Build pipeline triggers

Azure Pipelines | Azure DevOps Server 2019 | TFS 2018 | TFS 2017 | TFS 2015

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

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

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*

In addition to specifying branch names in the branches lists, you can also configure triggers based on tags by using the following format:

trigger:
  branches:
    include:
      refs/tags/{tagname}
    exclude:
      refs/tags/{othertagname}

If you don't specify any triggers, the default is as if you wrote:

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

When you specify a trigger, this default no longer applies.

Tags

In addition to specifying tags in the branches lists as covered in the previous section, you can directly specify tags to include or exclude:

# specific branch build
trigger:
  tags:
    include:
    - v2.*
    exclude:
    - v2.0

If you don't specify any tag triggers, then by default, tags will not trigger pipelines.

Batching CI builds

If you have a lot of team members uploading changes often, you may 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

Paths

You can specify file paths to include or exclude.

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

When you specify paths, you also need to explicitly specify branches or tags to trigger on.

Opting out of CI builds

Disabling the CI trigger

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

# A pipeline with no CI trigger
trigger: none

Important

When you push a change to a branch, the YAML file in that branch is evaluated to determine if a CI build should be run.

For more information, see Triggers in the YAML schema.

Skipping CI for individual commits

You can also tell Azure Pipelines to skip running a pipeline that a commit would normally trigger. Just include ***NO_CI*** in the commit message of the HEAD commit and Azure Pipelines will skip running CI. This is supported for commits to Azure Repos Git and GitHub.

You can also tell Azure Pipelines to skip running a pipeline that a commit would normally trigger. Just include [skip ci] in the commit message or description of the HEAD commit and Azure Pipelines will skip running CI. You can also use any of the variations below. This is supported for commits to Azure Repos Git, Bitbucket Cloud, GitHub, and GitHub Enterprise Server.

  • [skip ci] or [ci skip]
  • skip-checks: true or skip-checks:true
  • [skip azurepipelines] or [azurepipelines skip]
  • [skip azpipelines] or [azpipelines skip]
  • [skip azp] or [azp skip]
  • ***NO_CI***

YAML builds are not yet available on TFS.

Pull request validation

Note

New pipelines automatically override YAML PR triggers with a setting in the UI. To opt into YAML-based control, you need to disable this setting on the Triggers tab in the UI.

Important

YAML PR triggers are only supported in GitHub and Bitbucket Cloud. If you are using Azure Repos Git, you can configure a branch policy for build validation in order to trigger your build pipeline for validation.

Important

YAML PR triggers are only supported in GitHub. If you are using Azure Repos Git, you can configure a branch policy for build validation in order to trigger your build pipeline for validation.

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/*

PR triggers will fire for these branches once the pipeline YAML file has reached that branch. For example, if you add master in a topic branch, PRs to master will not start automatically building. When the changes from the topic branch are merged into master, then the trigger will be fully configured.

If no pr triggers appear in your YAML file, pull request builds are automatically enabled for all branches.

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 specify whether additional pushes to a PR should cancel in-progress runs for the same PR. The default is true.

# auto cancel false
pr:
  autoCancel: false
  branches:
    include:
    - master

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

# no PR builds
pr: none

Important

When you create a pull request, or push a change to the source branch of a PR, the YAML file in the source branch is evaluated to determine if a PR build should be run.

For more information, see PR trigger in the YAML schema.

YAML builds are not yet available on TFS.

Trigger builds using GitHub pull request comments

If your team uses GitHub pull requests, you can manually trigger pipelines using pull request comments. See details here.

Scheduled

Scheduled builds are not yet supported in YAML syntax. After you create your YAML build pipeline, you can use pipeline settings 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 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 you 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 Other Git repo will stop running until someone signs in again.

The YAML file in my branch is different than the YAML file in my master branch, which one is used?

When you have configured a CI trigger or a PR trigger, the YAML file that is in the branch being pushed is used.

  • For CI triggers, the YAML file that is in the branch you are pushing is evaluated to see if a CI build should be run.
  • For PR triggers, the YAML file that is in the source branch of the PR is evaluated to see if a PR build should be run.

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.