The Automation API is a solution for people who'd like to be able to integrate Gearset with external workflows like Jenkins or Azure Pipelines. It presents the functionality to interact with continuous integration and unit test jobs from outside of Gearset. Therefore, teams can take advantage of our powerful deployment engine and other analysis tools, but integrate them within a wider DevOps toolchain.

In many scenarios, we believe that pipelines, VCS integrations, and outgoing webhooks present enough functionality to our users to achieve what they want, so be sure to give them a look first as they do a lot of the work we can imagine using the API for.

To start with, you need an API access token, which you can generate by following our tutorial Creating a Gearset API access token.

Once you have that, you're now ready to start making some requests. The Automation API is a REST API that accepts JSON messages over HTTPS, so we'll be using the curl program to demonstrate its use. The curl program is installed by default on Linux, Windows, and macOS command lines. Our full API reference gives a list of the commands available, and also lets you run them.

We'll start by querying the current status of a continuous integration job, to find whether the job is currently running or is idle.

First, we need to get the ID of a CI job we're interested in. Navigate to the Continuous integration dashboard in Gearset and click on the arrow icon to the right of the job.

You can then copy the job ID to the clipboard using the Copy job ID link.

Next, we need to start building the request. To make a request to an endpoint, add the Authorization header to your API request. It needs to contain the prefix 'token', followed by your token secret (that you copied from the access token tutorial).

To do this in curl, we use the -H command, as follows:

Now we need to specify the endpoint we want to query. The address is https://api.gearset.com/public/automation/continuous-integration-jobs/{CI_JOB_ID}/status, as found in the full API reference.

To complete the request, copy the following and run it, making sure to replace the token and CI job ID with the ones we copied earlier!

When you've run that command you should get a response like this:

There you have it — you've successfully queried the Automation API to get the status of a continuous integration job.

We're now going to try starting that CI job. As before, get your CI job ID and your token header for the request. Then modify the example request shown below, adding your own token and integration job ID. No HTTP body is required in the POST request, so adding the option -d {} to the curl command will be sufficient.

Example curl command to request a CI job run:

Once the command is executed, you should receive a 200 OK response with the following information attached:

Save this value, as we're going to need it to check the progress of the run. This is done by sending a request like the following (but with your token, CI job ID and run request ID):

This will return a status object with information about the run in the form:

And that's it — you've successfully used the Automation API to query the status of a CI job, run it, and found out when a run has ended.

If you want to kick off the job run only when the API calls it (and not when the branch is updated or at a regular frequency), you can set the CI job to be Disabled.

This means the job will only run when the API triggers it and not at the regular frequency specified in the Run job section of the settings (as shown on below example where the CI job within the Gearset Pipelines setup is configured to run "when the source branch is updated").