Triggering builds with API V3

Trigger Travis CI builds using the API V3 by sending a POST request to /repo/{slug|id}/requests:

  1. Get an API token using the Travis CI command line client:

    travis login --org
    travis token --org
    

    You’ll need the token to make most API requests.

    If you are using Travis CI with a private repository use --pro instead of --org in the previous commands, and use https://api.travis-ci.com in all API requests.

  2. Send a request to the API. This example shell script sends a POST request to /repo/travis-ci/travis-core/requests to trigger a build of the most recent commit of the master branch of the travis-ci/travis-core repository:

    body='{
    "request": {
    "branch":"master"
    }}'
    
    curl -s -X POST \
       -H "Content-Type: application/json" \
       -H "Accept: application/json" \
       -H "Travis-API-Version: 3" \
       -H "Authorization: token xxxxxx" \
       -d "$body" \
       https://api.travis-ci.org/repo/travis-ci%2Ftravis-core/requests
    

    The %2F in the request URL is required so that the owner and repository name in the repository slug are interpreted as a single URL segment.

    The build uses the .travis.yml file in the master branch, but you can add to or override configuration, or change the commit message. Overriding any section (like script or env) overrides the full section, the contents of the .travis.yml file is not merged with the values contained in the request.

  3. Send a more complex request to the API. The following script triggers a build and also passes a message attribute for the commit, and adds to the build configuration by passing environment variables and a script command. Here the config from the .travis.yml file is merged with the config from the request body.

    Keys in the request’s config override any keys existing in the .travis.yml.

    body='{
     "request": {
     "message": "Override the commit message: this is an api request",
     "branch":"master",
     "config": {
       "env": {
         "matrix": ["TEST=unit"]
       },
       "script": "echo FOO"
      }
    }}'
    
    curl -s -X POST \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "Travis-API-Version: 3" \
     -H "Authorization: token xxxxxx" \
     -d "$body" \
     https://api.travis-ci.org/repo/travis-ci%2Ftravis-core/requests
    
  4. Look at the reponse body, which contains information about the build, the repository and the user:

    {
      "@type": "pending",
      "remaining_requests": 1,
      "repository": {
        "@type": "repository",
        "@href": "/repo/39521",
        "@representation": "minimal",
        "id": 39521,
        "name": "test-2",
        "slug": "svenfuchs/test-2"
      },
      "request": {
        "repository": {
          "id": 44258138,
          "owner_name": "svenfuchs",
          "name": "test-2"
        },
        "user": {
          "id": 3664
        },
        "id": 205729,
        "message": null,
        "branch": "master",
        "config": {
        }
      },
      "resource_type": "request"
    }
    
  5. Visit the API V3 explorer for more information about what endpoints are available and what you can do with them.

If your API or cron triggered builds run on the same commit or branch over and over again, you will notice GitHub have a limit of 1000 status updates per commit, which causes the Travis CI build status displayed on GitHub to be incorrect. Avoid this problem by specifying a regularly updated branch for your automated builds.

Customizing the commit message

You can specify a commit message in the request body:

body='{
  "request": {
    "branch":"master",
    "message": "Override the commit message: this is an api request"
  }
}'

Customizing the build configuration

You can also customize the build configuration.

Choose one of the following merge modes to determine how the original build configuration (in the .travis.yml file), and the configuration specified in your API request are combined :

  • replace replaces the full, original build configuration with the configuration in the API request body
  • merge (default) replaces sections in the original configuration with the configuration in the API request body
  • deep_merge merges the configuration in the API request body into the build configuration

For example, given that the .travis.yml file contains the following configuration:

language: ruby
env:
  FOO: foo_from_travis_yaml

And given we send the following configuration as an API request:

body='{
  "request": {
    "config": {
      "merge_mode": [...],
      "env": {
        "BAZ": "baz_from_api_request"
      },
      "script": "echo FOO"
    }
  }
}'

Merge mode: replace

With the merge_mode set to replace the resulting combined build configuration is:

{
  "env": {
    "BAZ": "baz_from_api_request"
  },
  "script": "echo FOO"
}

The full configuration has been replaced by the configuration from the API request.

Merge mode: merge (default)

With the merge_mode set to merge, or not given a merge_mode (default), the resulting build configuration is:

{
  "language": "ruby"
  "env": {
    "BAZ": "baz_from_api_request"
  },
  "script": "echo FOO"
}

Each of the top level sections have been replaced with the ones from the API request, other top level sections remain the same.

Merge mode: deep_merge

With the merge_mode set to deep_merge, the resulting build configuration is:

{
  "language": "ruby"
  "env": {
    "FOO": "foo_from_travis_yaml",
    "BAZ": "baz_from_api_request"
  },
  "script": "echo FOO"
}

The env section from the API request has been merged into the existing env section.