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 ⚓
Endpoints | Function |
---|---|
POST /apps/{app-slug}/builds | Trigger a new build. |
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
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 master as the value of the branch
parameter:
{
"hook_info": {
"type": "bitrise",
},
"build_params": {
"branch": "master"
}
}
And here’s an example curl request:
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d \
'{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "master"
}
}'
In the above example, we triggered a build of the app’s master
branch.
In the 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/app/APP-SLUG/builds/", {
"payload":{
"hook_info":{
"type":"bitrise",
},
"build_params":{
"branch":"master"
}
}
})
You can specify several different build parameters when triggering a build. The parameters should be set in the build_params
object: let’s go through some of the possible configurations!
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 -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d \
'{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "master"
}
}'
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 -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d \
'{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"commit_hash": "0000ffffeeeee",
"commit_message": "testing"
}
}'
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.
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 -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d \
'{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "the-pr-branch",
"branch_dest": "master",
"pull_request_id": 133,
"commit_hash": "fffff000000eeeeee"
}
}'
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 report ⚓
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 -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d \
'{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "the-pr-branch",
"branch_dest": "master",
"pull_request_id": 133,
"skip_git_status_report": "true"
}
}'
Specifying Environment Variables ⚓
You can define additional environment variables for your build.
Be aware that Environment Variables have a priority order! These additional variables will be handled with priority between Secrets
and App Env Vars
, which means that you can not overwrite environment variables defined in your build configuration (for example, App Env Vars), only Secrets.
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 Environment Variable.
- The value of the Environment Variable.
Example:
"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 your 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 however 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 -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds" -d \
'{
"hook_info": {
"type": "bitrise"
},
"build_params": {
"branch": "master",
"workflow_id": "deploy"
}
}'
Aborting a build ⚓
Endpoints | Function |
---|---|
POST /apps/{app-slug}/builds/{build-slug}/abort | Abort a specific 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.
To simply abort the build, call the /apps/APP-SLUG/builds/BUILD-SLUG/abort
endpoint. The only required parameters are the app slug and the build slug.
curl -X POST -H "Authorization: ACCESS-TOKEN" "https://api.bitrise.io/v0.1/apps/APP-SLUG/builds/BUILD-SLUG/abort"
Setting an abort reason ⚓
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}'
Cancelling email notifications ⚓
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}'