Skip to main content

YAML syntax for build triggers

Abstract

The configuration YAML files contain the definitions for build triggers. You can configure them directly in YAML without having to use the online Workflow Editor.

Existing trigger configurations

This page details information about target-based build triggers, defined within a Workflow or a Pipeline. We recommend this approach for all new users as it offers a more granular and flexible build trigger system.

Existing configurations might use legacy, project-based triggers. Read more about them: Legacy project-based triggers.

The configuration YAML files contain the definitions for build triggers. You can configure them directly in YAML without having to use the online Workflow Editor.

Trigger syntax

Triggers must be included in a triggers element within a Workflow or Pipeline. A valid trigger in the triggers element includes the type of the trigger and at least one trigger condition.

For example, the below trigger launches a build when code is pushed to the release branch.

workflows:
  pipeline-tests:
    triggers:
      push:
      - branch: "release"

Multiple matching triggers

We parse all triggers in a configuration YAML and start builds with all matching triggers. This means the order of the triggers doesn't matter.

For example, if you have two Workflows with push triggers with the same branch condition, both will be triggered when a commit is pushed to that branch. In the configuration below, both triggers will launch a build if a commit is pushed to the release branch:

  • The pipeline-tests Workflow specifies the release branch.

  • The pipeline-build Workflow uses a wildcard so any commit triggers a build with it.

workflows:
  pipeline-tests:
    triggers:
      push:
      - branch: "release"
    [...]
  pipeline-build:
    triggers:
      push: 
      - branch: "*"

Multiple trigger conditions

If you define multiple trigger conditions, all of them must match to trigger a build. In the example below, a build will be triggered if:

  • A commit is pushed to the release branch.

  • Certain files have changed in the commit.

workflows:
  pipeline-builds:
    triggers:
      push:
      - branch: release
        changed_files:
          - path/to/library-a/**

Wildcards and regex

We support wildcards (*) for simple text matching within all types of triggers. Wildcards are a good choice when you don't need the advanced pattern matching capabilities of regular expressions. For example, a trigger based on commit messages starting with fix can be achieved using a wildcard.

Wildcards are useful to match specific, fixed values appearing in the input. We recommend using regexes are needed when multiple alternative values, negation, capturing specific groups of characters or specific character types (for example, numbers only) are needed.

To use regular expressions for a trigger condition, you need to add regex: to its value:

workflows: 
  deploy:
    triggers:
      tag:
      - name:
          regex: '^\d\.\d\.\d$'
      pull_request:
      - comment: "[workflow: deploy]"
        commit_message:
          regex: '.*\[workflow: deploy\].*'

Trigger components

Table 1. Components for all trigger types

Component

Description

Accepted values

Default value

pull request

push

tag

Defines the type of a trigger. The trigger conditions of a target-based trigger are children of these elements.

N/A

N/A

enabled

A boolean property that defines if the trigger is currently active.

  • true

  • false

true


Table 2. Components for code push triggers

Component

Description

Default value

branch

The branch of the repository where code is pushed to trigger a build.

*

commit_message

The commit message to trigger a build.

*

changed_files

The path to a file or folder where changes should trigger a build.

*


Table 3. Components for pull request triggers

Component

Description

Default value

source_branch

The branch of from which the pull request is opened.

*

target_branch

The branch which is the merge target of the pull request.

*

label

The pull request label.

*

draft_enabled

A boolean property that defines if draft pull requests trigger builds.

true

comment

A comment posted on a pull request.

*

commit_message

A specific commit message in pushes to a pull request.

*

changed_files

Specific files that are modified in a pull request.

*


Table 4. Components for tag triggers

Component

Description

Default value

name

The value of the tag. Accepts a string value or a regex property.

*