Build triggers

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.

Existing trigger configurations

This page details information about target-based build triggers, defined within a Workflow or a Pipeline. We recommend this approach for all new users as it offers a more granular and flexible build trigger system.

Existing configurations might use legacy, project-based triggers. Read more about them: Legacy project-based triggers.

Use build triggers to start one or more Bitrise builds automatically. A trigger's definition contains a code event and one or more conditions that the event must match in order to trigger a build.

You can define triggers within a Workflow or a Pipeline. They allow a single code event to trigger multiple different Workflows or Pipelines so you can run all the relevant parts of your CI process together based on the scope of code change, without bundling everything into a single Workflow or Pipeline. Each build will run independently and deliver individual results.

For the detailed syntax of triggers and the exact trigger conditions, see Build triggers in the configuration YAML.

Code events

You can use three types of code events to trigger builds:

Code push: Trigger a build automatically whenever you push code using commits that match your trigger 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 trigger 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.

Conditions

A trigger condition is a filter for code events: instead of triggering a build on every pull request, you can configure triggers for pull requests targeting a specific branch.

Different Git providers support different conditions. For the full table, see Supported trigger conditions.

Trigger conditions can be combined within a single trigger: for example, you can set up a pull request trigger that only triggers a build if the PR targets a specific branch AND contains a specific label.

Creating build triggers

You create build triggers directly in a Workflow or Pipeline. Such triggers allow a single code event to trigger multiple Workflows or Pipelines. You can create triggers via the UI or in the configuration YAML file.

To create triggers:

Workflow Editor

Configuration YAML

Log in to Bitrise and select Bitrise CI on the left, then select your project.
Click the Workflows button on the main page.
Select a Workflow.
Select the Triggers tab on the Workflow's page.
Select the trigger type and click the Add trigger button.
Configure your trigger in the dialog.
When done, click Add trigger.

Open your configuration YAML file.
Find the Workflow.
In the Workflow, add a triggers property.
```
my-workflow:
    triggers:
```
Create your triggers. You can find the exact syntax for the different trigger types here: Build triggers in the configuration YAML.

For example, this trigger starts a build with the Workflow
```
my-workflow:
triggers:
  push:
  - commit_message: your_message
```
Save the configuration.

Disabling a trigger

You can temporarily disable any build trigger. A disabled trigger doesn't trigger builds but retains all configuration information. You can reactivate a disabled trigger at any time.

To disable a build trigger:

Workflow Editor

Configuration YAML

Open the Workflow Editor on Bitrise.
Select a Workflow or Pipeline.
On the Workflow page, select the Triggers tab.
Find the trigger you need and click the vertical ellipsis next to its name.
Select Disable trigger.

Open your configuration YAML file.
Find the Workflow or Pipeline and its triggers property.

Add enabled: false to the trigger you want to disable.

triggers:
  push:
  - branch: main
    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: