How to utilize Team Foundation Server check-in policies

Applies to
ApexSQL Source Control

This article describes how to utilize Team Foundation Server check-in policies.

What are check-in policies?

Check-in policies are a set of rules (each policy as a single rule) that must be followed whenever a developer wants to check-in changes to a repository. Each policy that is previously set for the specific Team Foundation Server project requires a developer to take specific action prior to checking in changes. These policies are often set by the Team Foundation Server administrators.

Quick tip icon

Quick tip:

To add and manage the check-in policies, a Team Foundation Server user must have the Edit project-level information permission set to Allow. For more details on how to set this, check the Permissions and groups defined for Team Services and Team Foundation Server.

To add a check-in policy for the specific Team Foundation Server project, make sure you are connected to the Team Foundation Server in Visual Studio and click the Settings button from the Home tab in the Team Explorer pane:

Under the Team project settings, click the Source Control option:

Under the Source Control Settings dialog, switch to the Check-in Policy tab and add a policy that must be followed by each developer before checking-in changes:

The following are a description of check-in policy categories

Builds – requires a last build to be successful in order to check-in new changes

Changeset Comment Policy – requires a developer to specify a comment (commit message) before checking-in any changes

Custom Path Policy – scopes other policies to specific folders or file types (for example, policies can be applied to files that have .sql extension only, or to all files in the specific branch)

Forbidden Patterns Policy – prevents users from checking in files with forbidden filename patterns

Work Item Query Policy – allows users to specify a work item query whose results will be the only legal work items for a check-in to be associated with

Work items – This policy requires that one or more work items be associated with every check-in


Assuming that any of the shown policies are already specified for the Team Foundation Server project, let’s check how that can be utilized when checking-in changes using ApexSQL Source Control.

For our example, let’s have a sample database linked to a Team Foundation Server repository, specifically to a project where the previously mentioned policies are set. When linking a database to a Team Foundation Server, it is necessary to select the Check-in policy option in the first step of the Source control wizard:

Quick tip icon

Quick tip:

In case a database is already linked, or the Check-in policy option is not selected for any reason in the Source control wizard, it can be checked later, after the linking process is finished, in the add-in options.

To check the Check-in policy option for already linked database, select a SQL Server instance and a linked database from the drop-down list, in the add-in options, under the General tab, and check the Apply policy option:

This way, a developer is forced to perform any check-in in compliance with the specified policies.

Worked case

For example, let’s assume that Changeset Comment Policy and Work Items are set on the Team Foundation Server side. If the Check-in policy option is selected for the sample database, each check-in must be followed by the commit message and associated with at least one work item. In other words, each check-in without a comment and work item association will fail:

To illustrate this, let’s make a simple change in one of the tables in a sample database linked to a Team Foundation Server repository where the check-in policy is set. After making a change and refreshing the Action center tab, it is mandatory to provide a commit message in order for the check-in to be successful. Let’s try checking-in changes without a commit message, thus without associating a check-in with any work item, just by clicking the Apply button:

The following message appears:

Since the check-in does not meet the requirement, changes cannot be checked-in. To perform the check-in, all listed requirements must be covered. In this specific case, a commit message must be provided and a check-in must be associated with at least one work item.

Once the commit message is provided along with the work item association (we have associated with a work item which ID is 7), changes can be checked in:

After reloading the Action center tab, the following message is displayed:

This means that policy requirements are satisfied and changes are successfully checked-in. Similar to this example, any other policy requirement will be challenged before the check-in, as it needs to be satisfied in order for the check-in to complete successfully.

Q: Is the Check-in policy option dependent on Team Foundation Server project type?

A: No, the Check-in policy feature works the same regardless of the team project type.

When the option for the check-in policies is checked for the specific database, each check-in must comply with policies previously added for the selected Team Foundation Server project. For instance, if the policy enforce comments is set, a SQL database change cannot be checked in without specifying a check-in message. Otherwise, the add-in throws a warning and won’t allow checking-in changes.

Q: Is it possible for one user to have the policy option checked, while for another one the same option could be unchecked?

A: Yes, currently, the Check in policy option is left to the user to decide whether policies will be followed or overridden.

Q: Is it mandatory to comply with the check-in policy if it is disabled on the Team Foundation Server side?

A: No, there is no need to follow the check-in policy that is temporarily disabled on a Team Foundation Server side, even if the Check-in policy option is checked for the specific database in the add-in options.

Q: Is the Check-in policy option related to a single database or it is applied against all databases linked to the specific Team Foundation Server project?

A: The Check-in policy option is separate for each linked database and can be set independently, no matter if databases are linked to the same Team Foundation Server project.

Q: Is it possible to comply with specific check-in policies for the selected database?

A: No, this is not possible. When the Check-in policy option is checked for the specific database, the user must comply with all previously specified policies for the selected Team Foundation Server project.