Cirrus CI API¶
Cirrus CI exposes GraphQL API for integrators to use through https://api.cirrus-ci.com/graphql
endpoint. Please check
Cirrus CI GraphQL Schema for a full list of
available types and methods. Or check built-in interactive GraphQL Explorer. Here is an example of how to get a build for a particular SHA of a given repository:
curl -X POST --data \
'{
"query": "query BuildBySHAQuery($owner: String!, $name: String!, $SHA: String) { searchBuilds(repositoryOwner: $owner, repositoryName: $name, SHA: $SHA) { id } }",
"variables": {
"owner": "ORGANIZATION",
"name": "REPOSITORY NAME",
"SHA": "SOME SHA"
}
}' \
https://api.cirrus-ci.com/graphql | python -m json.tool
Authorization¶
In order for a tool to access Cirrus CI API, an organization admin should generate an access token through Cirrus CI
Settings page for a corresponding organization. Here is a direct link to the settings page: https://cirrus-ci.com/settings/github/<ORGANIZATION>
. Access tokens will allow full write and read access to both public and private repositories of your organization on Cirrus CI: it will be possible to create new builds and perform any other GraphQL mutations. If you only need read access to public repositories of your organization you can skip this step and don't provide Authorization
header.
Once an access token is generated and securely stored, it can be used to authorize API requests by setting Authorization
header to Bearer $TOKEN
.
User API Token Permission Scope
It is also possible to generate API tokens for personal accounts but they will be scoped only to access personal public and private repositories of a particular user. It won't be possible to access private repositories of an organization, even if they have access.
WebHooks¶
It is possible to subscribe for updates of builds and tasks. If a WebHook URL is configured on Cirrus CI Settings page for
an organization, Cirrus CI will try to POST
a webhook event payload to this URL.
POST
request will contain X-Cirrus-Event
header to specify if the update was made to a build
or a task
. The event
payload itself is pretty basic:
data
field will be populated by executing the following GraphQL query:
repository(id: $repositoryId) {
id
owner
name
isPrivate
}
build(id: $buildId) {
id
branch
pullRequest
changeIdInRepo
changeTimestamp
status
}
task(id: $taskId) {
id
name
status
statusTimestamp
creationTimestamp
uniqueLabels
automaticReRun
automaticallyReRunnable
notifications {
level
message
link
}
}
Custom GraphQL Query
If you'd like to customize GraphQL query which will be executed and included in the event payload please contact support for further details.
Securing WebHooks¶
Imagine you've been given a https://example.com/webhook
endpoint by your administrator, and for some reason there's no easy way to change that. This kind of URL is easily discoverable on the internet, and an attacker can take advantage of this by sending requests to this URL, thus pretending to be the Cirrus CI.
To avoid such situations, set the secret token in the repository settings, and then validate the X-Cirrus-Signature
for each WebHook request.
Once configured, the secret token and the request's body are fed into the HMAC algorithm to generate the X-Cirrus-Signature
for each request coming from the Cirrus CI.
Missing X-Cirrus-Signature header
When secret token is configured in the repository settings, all WebHook requests will contain the X-Cirrus-Signature-Header
. Make sure to assert the presence of X-Cirrus-Signature-Header
header and correctness of its value in your validation code.
Using HMAC is pretty straightforward in many languages, here's an example of how to validate the X-Cirrus-Signature
using Python's hmac
module: