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 for the same project.

By default, one trigger can trigger only one Workflow. If you need to trigger multiple Workflows from a single trigger, there are some ways:

Use Pipelines: in a Pipeline, Workflow run parallel in each Stage, and a Pipeline trigger starts the first Stage of a Pipeline. Read more: Configuring Pipeline triggers.
Chain Workflows together so they run after each other.
Use the Bitrise Start Build and the Bitrise Wait for Build Steps.

There are three types of triggers:

Code push: Trigger a build automatically whenever you push code using commits that match your conditions. For example, a commit to the specified branch of the project's repository triggers a build.
Pull request: Trigger a build automatically whenever a pull request matches your conditions. For example, you can specify source and/or destination branches where any pull request will trigger a build.
Git tag: Trigger a build automatically whenever a commit with a specific tag triggers a build.

Trigger conditions

Each trigger type can be set up with multiple different trigger conditions. The available trigger conditions are listed and explained in the procedure for creating each trigger type.

Not all trigger conditions are supported for all Git providers. For the detailed list, see Supported trigger conditions.

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.

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.

Code push triggers

A code push trigger starts a build every time the code in your app's repository changes.

A code push trigger has three possible condition types:

Push branch: Only commits on the specified branch of the app's repository trigger a new build.
Commit message: Only a specified commit message triggers a new build. For example, you have this commit message: hotfix critical: Resolved security vulnerability in user authentication. You can use a wild card pattern like hotfix.* or a regex pattern like hotfix\s*(critical|high):.* to trigger builds for such commit messages.
Files changed: A build is triggered only if certain files change. This is especially useful for monorepo setups; that is, when a single repository contains the code for multiple different projects. For example, a regex pattern like ios/.*\.swift$ can trigger builds when only Swift files within iOS directory are changed inside the monorepo. Similarly, simple wild card patterns like ios/app.js or ios/components/MyView.swift or ios/layouts/main_screen.xml can target specific files in the relevant directories and trigger builds.

These conditions can be combined: for example, you can set up a trigger that starts a build when a given file changes on the main branch of your app's repository. At least one condition must be configured for each trigger. When you set up multiple conditions, all of them must be fulfilled for a build to be triggered.

The trigger configuration allows the use of regular expressions: you can use a regex to match a branch, a commit message, or a filename. The first match will trigger a build and potential subsequent matches will be ignored.

Creating triggers for code pushes

Workflow Editor

bitrise.yml

If you use an OAuth connection to your repository, make sure you have a Bitrise webhook registered to your repository. If you use the GitHub App integration, you don't need a webhook.
Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
On the left, select Triggers.
On the Triggers page, select the Push tab.
Click Add push trigger.
In the Add push trigger dialog, set up one or more trigger conditions:
- Push branch: Commits to the specified branch will trigger a build.
- Commit message: Commits with the specified commit message will trigger a build.
- File change: Changes to the specified file(s) will trigger a build.
When setting multiple conditions, all conditions must be fulfilled for a build to start.

You can use regular expressions for any of the condition types.
Click Next when done.
Select the Workflow or Pipeline you want Bitrise to run when the conditions are met. When done, click Add trigger.

Triggers in YAML

For a detailed description about how build triggers are defined in YAML format, see Build triggers in the configuration YAML.

If you use an OAuth connection to your repository, make sure you have a Bitrise webhook registered to your repository. If you use the GitHub App integration, you don't need a webhook.
Open the bitrise.yml file.
Under trigger_map, add a new trigger by defining the type as push and setting the trigger condition:
```
trigger_map:
- type: push
  commit_message: your_message
```
In this example, we use commit_message as a trigger condition. The available conditions are:
- push_branch: Commits to the specified branch will trigger a build.
- commit_message: Commits with the specified commit message will trigger a build.
- changed_files: Changes to the specified file(s) will trigger a build.
You can use a regex for either of them by adding regex: to a trigger condition. For example:
```
commit_message: 
  regex: ".*"
```

Add a Workflow or Pipeline that should be triggered.

trigger_map:
- type: push
  commit_message: your_message
  workflow: primary

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 or Pipeline.

Pull request triggers

A pull request trigger starts a build every time a pull request is opened in your app's repository.

A pull request trigger has the following condition types:

