- Home
- Builds
- Starting builds
- Triggering builds automatically
Triggering builds automatically
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 likehotfix.*
or a regex pattern likehotfix\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 likeios/app.js or ios/components/MyView.swift
orios/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 aspush
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 aspull-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 atype: 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.
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 astag-push
and set thetag
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.
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 |
|
|
|
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 |
|
|
|
|
|
|