Triggering and aborting builds

Abstract

You can use the Bitrise API to trigger and abort builds of your apps. Define parameters for the build: for example, branch, tag or git commit to use. Custom Environment Variables can be defined as well.

Table 1. Endpoints related to triggering and aborting builds with the API

Endpoints	Function	Required role on the app's team
POST /apps/{app-slug}/builds	Trigger a new build.	Owner, Admin, or Developer
POST /apps/{app-slug}/builds/{build-slug}/abort	Abort a specific build.	Owner, Admin, or Developer

You can trigger and abort builds with the Bitrise API. Define parameters for the build: for example, branch, tag or git commit to use. Custom Environment Variables can be defined as well.

Triggering a new build with the API

To trigger a new build with the Bitrise API, call the /apps/{APP-SLUG}/builds endpoint. You need to specify an app slug and at least one build parameter in a JSON object:

A git tag or git commit hash
A branch
A Workflow ID

You also must have a valid build trigger set up in the trigger map in your app's bitrise.yml file.

Required role

You must have a developer, admin, or owner role on the app's team to trigger a new build using the API.

For a complete list of user roles and role cheatsheets, check User roles on project teams.

The JSON object must also contain a hook_info object with a type key and bitrise as the value of the key.

Here’s a minimal sample JSON body which specifies main as the value of the branch parameter:

{
  "hook_info": {
    "type": "bitrise",
  },
  "build_params": {
    "branch": "main"
  }
}

And here’s the curl request syntax for triggering a build on the main branch:

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "build_params": {
    "branch": "main"
  },
  "hook_info": {
    "type": "bitrise"
  }
}'

Interactive cURL call configurator

You can find an interactive cURL call configurator by clicking on the Start/Schedule a build button on your app’s bitrise.io page and switching to Advanced mode in the popup. At the bottom of the popup you can find a curl call, based on the parameters you specify in the popup.

In the previous example, we passed this JSON payload as a string: to be precise, as a JSON object serialized to a string.

You can also pass it as an object (for example, if you want to call it from JavaScript). To do so, include a root payload element or, alternatively, set the JSON object as the value of the payload POST parameter.

Here’s a jQuery example using the payload parameter:

$.post("https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/", {
    "payload":{
        "hook_info":{
            "type":"bitrise",
        },
        "build_params":{
            "branch":"main"
        }
    }
})

You can specify several different build parameters when triggering a build. The parameters should be set in the build_params object.

Setting a branch, commit or tag to build

You can set Git-specific parameters in your call. The branch parameter specifies the source branch to be built. This is either the branch of the git commit or, in the case of a pull request build, the source branch of the pull request.

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
        "hook_info": {
                "type": "bitrise"
        },
        "build_params": {
                "branch": "main"
        }
 }'

You can also build a specific git commit or even a git tag: you just need to set either the commit hash or the tag in the build_params object. You can also set a commit message for the build with the commit_message parameter.

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "hook_info":{
    "type":"bitrise"
  },
  "build_params": {
    "commit_hash": "0000ffffeeeee",
    "commit_message": "testing"
  }
}'

Parameter priority

The Git Clone Step has the following parameter priority:

commit_hash
tag
branch

If you provide multiple parameters, the parameter with lower priority will be ignored.

The ignored parameters will still be logged. They will be available for Steps and they will be visible on the Build’s Details & Add-ons page but the Git Clone Step will use the most specific parameter for checkout.

Setting parameters for pull request builds

For a pull request build, use the branch_dest parameter to set up the destination or target branch of the pull request. The PR will be merged into this branch but before that, Bitrise will build your app based on how the code would look like after merging. This is what happens when a PR build is automatically triggered by a webhook, for example.

The branch_repo_owner and branch_dest_repo_owner parameters are used to identify the owners of the repositories, to unambiguously identify the branches involved in the pull request.

Pull request builds from forks

If you do not specify the branch_repo_owner and branch_dest_repo_owner parameters, the API will assume pull request builds are coming from a fork. As such, they might be put on hold pending manual approval: Approving pull request builds.

