Triggering builds automatically

Abstract

You can configure automatic build triggers on Bitrise by specifying a trigger event and a Workflow. You can trigger builds from code pushes, pull requests or Git tags.

You can configure automatic build triggers on Bitrise by specifying a code event that should trigger a build and a destination Workflow that should run. You can define multiple triggers, and add new triggers or remove existing ones any time you wish.

There are three types of triggers:

Code push: code push to the specified branch of the app's repository triggers a build.
Pull request: specify source and/or destination branches where any pull request will trigger a build.
Git tag: a commit with a specific tag triggers a build.

You can manage the triggers in the Triggers section of the Workflow Editor or you can directly edit the bitrise.yml of your app to set them up. In this guide, we cover how to set up and manage triggers on the website UI.

For information on how to set up the triggers in YAML format, check out the relevant guide: Using the Trigger Map to trigger builds.

Trigger restrictions

By default, one trigger can trigger only one Workflow. If you need to trigger multiple Workflows from a single trigger, there is a couple of workarounds:

Chain Workflows together so they run after each other.
Use the Bitrise Start Build and the Bitrise Wait for Build Steps.

Also, you can't set up two different triggers for the same code event (for example, a code push) on the same branch (for example, main). The Workflow Editor will not allow you to save the configuration if you attempt to do so.

Triggering builds with code push

By creating a trigger on code push, you can configure Bitrise to automatically start a build every time code is pushed to your repository. You can specify both the branch of the repository and the Workflow that should run.

Webhooks for triggering builds

Triggering builds automatically requires an incoming webhook set up with the hosting service of your repository. Read more in the Webhooks section.

Open your app on bitrise.io.
Go to the Workflows tab.
Go to the Triggers tab.
Select the PUSH option.
Click + ADD TRIGGER.
In the PUSH BRANCH window, type in the name of the branch (for example, master. Make sure there are no spelling errors, otherwise the trigger won’t work.

Using patterns when specifying a branch or tag

The * symbol can be used in your configured triggers as a wildcard in branch or tag names. It can also be used in patterns. For example, the pattern *-dev can be used for any branches or tags with the suffix -dev. Please note that when there are multiple triggers, only the first matching trigger will start a workflow.

For more information on using wildcards, see: Using wildcards in the trigger map
Select the Workflow you wish to trigger (for example, primary).
Click Save in the top right corner.

You’re done! From now on, if code gets pushed to the selected branch of your app’s repository, Bitrise will trigger a build with the selected Workflow!

Triggering builds with pull requests

You can set up a trigger so that every time a pull request is opened from a specified source branch to a specified target branch of your repository, a build is automatically triggered on Bitrise.

Webhooks for triggering builds

Triggering builds automatically requires an incoming webhook set up with the hosting service of your repository. Read more in the Webhooks section.

Open your app on bitrise.io.
Go to the Workflows tab.
Go to the Triggers tab.
Select the PULL REQUEST option.
In the default trigger, click the SOURCE BRANCH and TARGET BRANCH options.

Click + ADD TRIGGER.
Type the names of the source branch and the target branch. Make sure there are no spelling errors, otherwise the trigger won’t work.

You can leave either the source or target branch fields, or both, empty: the trigger will work accordingly. For example, if you leave both empty, as is the default with new apps, every pull request will trigger a build.

Using patterns when specifying a branch or tag

The * symbol can be used in your configured triggers as a wildcard in branch or tag names. It can also be used in patterns. For example, the pattern *-dev can be used for any branches or tags with the suffix -dev. Please note that when there are multiple triggers, only the first matching trigger will start a workflow.

For more information on using wildcards, see: Using wildcards in the trigger map
Select the Workflow you wish to trigger (for example, primary).
Click Save in the top right corner.

And you’re done! From now on, if a pull request is opened in your repository, Bitrise will trigger a build with the selected Workflow!

Skipping a build triggered by a draft pull request

GitHub offers a feature called draft pull request: when you create a pull request (PR), you can choose to create a pull request that is ready for review or a draft pull request. Draft pull requests cannot be merged, and code owners are not automatically requested to review draft pull requests.

Draft PRs can trigger builds on Bitrise just like any other PR. However, you might not want draft PRs to trigger and run a full build. To skip a build or certain Steps in the build, you can use the GITHUB_PR_IS_DRAFT Environment Variable.

To skip a build triggered by a draft PR:

Workflow Editor

bitrise.yml

Add a Script Step to your Workflow as the very first Step.

We recommend adding it as the first Step to avoid wasting credits on a build you don't want to run.
Add the following script to the Content input:
```
#!/usr/bin/env bash
if [ "$GITHUB_PR_IS_DRAFT" = true ] ; then
exit 1
fi
```
This script checks if the PR triggering the build is a draft, and exits the build if it is.

Add a script Step to your Workflow as the very first Step.

We recommend adding it as the first Step to avoid wasting credits on a build you don't want to run.

Add the following script to the content input:

- script:
    inputs:
    - content: |-
        #!/usr/bin/env bash
        if [ "$GITHUB_PR_IS_DRAFT" = true ] ; then
        exit 1
        fi

This script checks if the PR triggering the build is a draft, and exits the build if it is.

Skipping Steps if a build is triggered by a draft PR

You can also skip certain Steps in a build that is triggered by a draft pull request. You just need to use a run_if condition: for more information, see Enabling or disabling a Step conditionally.

Triggering builds with Git Tags

You can specify a pattern for your Git Tags to trigger a specific workflow. This is a good way to build and deploy your app in a specific state. And it’s very easy to set up!

Webhooks for triggering builds

Triggering builds automatically requires an incoming webhook set up with the hosting service of your repository. Read more in the Webhooks section.

Note that certain providers, such as GitLab, require Tag Push events to be specifically enabled in the webhook setup.

Open your app on bitrise.io.
Go to the Workflows tab.
Go to the Triggers tab.
Select the TAG option.
Click + ADD TRIGGER.
In the TAG window, add the tag that you wish to trigger a build.

Using patterns when specifying a branch or tag

The * symbol can be used in your configured triggers as a wildcard in branch or tag names. It can also be used in patterns. For example, the pattern *-dev can be used for any branches or tags with the suffix -dev. Please note that when there are multiple triggers, only the first matching trigger will start a workflow.

For more information on using wildcards, see: Using wildcards in the trigger map
Select the Workflow you wish to trigger (for example, primary).
Click Save in the top right corner.

And you’re done!

In this section:

Triggering builds automatically

Trigger restrictions

Triggering builds with code push

Webhooks for triggering builds

Using patterns when specifying a branch or tag

Triggering builds with pull requests

Webhooks for triggering builds

Using patterns when specifying a branch or tag

Skipping a build triggered by a draft pull request

Skipping Steps if a build is triggered by a draft PR

Triggering builds with Git Tags

Webhooks for triggering builds

Using patterns when specifying a branch or tag

Search results