Build definition triggers

Last Update: 4/26/2017

Team Services | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

On the Triggers tab you specify the events that will trigger the build. You can use the same build definition for both CI and scheduled builds.

Continuous integration (CI)

Select this trigger if you want the build to run whenever someone checks in code.

Batch changes

Select this check box if you have a lot of team members uploading changes often and you want to reduce the number of builds you are running. If you select this option, when a build is running, the system waits until the build is completed and then queues another build of all changes that have not yet been built.

If you are using batched changes, you can also specify a maximum number of concurrent builds per branch.

You can batch changes when your code is in Git in the team project or on GitHub. This option is not available if your code is in a remote Git repo or in Subversion.

Git filters

If your repository is Git then you can specify the branches where you want to trigger builds. You can use wildcard characters.

Path filters in Team Services and Team Foundation Services (TFS)

If your Git repo is in Team Services or TFS, you can also specify path filters to reduce the set of files that you want to trigger a build.

Tips:

  • If you don't set path filters, then the root folder of the repo is implicitly included by default.
  • When you add an explicit path filter, the implicit include of the root folder is removed. So make sure to explicitly include all folders that your build needs.
  • If you exclude a path, you cannot also include it unless you qualify it to a deeper folder. For example if you exclude /tools then you could include /tools/trigger-runs-on-these
  • The order of path filters doesn't matter.

Example

For example, you want your build to be triggered by changes in master and most, but not all, of your feature branches. You also don't want builds to be triggered by changes to files in the tools folder.

Team Services

ci trigger git branches

TFS 2017 Update 1 and older versions

ci trigger git branches

TFVC Include

Select the version control paths you want to include and exclude. In most cases, you should make sure that these filters are consistent with your TFVC mappings on the Repository tab.

CI trigger for a remote Git repo or Subversion

You can also select the CI trigger if your code is in a remote Git repo or Subversion. In this case we poll for changes at a regular interval. For this to work, Team Services or your Team Foundation Server must be able to resolve the network address of the service or server where your code is stored. For example if there's a firewall blocking the connection, then the CI trigger won't work.

Scheduled

Select the days and times when you want to run the build.

If your repository is Git, GitHub, or External Git, then you can also specify branches to include and exclude. You can use wildcards.

Example: Nightly build of Git repo in multiple time zones

Team Services

scheduled trigger multiple time zones

TFS 2017 Update 1 and older versions

scheduled trigger multiple time zones

Example: Nightly build with different frequencies

Team Services

scheduled trigger different frequencies

TFS 2017 Update 1 and older versions

scheduled trigger different frequencies

TFVC gated check-in

If your code is in a Team Foundation version control (TFVC) repo, use gated check-in to protect against breaking changes.

By default Use workspace mappings for filters is selected. Builds are triggered whenever a change is checked in under a path specified in your mappings on the repository tab.

Otherwise, you can clear this check box and specify the paths in the trigger.

How it affects your developers

When a developers try to check-in, they are prompted to build their changes.

Gated check-in prompt

The system then creates a shelveset and builds it.

For details on the gated check-in experience, see Check in to a folder that is controlled by a gated check-in build process.

Option to run CI builds

By default, CI builds are not run after the gated check-in process is complete and the changes are checked in.

However, if you do want CI builds to run after a gated check-in, select the Run CI triggers for committed changes check box. When you do this, the build process does not add ***NO_CI*** to the changeset description. As a result, CI builds that are affected by the check-in are run.

A few other things to know

  • Make sure the folders you include in your trigger are also included in your mappings on the Repository tab.

  • You can run gated builds on either a hosted agent or a windows agent. You cannot run them on the cross-platform agent.

Q&A

How do I protect my Git codebase from build breaks?

If your code is in a Git repo on Visual Studio Team Services or Team Foundation Server, you can create a branch policy that runs your build. See Improve code quality with branch policies. This option is not available for GitHub repos.

My build didn't run. What happened?

If your build is in Team Services, then at least one of your users must sign in regularly for CI and scheduled builds to run. Your Team Services account goes dormant five minutes after the last user signed out. After that, each of your build definitions will run one more time.

For example, while your account is dormant:

  • A nightly build of code in your Team Services account will run only one night until someone signs in again.

  • CI builds of an external Git repo will stop running until someone signs in again.

Can I chain builds so that one build triggers another?

Not yet. See User Voice: Provide build configuration dependencies in TFS Build.

Do I need a build agent?

You need at least one agent to run your build. Get an agent.

I can't select a default agent queue and I can't queue my build. How do I fix this?

See queues.

I use Team Foundation Server on-premises and I don't see some of these features. Why not?

Some of these features are available only on Visual Studio Team Services and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.