Source branch: The name of the branch containing the changes of the pull request.
Target branch: The name of the branch that the pull request should be merged to.
Pull request comment: A specified comment submitted to a pull request.
Pull request label: Only pull requests with a certain label applied trigger builds. For example, manually trigger builds for specific PRs by adding a label like build-test.
Pull request commit messages.

Bitrise checks all commit messages of a PR

Note that a pull request trigger checks every commit of a pull request. If any commit message matches the condition, Bitrise will trigger a build.

If this behavior doesn't suit your purposes, consider using a code push trigger instead.
Pull request file changes.

These conditions can be combined: for example, you can set up a trigger that starts a build when a pull request is opened from a given source branch with a certain label. At least one condition must be configured for each trigger. When you set up multiple conditions, all of them must be fulfilled for a build to be triggered.

The trigger configuration allows the use of regular expressions: you can use a regex to match a branch or a PR label. The first match will trigger a build and potential subsequent matches will be ignored.

Builds triggered by pull requests might be subject to manual approval: Approving pull request builds.

By default, draft pull requests trigger builds, too. This can be disabled at any time: Triggering builds from draft PRs.

Creating triggers for pull requests

Workflow Editor

bitrise.yml

Make sure you have a Bitrise webhook registered to your repository.
Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
On the left, select Triggers.
On the Triggers page, select the Pull request tab.
Click Add pull request trigger.
In the Add pull request trigger dialog, set up one or more trigger conditions that will trigger builds:
- Source branch: The branch from which the pull request is opened.
- Target branch: The branch the pull request will be merged into.
- PR label: A label applied to the PR.
- PR comment: A specified comment submitted to a pull request. Note that if any commit message in the pull request matches the condition, Bitrise will trigger a build.
- Commit message: One of the commit messages of the pull request.
- File change: Changes to the specified file(s) in the pull request.
Pull request trigger limitations

To use the PR comment trigger, allow pull request comment to be passed on as the webhook payload at your Git provider. Enable two events: comment created, comment updated.

When setting multiple conditions, all conditions must be fulfilled for a build to start.

You can use regular expressions for any of the condition types.
Click Next when done.
Select the Workflow or Pipeline you want Bitrise to run when the conditions are met. When done, click Add trigger.

Triggers in YAML

For a detailed description about how build triggers are defined in YAML format, see Build triggers in the configuration YAML.

Make sure you have a Bitrise webhook registered to your repository.
Open the bitrise.yml file.
Under trigger_map, add a new trigger by defining the type as pull-request and setting the trigger condition:
```
trigger_map:
- type: pull-request
  pull_request_target_branch:
    regex: ".*"
```
In this example, we use pull_request_target_branch as a trigger condition with a regular expression. The available conditions are the following (you can use a regex for each of them):
- pull_request_source_branch: Pull requests opened from the specified branch will trigger a build.
- pull_request_target_branch: Pull requests to be merged into the specified branch will trigger a build.
- pull_request_label: Pull requests with a given label will trigger a build.
You can use a regex for either of them by adding regex: to a trigger condition.

Add a Workflow or Pipeline that should be triggered.

trigger_map:
- type: pull-request
  pull_request_target_branch:
    regex: ".*"
  workflow: primary

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!

Triggering builds from draft PRs

GitHub and GitLab offers a feature called draft pull request (or merge request in the case of GitLab): 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.

Git provider limitations

This feature is only supported for GitHub and GitLab repositories.

By default, draft PRs trigger builds: every time you open a draft PR or push code to a draft PR. You can disable this at any time with the draft PR toggle in the Workflow Editor. You can check out the exact code events that trigger builds depending on the draft PR trigger settings: Build trigger behavior for draft PRs.

Each separate trigger has its own toggle: you can configure your app so that certain triggers start a build from draft PRs while other triggers don't.

Disabling builds from a draft PR

Skipping Steps if a build is triggered by a draft PR

This guide tells you how to disable triggering builds from a draft PR altogether. You can, however, also skip certain Steps in a build that is triggered by a draft pull request. You just need to use a run_if condition and the GITHUB_PR_IS_DRAFT Environment Variable: for more information, see Enabling or disabling a Step conditionally.

Workflow Editor

bitrise.yml

Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
On the left, select Triggers.
Find the trigger you need and toggle the Draft Pull Requests enabled switch.

Open the bitrise.yml file.
In the trigger_map property, find your trigger. It should have a type: pull_request field.