To identify the PR itself, use the pull_request_id parameter: it takes an integer; for example, the number of the PR on GitHub.

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "hook_info":{
    "type":"bitrise"
  },
  "build_params": {
    "branch": "the-pr-branch",
    "branch_dest": "main",
    "commit_hash": "fffff000000eeeeee",
    "pull_request_id": 1
  }
}'

If your git provider supports it, you can also use the pull_request_merge_branch parameter to build the pre-merged state of the branch of the PR. Another alternative is the pull_request_head_branch parameter: this is a special git ref that should point to the source of the PR.

If you want to trigger a build from a PR opened from a fork of your repository, use the pull_request_repository_url parameter. The value should be the URL of the fork.

Skipping Git status reports

If you have a webhook set up, Bitrise will send status reports to your git provider about your builds. However, this can be disabled via the API: use the skip_git_status_report parameter. If it is set to true, no build status report will be sent.

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
  "hook_info":{
    "type":"bitrise"
  },
  "build_params": {
    "branch": "the-pr-branch",
    "branch_dest": "main",
    "skip_git_status_report": true
  }
}'

Specifying Environment Variables

You can define additional Environment Variables (Env Vars) for your build. These additional variables will be handled with priority between Secrets and App Env Vars, which means that you can not overwrite Env Vars defined in your build configuration (for example, App Env Vars), only Secrets.

Define additional Env Vars with the environments parameter. This parameter must be an array of objects, and every item of the array must include at least a mapped_to property. This must contain:

The key of the Env Var.
The value of the Env Var.

Replacing Env Var names

By default, Env Var names inside values will be replaced in triggered build by actual value from the target environment. This behavior can be disabled by setting the is_expand flag to false.

"environments":[
  {"mapped_to":"API_TEST_ENV","value":"This is the test value","is_expand":true},
  {"mapped_to":"HELP_ENV","value":"$HOME variable contains user's home directory path","is_expand":false},
]

Setting a Workflow for the build

By default, the Workflow for a triggered build will be selected based on the content of build_params and your app’s trigger map. This is the same as how webhooks select the Workflow for the build automatically, based on the Trigger Map.

With the API, you can overwrite this selection and specify exactly which Workflow you want to use.

Add a workflow_id parameter to your build_params and specify the workflow you want to use for that specific build. Here’s an example call where we specify the deploy workflow:

curl -X 'POST' \
  'https://api.bitrise.io/v0.1/apps/APP-SLUG/builds' \
  -H 'accept: application/json' \
  -H 'Authorization: ACCESS-TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "hook_info": {
        "type": "bitrise"
    },
    "build_params": {
        "branch": "main",
        "workflow_id": "primary"
    }
}'

Aborting a build

You can abort running builds, and set the reason for aborting, as well as specify if email notifications should be sent about the build.

Required role

You must have an admin or owner role on the app's team to manage incoming or outgoing webhooks using the API.

For a complete list of user roles and role cheatsheets, check User roles on project teams.

To simply abort the build, call the /apps/APP-SLUG/builds/BUILD-SLUG/abort endpoint. It requires three parameters:

The app slug.
The build slug.
The build abort parameters body. This can be left empty if you don't want to set any specific parameters for the abort: -d "{}".

curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d "{}"

You can set a reason for aborting the build by using the abort_reason parameter. This parameter takes a string and it will show up on your app’s build page.

curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d '{"abort_reason": "aborted for a reason"}'

Normally, aborted builds count as failed builds. Use the abort_with_success parameter to abort a build but still count it as a successful one. The status report sent to your git provider will show the build as successful though on bitrise.io it will be displayed as Cancelled.

curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d '{"abort_with_success": true}'

Depending on your app settings, Bitrise might send email notifications to team members when a build is aborted. If you do not want notifications, set the skip_notifications parameter to true.

curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort" -d '{"skip_notifications": true}'

In this section:

trigger

Triggering and aborting builds

Triggering a new build with the API

Required role

Interactive cURL call configurator

Setting a branch, commit or tag to build

Parameter priority

Setting parameters for pull request builds

Pull request builds from forks

Skipping Git status reports

Specifying Environment Variables

Replacing Env Var names

Setting a Workflow for the build

Aborting a build

Required role

Search results