Using the Trigger Map to trigger builds
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 branch for every code push (push_branch: "*"
), tag push (tag: "*"
) and for every pull request (pull_request_target_branch:
"*"
& pull_request_source_branch: "*"
).
This configuration will start a build with the primary Workflow for every code push, but for nothing else (for example not for pull requests).
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.