Add draft_pull_request_enabled: false to it.

trigger_map:
- type: pull-request
  pull_request_target_branch: main
  workflow: primary
  draft_pull_request_enabled: false

Build trigger behavior for draft PRs

The table shows whether a build is triggered when a specific action is performed regarding draft PRs, depending on the draft PR trigger settings. For example, converting a draft PR to a PR doesn't trigger a build if the draft PR trigger is enabled but it does trigger a build when it's disabled.

Table 1. Trigger behavior

Action	Draft PR trigger is enabled	Draft PR trigger is disabled
Open a draft PR
Push a commit to a draft PR
Convert a draft PR to PR
Convert PR to draft PR

Git tag triggers

A Git tag trigger starts a build every time a commit with a given Git tag is pushed to your app's repository.

For a tag trigger, there is only one possible condition: the tag itself. When setting up the trigger, you need to either set a full tag or a regular expression pattern.

Creating Git tag triggers

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

Workflow Editor

bitrise.yml

Make sure you have a Bitrise webhook registered to your repository.
If your Git provider requires it, make sure that Tag Push events are enabled in the webhook configuration.

For example, GitLab requires it.
Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
On the left, select Triggers.
On the Triggers page, select the Tag tab.
Click Add tag trigger.
In the Add tag trigger dialog, add a tag in the Tag field.

You can use a regular expression instead of the full tag.
Click Next when done.
Select the Workflow or Pipeline you want Bitrise to run when the conditions are met. When done, click Add trigger.

Triggers in YAML

For a detailed description about how build triggers are defined in YAML format, see Build triggers in the configuration YAML.

Make sure you have a Bitrise webhook registered to your repository.
Open the bitrise.yml file.
Under trigger_map, add a new trigger by defining the type as tag-push and set the tag trigger condition:
```
trigger_map:
- type: tag-push
  tag: '*'
```
This example uses a wildcard that triggers a build on any tag push.

Add a Workflow or Pipeline that should be triggered.

trigger_map:
- type: tag-push
  tag: '*'
  workflow: primary

Deactivating a trigger

You can temporarily deactivate any build trigger. A deactivated trigger doesn't trigger builds but retains all configuration information. If you need the trigger again in the future, you don't have to recreate it: just reactivate it with a single click.

To deactivate a build trigger:

Workflow Editor

bitrise.yml

Open the Workflow Editor on Bitrise.
On the left, select Triggers.
Select the appropriate tab, depending on the trigger you want to deactivate.
Set the trigger to Inactive.

Open the bitrise.yml file.
Find the trigger_map property and the trigger you want to disable.

Add enabled: false to it.

trigger_map:
- type: push
  push_branch: main
  workflow: primary
  enabled: false

Supported trigger conditions

Not all trigger conditions are available for all Git providers. As a general rule, all our trigger conditions are available for the cloud service of the three most frequently used Git providers: GitHub, GitLab, and Bitbucket. For other providers, or self-hosted Git repositories, check out the detailed table for both push triggers and pull request triggers.

Table 1. Supported trigger conditions for code push triggers

Git provider	Branch	Commit message	Files changed
GitHub (cloud)
GitHub (self-hosted)
GitLab (cloud)
GitLab (self-hosted)
Bitbucket (cloud)
BitBucket Server (self-hosted)
Assembla
Deveo (Perforce)
Gogs
Azure DevOps

Table 2. Supported trigger conditions for pull request triggers

Git provider	Source branch	Target branch	Labels	Comments	Commit message	Changed files
GitHub (cloud)
GitHub (self-hosted)
GitLab (cloud)
GitLab (self-hosted)
Bitbucket (cloud)			N/A
BitBucket Server (self-hosted)			N/A
Assembla			N/A
Deveo (Perforce)
Gogs
Azure DevOps

In this section:

Triggering builds automatically

Trigger conditions

Code push triggers

Creating triggers for code pushes

Triggers in YAML

Pull request triggers

Bitrise checks all commit messages of a PR

Creating triggers for pull requests

Pull request trigger limitations

Triggers in YAML

Triggering builds from draft PRs

Git provider limitations

Disabling builds from a draft PR

Skipping Steps if a build is triggered by a draft PR

Build trigger behavior for draft PRs

Git tag triggers

Creating Git tag triggers

Triggers in YAML

Deactivating a trigger

Supported trigger conditions

Search results