YAML syntax for build triggers

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. We recommend using the pattern property to achieve this:

my_awesome_workflow
  triggers:
    push:
      - branch: main
      - commit_message:
          pattern: "hello"

Alternative syntax

You can also add your wildcard pattern right next to the commit_message field: commit_message: "hello". We’ll continue to support this syntax.

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

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.	*
last_commit	A boolean property that defines whether Bitrise should evaluate every commit message or changed file in a code push or only those belonging to the most recent commit.	false

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

Component	Description	Default value
name	The value of the tag. Accepts a string value or a regex property.	*