YAML syntax for build 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.
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 therelease
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
Component |
Description |
Accepted values |
Default value |
---|---|---|---|
|
Defines the type of a trigger. The trigger conditions of a target-based trigger are children of these elements. |
N/A |
N/A |
|
A boolean property that defines if the trigger is currently active. |
|
|
Component |
Description |
Default value |
---|---|---|
|
The branch of the repository where code is pushed to trigger a build. |
|
|
The commit message to trigger a build. |
|
|
The path to a file or folder where changes should trigger a build. |
|
Component |
Description |
Default value |
---|---|---|
|
The branch of from which the pull request is opened. |
|
|
The branch which is the merge target of the pull request. |
|
|
The pull request label. |
|
|
A boolean property that defines if draft pull requests trigger builds. |
|
|
A comment posted on a pull request. |
|
|
A specific commit message in pushes to a pull request. |
|
|
Specific files that are modified in a pull request. |
|
Component |
Description |
Default value |
---|---|---|
|
The value of the tag. Accepts a string value or a |
|