About build triggers

Abstract

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 YAML syntax for build triggers.

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.

Initial PR event

A pull request only triggers a build once, at its initial event. In most cases, that initial event is the creation of the pull request. For example, converting a PR to a draft PR will never trigger another build. To trigger builds for updates to a pull request, configure code push triggers for the new commits.
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.

Trigger priority

Triggers can be assigned a priority setting: this determines the priority of a build triggered by a specific trigger. The higher the priority, the higher the build is in the build queue.

You can assign a priority either in the Workflow Editor or in the configuration YAML file of your project. The priority is always an integer between -100 and 100: the higher the number, the higher the priority. The default priority is 0.

For more information about build priority, and the order of precedence between different types of priorities, check out Build priority.

Trigger variables

A number of Environment Variables related to build triggers are available during an automatically triggered build. These variables can give detailed context about build triggers and pull request attributes. Use these trigger variables to:

Use pull request data, such as comments, labels, and changed files, to automate complex workflows and decision-making processes.
Understand who and how your builds are triggered and use that to better debug your workflows
Implement precise build conditions to reduce unnecessary runs, saving time and resources.

You can find all trigger variables and their definition in our reference table: Table 74, “Env Vars exposed by bitrise.io”.

Trigger variables are only available if the requirements are met. For example, the BITRISE_GIT_PULL_REQUEST_COMMENT variable is only available if the build is triggered by a PR comment; in other words, the build trigger has a pr_comment condition. You can find the exact conditions in Table 74, “Env Vars exposed by bitrise.io”.

Use cases for trigger variables

Here are some example use cases for trigger variables. These are merely suggestions: you can experiment with variables to find what suits your needs best.

Example 29. Reporting back to the PR comment

BITRISE_GIT_PULL_REQUEST_COMMENT_ID: Use the pull request comment ID to post a status update directly to the original comment on the pull request. This can include details such as success, failure, logs, or any other relevant information.

Example 30. Conditional test execution

BITRISE_GIT_CHANGED_FILES : Identify modified parts of the codebase and based on these changes, trigger specific test suites, such as running frontend tests for UI changes and backend tests for API modifications.

Example 31. Deploying to different environments based on commit messages or labels

Use BITRISE_GIT_COMMIT_MESSAGES and BITRISE_GIT_PULL_REQUEST_LABELS to determine the deployment environment. For instance, if a commit message includes "[staging]" or a label "ready-for-staging" is present, deploy the code to the staging environment.

Merge queue support

GitHub Merge Queues allow multiple pull requests (PRs) to be merged automatically into a branch. You can verify the changes in each PR with a Bitrise build by setting up a trigger with gh-readonly-queue/* as the branch filter. You can read more about this prefix in the GitHub documentation.

The merge queue will only function correctly if your builds, triggered for the queue, report the same status names as the PR builds.

For example, with the configuration below, all branches that are merged from a merge queue, trigger a build with the ci-pipeline Pipeline:

pipelines:
  ci-pipeline:
    triggers:
      push:
      - branch: "gh-readonly-queue/*"
    status_report_name: ci/bitrise/<project_slug>/pr

In this section: