Define a Gated Check-In Build to Validate Changes
When a developer checks in changes that break the build, the result can be a significant hassle for small teams. The cost to larger teams can be expensive as measured by lost productivity and schedule delays.
You can create a gated check-in build definition to guard some or all of your code base against this problem.
In this Topic
How Gated Check-In Builds Affect Your Team
Define a Gated Check-In Build
Guidelines for Settings on the Process Tab
How Gated Check-in Builds are Run
Automatically Run Gated Check-in Builds
Manually Run Gated Check-in Builds and Private Builds
How Gated Check-In Builds Affect Your Team
When a gated check-in build is created, changes that the developer submits are placed in a shelveset and automatically built in your build system. The build must be successful for the check-in process to be completed. For more information, see Check In Pending Changes that Are Controlled by a Gated Check-in Build.
If some of your users must bypass gated check-in, you can set the Override check-in validation by build permission to Allow for a group of your users. For more information, see Team Foundation Server Permissions.
Define a Gated Check-In Build
Required Permissions
To perform this procedure, your Edit Build Definition permission must be set to Allow. For more information, see Team Foundation Server Permissions.
To define a gated check-in build
In Team Explorer, click a team project.
On the Build menu, click New Build Definition.
The New Build Definition window appears with the General tab displayed.
In the Build definition name box, type a name.
On the Trigger tab, click Gated Check-in accept check-ins only if the submitted changes merge and build successfully.
Click the Workspace tab.
The Working folders table appears. This table lists the version control folders for the team project for which you are creating the build definition and maps them to local folders on the build agent.
The local folder on the build agent appears in the Build Agent Folder column. You can include the $(SourceDir) token to indicate that you want to download the files to the build agent's Sources subdirectory.
To copy an existing workspace to the list of working folders, click Copy Existing Workspace to open the Select a Workspace dialog box.
Tip
Make sure that any version control folder that you specify for this definition is not also specified in the Workspace tab of any other gated check-in build definitions. Otherwise, when a person checks in files to these folders, the system requires them to decide which build definition to queue.
Click the Process tab, and then set the build process parameters in a way that ensures that check-ins meet the specific code quality standards of your team.
For a large code base produced by a large team, you should balance this goal of validating code quality against the goal of avoiding unnecessary delays for your developers. For more information, see Guidelines for Settings on the Process Tab later in this topic.
Click the Build Defaults and Retention Policy tabs, and apply whatever settings are appropriate in each tab.
For more information, see Create a Basic Build Definition.
Guidelines for Settings on the Process Tab
To minimize the time that is required to process the build, you should consider following these guidelines when you specify values for the build process parameters on the Process tab.
Required node
Items to Build, Configurations to Build: If you leave this parameter empty, the default platform and configuration is used for each solution and project. To optimize performance, adhere to the following guidelines:
If a platform-configuration pair builds more quickly than other pairs, specify it in this parameter.
Specify as few platform-configuration pairs as possible.
Basic node
Automated Tests: If your code must pass certain tests to be valid, set up a test run to run these tests. When you set up the test run, make sure that you filter by either categories or priority so that you are running only the tests that you need most. For more information, see Define a Build Using the Default Template.
Clean Workspace: Set this value to None (recommended) or Outputs. However, some types of defects are more likely to be missed if the workspace is not cleaned. For more information, see Define a Build Using the Default Template.
Perform Code Analysis: Set this value to Never.
Source and Symbol Server Settings, Index Sources: Set this value to False.
Advanced node
Agent Settings
Name Filter or Tags Filter: Use either a build agent name or a tag to bind this build definition to a build agent that is designed specifically for running this build. The build agent should run on a build machine with hardware that is sufficiently powerful to process this build quickly enough to meet your team's performance expectations.
For example, developers on your team might not mind waiting 15 minutes for the build to finish. But your developers are not likely to accept having to wait eight hours before they can determine whether their code has successfully checked in.
Maximum Execution Time: Set this value to a reasonably small number for continuous integration builds. For example, 15 minutes might work for your team, but eight hours is probably too long.
Copy Outputs to Drop Folder: The system takes this value as False, even if you set it to True.
Create Work Item on Failure: The system takes this value as False, even if you set it to True.
Label Sources: Set this value to False.
For more information about how to set the values of build process parameters, see Define a Build Using the Default Template.
How Gated Check-in Builds are Run
Each gated check-in build definition can have only one running build at a time. Therefore, large and active teams are more likely to develop a large queue of gated check-in builds. The following best practices can help your team avoid blocking progress:
Dedicate a build machine that has powerful hardware (for example, a fast processor and a fast hard disk) to the build agent that your gated check-in build definition uses.
Define the build so that the build agent does only the work that is required to validate the quality of code that is being checked in. For more information, see Guidelines for Settings on the Process Tab earlier in this topic.
Gated check-in builds can be run either run automatically or manually.
Automatically Run Gated Check-in Builds
A gated check-in build is run automatically when either of the following events occur:
A build has been defined with the Gated Check-in check box selected on the Trigger tab of the build definition.
Someone attempts to check in one or more changes that intersect with any of the mapped folders in the Workspace tab of the build definition.
Manually Run Gated Check-in Builds and Private Builds
Developers who want to feel more confident about the changes that they are checking in can manually queue a build of a shelveset. When they take this approach, they can specify one of two options for what the system does next if the build succeeds:
System checks in the changes (manual gated check-in build): This option can be handy for developers who want to validate their code before checking in but who work on a team that does not use the gated check-in trigger.
System does not check in the changes (private build): Developers can use this option when they want to validate some changes in a shelveset but not check them in.
For more information, see Queue a Build.