Specify Build Triggers and Reasons

  • Article

You can manually queue a build whenever necessary, but your team’s needs will, in most cases, be best met by build processes that are defined with automatic triggers. When a build is triggered, a specific reason is recorded in the Reason property. This topic describes and explains how to use all the available build triggers and build reasons when you develop your build process.

  • Use Build Triggers to Accomplish Team Goals

    • Protect your team from build breaks

    • Maintain quality by using continuous integration

    • Check product quality by running nightly BVTs

  • Use Automatic Build Triggers

    • Use the Continuous Integration trigger to queue a build when a change is checked in

    • Use the Rolling builds trigger to queue a build when a change is checked in but with limits on how often a build is run

    • Use the Gated Check-in trigger to queue a build when a team member attempts to check in a change, and block the change if the build fails

    • Use the Schedule trigger to queue a build on a regular interval

  • Manually Queue a Build

    • Queue a build

    • Queue a private build

  • Use Custom Code to Queue a Build

  • Work with Build Triggers and Reasons

Use Build Triggers to Accomplish Team Goals

Protect your team from build breaks

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 use the Gated Check-in trigger to guard some or all of your code base against this problem.

Maintain quality by using continuous integration

Continuous integration is the process of integrating your code into a shared repository as frequently as possible. During code integration, a build break or a test failure can inform you, in a timely manner, of an error in your code. You can use the Continuous Integration trigger to implement continuous integration. The Rolling builds trigger is similar to the Continuous Integration trigger and can be useful if you do not have a sufficiently powerful build system to run a build every time that a check-in occurs.

The Gated Check-in trigger can serve as an even more rigorous approach to continuous integration. The Continuous Integration trigger alerts your team to problems such as build breaks or failed core unit tests, but the Gated Check-in trigger blocks these kinds of problems from being introduced into your codebase.

For more information about how to use your build system to support continuous integration, see Define a Build Process to Support Continuous Integration and Build and Deploy Continuously.

Check product quality by running nightly BVTs

You can schedule regular test runs to evaluate the quality of your build. These tests are often called build verification tests (BVTs) or smoke tests. These tests typically consist of a broad suite of tests that are used to verify key areas of an application in a particular build. You can use the Schedule trigger to implement a nightly BVT run.

For information about the Schedule trigger, see Use Schedule to queue a build on a regular interval. For more information about how to set up a BVT process, see How to: Configure and Run Scheduled Tests After Building Your Application.

Use Automatic Build Triggers

You must specify a build trigger for your build definition. In most cases, you will want your build process to run automatically. You can select one of the automatic triggers that this section describes.

Use the Continuous Integration trigger to queue a build when a change is checked in

If you define a build with the Continuous Integration trigger, the build is queued every time that a team member checks in a change. The build definition Workspace determines which files trigger the build definition. For more information about build workspaces, see Work with Build Workspaces.

Builds that are triggered by Continuous Integration are assigned a Reason of IndividualCI.

Use the Rolling builds trigger to build multiple check-ins together at a regular interval

If you define a build with the Rolling builds trigger, the build system queues a build of each check-in as long as the build is not running. If the build is running, the system waits until the build is completed and then queues another build of all check-ins that have not yet been built. You can also limit the frequency of builds if you select the Build no more often than everyn minutes check box and type an integer value between 0 and 2147483647.

For example, you might have only one build agent, and it might finish your build every 20 minutes. If you use the Continuous Integration trigger and your team checks in code nine times between 10 A.M. and 11 A.M., the last check-in might not be built until 1 P.M. However, if you use the Rolling builds trigger and specify 60 minutes as the interval, the same set of check-ins might be built by 11:20 A.M.

The build definition Workspace determines which files trigger the build definition. For more information about build workspaces, see Work with Build Workspaces.

Builds that are triggered by Rolling builds are assigned a Reason of BatchedCI.

Use the Gated Check-in trigger to queue a build when a team member tries to check in a change and to block the change if the build fails

If you define a build with the Gated Check-in trigger, changes that a team member submits to the version-control system are placed in a shelveset and queued to be built. The build must be successful for the check-in process to be completed. The build definition Workspace determines which files are controlled by the build definition. For more information about build workspaces, see Work with Build Workspaces.

Builds that are triggered by Gated Check-in are assigned a Reason of CheckInShelveset.

For more information about how to implement the Gated Check-in trigger, see Define a Gated Check-In Build Process to Validate Changes. For more information about how this kind of build definition affects your team, see Check in to a Folder that is Controlled by a Gated Check-in Build Process.

Use the Schedule trigger to queue a build on a regular interval

Schedule trigger

If you define a build with the Schedule trigger and clear the Build even if nothing has changed since the previous build check box, a build is queued on those days and at those times that you specify if changes have been checked in since the most recent run of this build definition. The build is queued regardless of whether the changes were associated with the last good build.

Builds that are triggered in this way are assigned a Reason of Schedule.

Tip

If you are developing a custom build process template and you select Schedule as a value in the Reason property of an InvokeForReason section of your template, in most cases you should probably also select ScheduleForced.

Schedule trigger (Reason: ScheduleForced)

If you define a build with the Schedule trigger and select the Build even if nothing has changed since the previous build check box, a build is queued on those days and at those times that you specify. The build is queued regardless of whether changes were checked in.

Builds that are triggered in this way are assigned a Reason of ScheduleForced.

Tip

If you are developing a custom build process template and you select ScheduleForced as a value in the Reason property of an InvokeForReason section of your template, in most cases you should probably also select Schedule.

Manually Queue a Build

In certain situations, you may have a build process that you do not want to run automatically.

  • Your build definition may not be ready for automatic runs because it is still under development.

  • You might have a special build process that you want to run only manually.

In these situations, you can select the Manual trigger. The build definition will be run only when a team member queues it manually.

Queue a build

You can manually queue any build definition, even if it is defined with a build trigger other than Manual. When you manually queue a build, the Reason is set to Manual. For more information about how to manually queue a build, see Queue a Build.

Queue a private build

If you want to build changes that you have put into a shelveset, you can use a private build (also known as a "buddy build") to validate changes to your code before you check it in. When you manually queue a private build, the Reason is set to ValidateShelveset. For more information about how to queue a private build, see Queue a Build.

Use Custom Code to Create a Completed Build

You can develop custom code that creates a completed build by leveraging classes in the Microsoft.TeamFoundation.Build namespace. When a build is queued in this manner, the Reason is set to UserCreated. For more information, see Extending Team Foundation: Build

Work with Build Triggers and Reasons

You can leverage triggers and reasons in your build process in the following ways:

  • Set the trigger for your build process: In your build definition, click the Trigger tab, and then select the trigger that best meets the needs of your team. For more information about how to create a build definition, see Create a Build Definition.

  • Define which build reasons are accepted by a custom build process: You can use the InvokeForReason activity to enclose a segment of your build process that you want to run only in builds that have been run for a particular reason. For more information, see Team Foundation Build Activities: InvokeForReason.