Build Trigger API
    GitHub

    Build Trigger API

    Note: the _www_ endpoint is now deprecated. Please use the _https://app.bitrise.io/app/APP-SLUG/build/start.json_ endpoint instead.

    With the Build Trigger API you can start a new build of your app with a simple API call.

    You can define parameters for the build like what branch, tag or git commit to use and what build message to present on the Build’s details page.

    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.

    How to start a build by calling the Trigger API? ⚓

    You have to call your build trigger with a POST request with a JSON body.

    Build Trigger Token and App Slug

    When you use the Bitrise Trigger API you have to specify the App’s Build Trigger Token and App Slug. You can view both and regenerate your App’s Build Trigger Token anytime you want to, on the Code tab of the app.

    Old API token parameter

    The old _api_token_ parameter is DEPRECATED, please use the _build_trigger_token_parameter instead.

    JSON body ⚓

    The JSON body has to contain at least:

    A minimal sample JSON body, which specifies master as the branch parameter:

    {
  "hook_info": {
    "type": "bitrise",
    "build_trigger_token": "..."
  },
  "build_params": {
    "branch": "master"
  }
}

    To pass this JSON payload you can either pass it as the body of the request as string (the JSON object serialized to string), or if you want to pass it as an object (e.g. if you want to call it from JavaScript) then you have to include a root payload element, or set the JSON object as the value of the payload POST parameter.

    jQuery example using the payload parameter:

    $.post("https://app.bitrise.io/app/APP-SLUG/build/start.json", {
    "payload":{
        "hook_info":{
            "type":"bitrise",
            "build_trigger_token":"APP-API-TOKEN"
        },
        "build_params":{
            "branch":"master"
        }
    }
})

    Build Params ⚓

    The following parameters are supported in the build_params object:

    Bitrise.io specific: ⚓

    Pull Request specific: ⚓

    Git Clone - parameter priority

    If you provide a tag, the branch parameter will be ignored by the Git Clone step. If you provide a commit_hash parameter then both the tag and the branch parameters will be ignored. These will still be logged, will be available for steps and will be visible on the Build’s details page, but the Git Clone step will use the the most specific parameter for checkout.

    Specify Environment Variables ⚓

    You can define additional environment variables for your build.

    These 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 (e.g. App Env Vars), only Secrets. For more information see: _Availability order of environment variables

    It’s important that this parameter have to be an array of objects, and that every item of the array have to include at least a mapped_to (the key of the Environment Variable, without a dollar sign ($)) and a value property (the value of the variable). By default environment variable names inside values will be replaced in triggered build by actual value from target environment. This behavior can be disabled by setting is_expand flag to false.

    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},
]

    Workflow to be used for the build ⚓

    By default the Workflow for your Build will be selected based on the 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), and how you can define separate Workflows for separate branches, tags or pull requests without the need to specify the workflow manually for every build.

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

    All you have to do is add a workflow_id parameter to your build_params and specify the Workflow you want to use for that specific build.

    An example build_params with branch and workflow_id:

    "build_params":{"branch":"master","workflow_id":"deploy"}'

    curl example generator ⚓

    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.

    A base curl call would look like this (with master specified as the branch build parameter):

    curl -H 'Content-Type: application/json' https://app.bitrise.io/app/APP-SLUG/build/start.json --data '{"hook_info":{"type":"bitrise","build_trigger_token":"APP-API-TOKEN"},"build_params":{"branch":"master"}}'

    Note: please don’t forget to add _Content-Type_ header with _application/json_ value

    A more advanced example: let’s say you want to build the master branch using the deployment workflow, specify a build message (commit_message) and set a test environment variable (API_TEST_ENV), the call will look like this:

    curl  -H 'Content-Type: application/json' https://app.bitrise.io/app/APP-SLUG/build/start.json --data '{"hook_info":{"type":"bitrise","build_trigger_token":"APP-API-TOKEN"},"build_params":{"branch":"master","commit_message":"Environment in API params test","workflow_id":"deployment","environments":[{"mapped_to":"API_TEST_ENV","value":"This is the test value","is_expand":true}]}}'