Build triggers in the bitrise.yml file

Abstract

On Bitrise, you can create triggers (or webhooks) for events such as code push or pull requests to start a build automatically.

You can trigger builds on Bitrise by registering a webhook at your source code hosting provider and configuring a build trigger. Each app with build triggers has its own trigger map in its bitrise.yml file. The trigger map defines the build triggers, including their type and trigger conditions.

The trigger map is essentially a list of filters: every trigger is a filter item that matches a certain case. If a case is matched, a build is triggered. Every trigger must include at least one condition.

Overview of the trigger map

The trigger map is defined in a trigger_map property in the bitrise.yml file. A valid trigger map must have at least one trigger.

A trigger has three main elements:

The type of the trigger: push, pull_request, or tag.
The trigger condition. For example, the source branch of a pull request.
The Workflow or Pipeline to be triggered.

One trigger means one build: a single trigger can only trigger a single Workflow or Pipeline. You can chain Workflows together run several Workflows in succession from a single trigger.

Below is a single trigger that triggers a build with the primary Workflow when a pull request is opened from any branch.

trigger_map:
- pull_request_source_branch: "*"  
  type: pull_request  
  workflow: primary

Multiple trigger conditions

If you define multiple trigger conditions in a single item then all conditions have to match in order to trigger a build. For example:

trigger_map:
- pull_request_target_branch: "main"
  pull_request_source_branch: "develop"
  type: pull_request
  workflow: primary

This will only select the primary workflow if the pull request’s source branch is develop AND the target branch is main.

Order of triggers

The order of the triggers is important: the first trigger with matching conditions will trigger a build. For example, let's say you have two code push triggers:

trigger_map:
- type: push
  push_branch: main
  workflow: primary
- type: push
  commit_message: deploy
  workflow: deploy

The first trigger triggers the primary Workflow if code is pushed to the main branch of the app's repository.

The second trigger triggers the deploy Workflow if a commit with the commit message deploy is pushed to any branch of the repository.

What happens when a commit is pushed to the main branch with the commit message deploy? The commit matches all conditions of the first trigger so the primary Workflow is triggered. In this scenario, the deploy Workflow is NOT triggered, even though the commit matches all conditions of that trigger, too.

Wildcards and regex

We support wildcards (*) for simple text matching within 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 in the following format:

trigger_map:
- type: push
  push_branch:
    regex: <regular expression>
  workflow: primary
- type: pull_request
  pull_request_source_branch:
    regex: <regular expression>

Components of the trigger map

The trigger_map property of accepts the values listed in the tables below.

Table 1. Components for all trigger types

Component	Description	Accepted values	Default value
`type`	The type of the trigger. A trigger with a given type only accepts trigger conditions belonging to that type.	`push` `pull_request` `tag`	N/A
`enabled`	A boolean property that defines if the trigger is currently active.	`true` `false`	`true`
`workflow` or `pipeline`	The Workflow or Pipeline that is triggered. You can't set both.	The exact name of the Workflow or Pipeline.	N/A

Table 2. Components for code push triggers

Component	Description	Default value
`push_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
`pull_request_source_branch`	The branch of from which the pull request is opened.	`*`
`pull_request_target_branch`	The branch which is the merge target of the pull request.	`*`
`pull_request_label`	The pull request label.	`*`
`draft_pull_request_enabled`	A boolean property that defines if draft pull requests trigger builds.	`true`

In this section: