Using the Trigger Map to trigger builds

Abstract

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 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 with is_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.

Example 1. Using the wildcard

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

In this section: