- 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, 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 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.
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.
Draft pull requests
Draft pull requests trigger builds by default; however, you can switch this function off: Disabling builds from draft PRs.
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!
Disabling 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.
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.
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.
When the draft PR toggle is turned off, a draft PR or pushing a commit to a draft PR doesn't automatically start a build.
Converting a draft PR
If the draft PR toggle is disabled, and you convert a draft PR to a full PR at your Git provider, a build is triggered automatically!
To disable triggering builds by a draft PR:
-
Open your app on Bitrise.
-
Click the Workflows button on the main page.
-
On the Workflows & Pipelines pages, you can:
-
Click the Edit bitrise.yml button to get to the bitrise.yml tab of the Workflow Editor.
-
Click the button next to the name of any Workflow to open it in the Workflow Editor.
-
-
Go to the Triggers tab.
-
Find the trigger you need and toggle the Draft Pull Requests enabled switch.
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 and the GITHUB_PR_IS_DRAFT
Environment Variable: 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!