Current limitations and requirements

  • You'll need an enterprise license to use this feature

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.

Making your first Automation API requests

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 in Linux, Windows, and MacOS command lines. Our full API reference gives a list of the commands available, and also lets you run them.

Getting the status of a CI job

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:

curl -H "Authorization: token 052E08E9B1580A0D15121B6009B7C8D9D2ECAED75F888DC53F2D72A86ED575C9"

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!

curl -H "Authorization: token 052E08E9B1580A0D15121B6009B7C8D9D2ECAED75F888DC53F2D72A86ED575C9" https://api.gearset.com/public/automation/continuous-integration-jobs/b32672c1-f867-4032-a071-3b1d382b11d7/status

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

{"State":"Idle"}

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

Kicking off a CI job run

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:

curl -H "Authorization: token 052E08E9B1580A0D15121B6009B7C8D9D2ECAED75F888DC53F2D72A86ED575C9" -H "Content-Type: application/json" https://api.gearset.com/public/automation/continuous-integration-jobs/b32672c1-f867-4032-a071-3b1d382b11d7/run-requests -d {}

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

{"RunRequestId":"5872d0a8-bc64-4766-bbee-8aefd4ee1e97"}

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):

curl -H "Authorization: token 052E08E9B1580A0D15121B6009B7C8D9D2ECAED75F888DC53F2D72A86ED575C9" https://api.gearset.com/public/automation/continuous-integration-jobs/b32672c1-f867-4032-a071-3b1d382b11d7/run-requests/5872d0a8-bc64-4766-bbee-8aefd4ee1e97

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

{"State":"Succeeded","RunId":"0bc2311d-9d65-4a61-9f68-84175e2a22f9","StartDateTime":"2022-03-30T12:35:14.060832Z","EndDateTime":"2022-03-30T12:35:39.606944Z"}

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.

Did this answer your question?