Using the Trigger Map to trigger builds
On Bitrise, you can create triggers (or webhooks) for events such as code push or pull requests to start a build automatically.
When you register a webhook for an event or for multiple events (for example, for code push
and for pull request
events), your source code hosting service will call the webhook every time the related event happens.
On bitrise.io these webhook calls are called triggers, and can be mapped to different Workflows, or not mapped at all. If you don’t map a trigger to any Workflow, then bitrise.io won’t start a build. If you map it to a Workflow, then a build will be started with the selected Workflow.
In the following examples, we’ll use a very simple Bitrise configuration (bitrise.yml
), which does nothing else just prints the selected Workflow’s ID:
What is the bitrise.yml file
The bitrise.yml
file is the representation of your app’s configuration in YAML format. You can:
-
Edit the file locally and store it in your repository.
-
Edit the file on the bitrise.yml tab of the Workflow Editor on bitrise.io.
-
Update your Steps and Workflows on the graphical UI of the Workflow Editor. All changes will be reflected in the
bitrise.yml
file.
--- format_version: 1.3.0 default_step_lib_source: https://github.com/bitrise-io/bitrise-steplib.git trigger_map: - push_branch: "*" workflow: primary - pull_request_target_branch: "*" pull_request_source_branch: "*" workflow: primary - tag: "*" workflow: primary workflows: primary: steps: - script: inputs: - content: |- #!/bin/bash echo "$BITRISE_TRIGGERED_WORKFLOW_ID"
The above example bitrise.yml
will select the primary Workflow for every code push (push_branch: "*"
), tag push (tag: "*"
) and for every pull request (pull_request_target_branch:
"*"
& pull_request_source_branch: "*"
).
Components of the Trigger Map
A trigger_map
is a list of filters, and the workflow
is the given filters it should select in case of a matching trigger. Every filter item has to include at least one condition!
This means that you can’t have an item which only specifies the workflow
, at least one filter (push_branch
/ pull_request_source_branch
/ pull_request_target_branch
/ tag
) has to be specified!
The available filters:
-
push_branch
: A filter which is matched against code push events’ branch parameter. -
pull_request_source_branch
: A filter which is matched against Pull Request events’ source branch parameter (the branch the pull request was started from). -
pull_request_target_branch
: A filter which is matched against Pull Request events’ target branch parameter - the branch the pull request will be merged into. -
tag
: A filter which is matched against Tag Push events’ tag (name) parameter. -
pattern
: DEPRECATED - this filter was used for both code push and pull request events, in combination withis_pull_request_allowed
. This filter is now deprecated, as the new filters allow better control over event mapping.
One trigger = one build
One trigger can only select a single Workflow / can only start a single build. The first item which matches the trigger will select the Workflow for the build!
The order of the items also matters:
trigger_map: - push_branch: "*" push_branch: "master*" workflow: primary
By specifying a push_branch: master
item after a push_branch: "*"
item, the push_branch: master
would never be selected as every code push event would match push_branch: "*"
first, and the first item which matches the
trigger will select the Workflow for the build!
If you define multiple filters in a single item then all filters have to match in order to select that item’s workflow. For example:
trigger_map: - pull_request_target_branch: "master" pull_request_source_branch: "develop" workflow: primary
This will only select the primary
workflow if the pull request’s source branch is develop
AND the target branch is master
.
If you want to specify filters which should be treated separately, for example, to select primary
for pull requests where the source is develop
, as well as select for the ones which target master
:
trigger_map: - pull_request_target_branch: "master" workflow: primary - pull_request_source_branch: "develop" workflow: primary
Can't mix filters in the same item
You can’t mix and match push_branch
, tag
and the pull_request
filters in the same item. This would effectively mean that the workflow should be selected if the event is a code push and a pull request (or tag push) event at the same time. This is
simply not possible, source code hosting services send separate webhooks for pull request (pre-merge state), tags and for code push events. A single webhook event will never be code push, tag push and pull request at the same time, a single webhook is always related to only one type (code push, tag push or pull request).
Building a single branch
If you want to build only a single branch for every code push, but for nothing else (no push to any other branch should trigger a build, nor any pull request or tag), then all you have to do is to specify a trigger_map
which does not map anything else to any Workflow, only the branch you want to
build.
For example, if you only want to build the master
branch on code push:
trigger_map: - push_branch: master workflow: primary
Or if you only want to build feature/
branches:
trigger_map: - push_branch: feature/* workflow: primary
Or the two together:
trigger_map: - push_branch: master workflow: primary - push_branch: feature/* workflow: primary
This configuration will start a build for every code push which happens on either master
or on a feature/
branch, and will use the same Workflow for both (primary
).
If you want to use a different Workflow for your master
branch, then all you have to do is to change the workflow:
for that trigger map item:
trigger_map: - push_branch: master workflow: deploy - push_branch: feature/* workflow: primary
This configuration will use the Workflow deploy
for every code push on master
, and the Workflow primary
for every code push on feature/
branches, and will not start a build for anything else.
Using wildcards in the trigger map
When you create a trigger map, you don't have to specify exact branch names: you can use wildcards to match patterns. Bitrise uses a simplified version of the glob syntax for this: you can use *
as a wildcard. You can use multiple sections of *
but other pattern matching features aren't supported.
Wildcards on the UI
All examples below show how the trigger map looks like in the bitrise.yml
file of the app. However, you can use wildcards on the Triggers tab of the Workflow Editor in the same way: Triggering builds automatically
Trigger the primary
Workflow any time code is pushed to a branch that contains the string dev
anywhere in its name:
trigger_map: - push_branch: "*dev*" workflow: primary
Trigger the primary
Workflow any time a pull request is opened to a branch that contains both dev
and feature
anywhere in its name, with anything in between the two strings:
trigger_map: - pull_request_source_branch: "*" pull_request_target_branch: "*dev*feature*" workflow: primary
Trigger the primary
Workflow any time a commit is pushed with a Git tag that ends in v1.0
:
- tag: "*v1.0" workflow: primary