Use a gated check-in build process 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 even more expensive when measured by lost productivity and schedule delays. You can guard some or all of your code base against these problems by creating a gated check-in build definition.

Note

Gated check-in builds are available only in TFVC team projects. They are not available in Git team projects.

What do you want to do?

• Understand how gated check-in builds affect your team

• Define a gated check-in build process

• Guidelines to improve build process function and performance

• Avoid blocking your team

• Manually run gated check-in builds and private builds

How gated check-in builds affect your team

When your team puts a gated check-in build process in place, changes that the developers submit are placed in shelvesets and are automatically built and possibly tested by your build system.

The build must be successful for the check-in process to be completed. For more information, see Check in to a folder that is controlled by a gated check-in build process.

If some of your users must bypass the 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 Permission reference for Team Foundation Server.

Define a gated check-in build process

1. In Team Explorer, make sure you are connected to the team project (Keyboard: Ctrl + 0, C), and then open the Builds page (Keyboard: Ctrl + 0, B).

2. Choose the New Build Definition link or select a build, open its shortcut menu, and choose Edit Build Definition.

   Tip

   If a TF225001 error message appears, configure a build controller.

3. On the Trigger tab:

   • Choose Gated Check-in.

   • (Optional) To increase the efficiency of your build process, select Merge and build up to n submissions For more information, see Avoid blocking your team.

4. On the Source Settings tab, in the Working folders table, map the version-control folders that this build definition will control to local folders on the build agent.

   Tip

   Follow these guidelines:

   • To ensure that your build process functions correctly and to improve performance, include all folders—and only these folders—that contain files that your build process requires.

   • Make sure that you do not specify any version-control folder that is also specified on the Workspace tab of another gated check-in build definition. Otherwise, when a user checks in files to these folders, the build system requires them to decide which build definition to queue.

   • For more information about how to specify the mappings, see Work with build workspaces.

5. To improve performance, on the Build Defaults tab, choose This build does not copy output files to a drop folder.

6. On the Process tab, under Build, in the Projects parameter, specify the solutions or code projects that you want to build.

7. On the Process tab, set the parameters to ensure that check-ins meet the specific standards for code quality of your team without delaying your developers unnecessarily.

   For more information, see Improve build process function and performance later in this topic.

8. Specify build process options on the other tabs. For more information, see Create or edit a build definition.

Improve build process function and performance

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.

TF Version Control or Git

• Clean workspace or Clean repository: For faster performance, set this value to False. This setting might cause your team to miss some types of defects, such as those introduced during refactoring.

Build

• Configurations: 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.

• Clean build For faster performance, set this parameter to False. This setting might cause your team miss some types of defects, such as those introduced during refactoring.

Build, Advanced

• Perform Code Analysis: For faster performance, set this value to Never.

Test, Advanced

• Disable tests:

  • For faster performance, select True.

  • If your code must pass certain tests, select False, and then define a set of tests to run in the build. You can improve performance by running only the tests that you require. To designate those tests, filter them by either category or priority. For more information, see Run tests in your build process.

Publish Symbols

• Path to publish symbols: For faster performance, leave this value empty.

Advanced

• 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 hardware that is sufficiently powerful to process this build quickly enough to meet your team's performance expectations.

    For example, you and your team might not mind waiting 15 minutes for the build to finish. But you are not likely to want to wait eight hours before you can determine whether your code has successfully checked in.

  • Maximum Execution Time: Set this value to a reasonably small number. For example, 15 minutes might work for your team, but eight hours is probably too long.

For more information about Default Template build process parameters, see Use the Default Template for your build process.

Avoid blocking your team

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 you to avoid blocking team progress:

• To increase the efficiency of your build process on the Trigger tab, select the Merge and build up to n submissions option and specify the maximum number of check-ins you want to build together in any given batch. In general, you don't risk much disruption by using this option. Each check-in is individually committed or rejected.

  For example, if three check-ins are built together in a batch and the build does not succeed, the system queues individual builds of all three check-ins.

  However, this option presents some risk of one check-in interfering with others. This can occur, for example, if multiple check-ins modify the same file and a version control conflict occurs. In this case, the earlier check-in is committed and the later check-ins are rejected.

• 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.

• 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.

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 teams that do not want to require gated check-in but still want to enable developers to voluntarily validate their code before checking in.

• 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.