Configuring Check-in Policies (Team Explorer Everywhere)

  • Article

You can use check-in policies to enforce development practices in your organization. Check-in policies are enforced when team members check in changes. If you try to check in pending changes that violate the policy, your check-in is blocked. If necessary, you can override these policies.

Important

Check-in policies that you define by using Team Explorer Everywhere only apply when you check in by using the Team Foundation Server plug-in for Eclipse or the Cross-platform Command-Line Client for Team Foundation Server. If you use another client, such as Team Web Access or Team Explorer in Visual Studio, these policies do not apply. Similarly, policies that you define by using Team Web Access or Team Explorer in Visual Studio are not applied when you check in by using the Team Foundation Server plug-in for Eclipse or the Cross-platform Command-Line Client for Team Foundation Server.

Check-in policies can require the user to take specific actions when they check in files to version control. For example, a user can be required to associate a work item with a changeset. By default, the following check-in policy types are available:

  • Builds: Requires that the last build was successful before a check-in.

    This policy does not queue a build. It verifies the results of the most recent build.

  • Changeset Comments: Requires users to provide a non-empty comment when they check in pending changes.

  • Forbidden Patterns: Prevents users from checking in files that have forbidden filename patterns in the server path of the change. You might do this to prevent changes to a section of your application.

  • Work Items: Requires that one or more work items is associated with the check-in.

  • Work Item Queries: Requires that each changeset is associated with one or more work items from a specified query.

In this topic

Required Permissions

To complete this procedure, you must have the Edit project-level information permission set to Allow. For more information, see the following page on the Microsoft Web site: Team Foundation Server Permissions.

Add Check-in Policies

  1. In Team Explorer, right-click the team project for which you want to define check-in policies and click Check-in Policies.

    The Check-in Policies dialog box appears.

  2. Click Add.

    The Add Check-in Policy dialog box appears.

  3. In the Check-in Policy list, specify the type of policy that you want to define and then click OK.

    • Specify Build Policy if you want to require that a previous build was successful before any new changes can be checked in.

    • Specify Changeset Comments Policy if you want to require that users provide a non-empty comment when they check in pending changes.

    • Specify Forbidden Patterns Policy if you want to prevent users from checking in files that have forbidden filename patterns in the server path of the change.

    • Specify Work Item Policy if you want to require that one or more work items is associated with each changeset.

    • Specify Work Item Query Policy if you want to require that each changeset is associated with one or more work items from the specified query.

    If you specified Build Policy, the Build Policy Settings dialog box appears. If you specified Work Item Query Policy, the Choose Your Query dialog box appears. If you specified Forbidden Patterns Policy, the Forbidden Patterns dialog box appears.

  4. If you specified Build Policy, perform the following tasks in the Build Policy Settings dialog box:

    1. On the General tab, specify the items that must build cleanly before a check-in is allowed.

      You can specify the pending file, the project that contains the pending file, or the entire workspace.

    2. (Optional) On the Markers tab, specify one or more Eclipse resource markers that, if found with the specified attributes, will prevent a check-in.

    3. Click OK.

  5. If you specified Work Item Query Policy, in the Choose Your Query dialog box, click the query that defines the list of work items that can be associated with a changeset, and then click OK.

  6. If you specified Forbidden Patterns, perform the following tasks in the Forbidden Patterns dialog box:

    1. In New Expression, type a regular expression that matches the server paths of changes that you want to disallow and then click Add.

    2. (Optional) Add expressions that you want to disallow.

      Note

      A pending change will violate the check-in policy if it matches any of the configured regular expressions.

    3. Click OK to save the set of expressions.

  7. If you want to add another check-in policy, repeat steps 2 through 5.

  8. Click OK to save your changes.

    All policies that you added will now be enforced.

Modify Check-in Policies

If you defined build or work item query check-in policies, you can modify the details of those check-in policies. Changeset comments and work item policies have no details that you can configure. You can remove those policies, but you cannot modify them. For more information, see Remove Check-in Policies.

  1. In Team Explorer, right-click the team project for which you want to define check-in policies and click Check-in Policies.

    The Check-in Policies dialog box appears.

  2. In the list, click the check-in policy that you want to modify.

  3. Click Edit.

  4. If you want to modify a Build Policy, perform the following tasks in the Build Policy Settings dialog box:

    1. On the General tab, specify the items that must build cleanly before a check-in is allowed.

      You can specify the pending file, the project that contains the pending file, or the entire workspace.

    2. (Optional) On the Markers tab, specify one or more Eclipse resource markers that, if found with the specified attributes, will prevent a check-in.

    3. Click OK.

  5. If you want to modify a Work Item Query Policy, in the Choose Your Query dialog box, click the query that defines the list of work items that can be associated with a changeset, and then click OK.

  6. Click OK to save your changes.

Enable or Disable Check-in Policies

If you want to temporarily remove a check-in policy but retain it for future use, you can disable it. You might do this, for example, if you have configured a complex build policy and do not want to have to re-create it later.

  1. In Team Explorer, right-click the team project for which you want to define check-in policies and click Check-in Policies.

    The Check-in Policies dialog box appears.

  2. In the Enabled column of the list, perform one or more of the following tasks:

    • Select the check box that corresponds to a check-in policy that you want to enable.

    • Clear the check box that corresponds to a check-in policy that you want to disable.

  3. Click OK to save your changes.

Remove Check-in Policies

If you want to temporarily remove a build check-in policy or a work item query check-in policy, you should consider disabling that policy instead of removing it. By disabling the policy, you retain the policy details and can re-enable that policy later.

  1. In Team Explorer, right-click the team project for which you want to define check-in policies and click Check-in Policies.

    The Check-in Policies dialog box appears.

  2. In the list, click the check-in policy that you want to remove.

  3. Click Remove.

  4. Click OK to save your changes.

Restrict the Scope of a Check-in Policy

In Team Explorer Everywhere, you can restrict the scope of a check-in policy to control to which files the policy applies. You can specify one or more regular expressions to limit a check-in policy so it is only applied to items that match any of the configured expressions. If no expressions are specified, the check-in policy is applied to all items in the team project.

Example Expressions

If you want to define a policy that applies to the following:

Specify this expression:

All files that end with .java

 
.*\.java$

All items in a project named Inventory

 
^\$/Inventory/.*

All items in a folder named Framework

 
.*/Framework/.*

You can test your scope expressions before you save them.

  1. In Team Explorer, right-click the team project for which you want to define check-in policies and click Check-in Policies.

    The Check-in Policies dialog box appears.

  2. In the list, click the check-in policy for which you want to specify a scope.

  3. Click Scope.

    The Scope Expressions dialog box appears.

  4. Perform one or more of the following tasks:

    • To add an expression, in New expression, type a regular expression and then click Add.

      The expression is added to the list of expressions in the Configured Expressions list.

    • To remove an expression from the Configured Expressions list, click the expression and then click Delete.

    • To test the set of expressions, in Type a full server path to check if policies will be evaluated for it, type the full path to an item on the server.

      For example, you might type $/AdventureWorks/main/billing-service/src/main/java/com/contoso/billingservice/ClassC.java. In Result, a message appears that indicates whether policies will be evaluated for the specified path. The message also indicates which regular expression matched the path.

  5. Click OK to save your changes.

See Also

Other Resources

Setting and Enforcing Quality Gates (Team Explorer Everywhere)