Build pipeline triggers

Azure Pipelines | TFS 2018 | TFS 2017 | TFS 2015 | Previous versions (XAML builds)

Note

In Microsoft Team Foundation Server (TFS) 2018 and previous versions, build and release pipelines are called definitions, service connections are called service endpoints, stages are called environments, and jobs are called phases.

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

Continuous integration (CI)

YAML builds are configured by default with a CI trigger on all branches.

You can control which branches get CI triggers with a simple syntax:

trigger:
- master
- releases/*

You can specify the full name of the branch (for example, master) or a prefix-matching wildcard (for example, releases/*). You cannot put a wildcard in the middle of a value. For example, releases/*2018 is invalid.

You can specify branches to include and exclude. For example:

# specific branch build
trigger:
  branches:
    include:
    - master
    - releases/*
    exclude:
    - releases/old*

If you have a lot of team members uploading changes often, then you might want to reduce the number of builds you're running. If you set batch to true, when a build is running, the system waits until the build is completed, then queues another build of all changes that have not yet been built.

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - master

You can specify file paths to include or exclude.

# specific path build
trigger:
  branches:
    include:
    - master
    - releases/*
  paths:
    include:
    - docs/*
    exclude:
    - docs/README.md

You can opt out of CI builds entirely by specifying trigger: none.

# a build with no CI
trigger: none

YAML builds are not yet available on TFS.

Pull request validation

Unless you specify pr triggers in your YAML file, pull request builds are automatically enabled for all branches. You can specify the target branches for your pull request builds. For example, to run pull request builds only for branches that target: master and releases/*:

pr:
- master
- releases/*

You can specify the full name of the branch (for example, master) or a prefix-matching wildcard (for example, releases/*). You cannot put a wildcard in the middle of a value. For example, releases/*2018 is invalid.

You can specify branches to include and exclude. For example:

# specific branch build
pr:
  branches:
    include:
    - master
    - releases/*
    exclude:
    - releases/old*

You can specify file paths to include or exclude. For example:

# specific path build
pr:
  branches:
    include:
    - master
    - releases/*
  paths:
    include:
    - docs/*
    exclude:
    - docs/README.md

You can opt out of pull request builds entirely by specifying pr: none.

# no PR builds
pr: none

YAML builds are not yet available on TFS.

Scheduled

Scheduled builds are not yet supported in YAML syntax. After your create your YAML build pipeline, you can use the designer to specify a scheduled trigger.

YAML builds are not yet available on TFS.

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 in the source repository settings.

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

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 pipeline 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

Build completion triggers

Build completion triggers are not yet supported in YAML syntax. After your create your YAML build pipeline, you can use the designer to specify a build completion trigger.

Q & A

How do I protect my Git codebase from build breaks?

If your code is in a Git repo on Azure Repos 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?

Someone must view a page in your organization regularly for CI and scheduled builds to run. It can be any page, including, for example, Azure Pipelines.

Your organization goes dormant five minutes after the last user signed out of Azure DevOps. After that, each of your build pipelines will run one more time. For example, while your organization is dormant:

  • A nightly build of code in your organization 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.

Do I need an agent?

You need at least one agent to run your build or release. Get an agent for Linux, macOS, or Windows.

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

See Agent pools.

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

Some of these features are available only on Azure Pipelines and not yet available on-premises. Some features are available on-premises if you have upgraded to the latest version of TFS.