Web Interface (Cuirass Reference Manual)

8 Web Interface

Cuirass has a web interface that one can navigate through a web browser, and it also has a programming interface: HTTP endpoints that can be queried to obtain a JSON representation of its state.

This programming interface is inspired by that of Hydra, the continuous integration tool of the NixOS project. The sections below describe the available HTTP endpoints.

As a user, note that there are at least two tools that can simplify access to this interface: the emacs-build-farm package for Emacs, and the (guix ci) client module from Guix.

Evaluation information
Triggering an Evaluation
Build information
Build raw log output
Jobs
Jobs history
Dashboard registration
Latest builds
Queued builds

8.1 Evaluation information

Single evaluation

It is possible to query the Cuirass web server for evaluation information. The dedicated API is "/api/evaluation?id=eval-id" where eval-id is the unique id associated to the evaluation in database.

For instance, querying a local Cuirass web server can be done with curl and jq to format the JSON response :

$ curl -s "http://localhost:8080/api/evaluation?id=1" | jq

{
  "id": 1,
  "specification": "master",
  "status": 0,
  "timestamp": 1615289011,
  "checkouttime": 1615289011,
  "evaltime": 1615289655,
  "checkouts": [
    {
      "commit": "bd311f5a6ccbd4696ac77f0426a036bb375a2f10",
      "channel": "guix",
      "directory": "/gnu/store/6978xw9vs4ybg2pc3g736p1dba2056yl-guix-bd311f5"
    }
  ]
}

The nominal output is a JSON object whose fields are described hereafter.

id

The unique build id.

specification

The associated specification name, as a string.

status

The evaluation status, as an integer. Possible values are :

-1 -> started
0 -> succeeded
1 -> failed
2 -> aborted

checkouttime

The timestamp after channel checkout.

evaltime

The timestamp after evaluation completion.

checkouts

The evaluation checkouts as a JSON object.

Multiple evaluations

The latest evaluations list can be obtained with the API "/api/evaluations". The output is a JSON array of evaluations. Evaluations are represented as in the "/api/evaluation?id=eval-id" API.

This request accepts a mandatory parameter and an optional one.

nr: Limit query result to nr elements. This parameter is mandatory.
spec: Only consider evaluations that are part of the given spec specification.

8.2 Triggering an Evaluation

One can send an HTTP POST request to trigger the evaluation of a jobset, along these lines:

wget --post-data="" -O /dev/null \
  https://cuirass.example.org/jobset/jobset/hook/evaluate

A good idea is to do that from the post-push hook of the relevant Git repository.

8.3 Build information

It is possible to query Cuirass web server for build informations. The dedicated API is "/build/build-id" where build-id is the unique id associated to the build in database.

The build information can also be queried by output. For example, ‘/output/kg9mirg6xbvzcp0a98v7326n1nvvwgsj-hello-2.10’ will return the details of the output, along with the build if available.

$ curl -s "http://localhost:8080/build/2" | jq

{
  "id": 2,
  "jobset": "guix",
  "job": "acpica-20150410-job",
  "timestamp": 1501347493,
  "starttime": 1501347493,
  "stoptime": 1501347493,
  "buildoutputs": {
    "out": {
      "path": "/gnu/store/6g3njhfzqpdm335s7qhvmwvs5l7gcbq1-acpica-20150410"
    }
  },
  "system": "x86_64-linux",
  "nixname": "acpica-20150410",
  "buildstatus": 0,
  "weather": 0,
  "busy": 0,
  "priority": 0,
  "finished": 1,
  "buildproducts": null
}

If requested build-id is not known, the HTTP code 404 is answered with a JSON error message. For example:

$ curl -s "http://localhost:8080/build/fff"

{"error" : "Build with ID fff doesn't exist."}

The nominal output is a JSON object whose fields are described hereafter.

id

The unique build id.

jobset

The associated specification name, as a string.

job

The associated job-name, as a string.

timestamp

Timestamp taken at build creation time.

starttime

Timestamp taken at build start time.

stoptime

Timestamp taken at build stop time.

buildoutputs

Build outputs as a JSON object. The keys names are referring to the eventual output names. The associated value is another JSON object which only key is path. path value is the output directory in store as a string.

system

System name of the build, as a string.

nixname

Derivation name, as a string.

buildstatus

Build status, as an integer. Possible values are :

0 -> succeeded
1 -> failed
2 -> failed dependency
3 -> failed other
4 -> cancelled

weather

Build weather, as an integer.

-1 -> unknown
0 -> new-success
1 -> new-failure
2 -> still-succeeding
3 -> still-failing

busy

Whether the build is pending, as an integer.

priority

Build priority, as an integer.

finished

Build finished, as an integer.

buildproducts

Build products in store as a JSON object.

8.4 Build raw log output

It is possible to ask Cuirass for the raw build output log with the API "/build/build-id/log/raw" where build-id is the unique id associated to the build in database.

The output is a raw text, for example:

$ curl http://localhost:8080/build/2/log/raw

starting phase `set-SOURCE-DATE-EPOCH'
phase `set-SOURCE-DATE-EPOCH' succeeded after 0.0 seconds
starting phase `set-paths'
...

If requested build-id is not known, the HTTP code 404 is answered with a JSON error message. For example:

$ curl -s "http://localhost:8080/build/fff/log/raw"

{"error" : "Build with ID fff doesn't exist."}

8.5 Jobs

The list of jobs associated with a given evaluation can be obtained with the API "/api/jobs". The output is a JSON array of jobs.

This request accepts a mandatory parameter and multiple optional ones.

evaluation: The evaluation id. This parameter is mandatory.
names: Filter query result to jobs which names are part of the given names list, a comma separated list of job names.
system: Filter query result to jobs with the given system.

For example, to ask for the jobs of evaluation 12 for x86_64-linux:

$ curl "http://localhost:8080/api/jobs?evaluation=12&system=x86_64-linux"

or the emacs and emacs-minimal jobs of evaluation 12 for x86_64-linux:

$ curl "http://localhost:8080/api/jobs?evaluation=12&names=emacs.x86_64-linux,emacs-minimal.x86_64-linux"

The nominal output is a JSON object whose fields are described hereafter.

build: The unique build id associated with the job.
status: The build status, as an integer.
name: The job name, as a string.

8.6 Jobs history

The history of jobs across the last evaluations of a given specification can be optained with the API "/api/jobs/history".

This request accepts three mandatory parameters.

specification: The specification name. This parameter is mandatory.
names: Filter query result to jobs which names are part of the given names list, a comma separated list of job names. This parameter is mandatory.
nr: Limit query result to nr elements. This parameter is mandatory.

For example, to ask for the history of emacs.x86_64-linux and emacs-minimal.x86_64-linux jobs of the master specification over the last 10 evaluations:

$ curl "http://localhost:8080/api/jobs/history?spec=master&names=emacs.x86_64-linux,emacs-minimal.x86_64-linux&nr=10"

The nominal output is a JSON array which objects have the following field:

evaluation: The unique evaluation id.
checkouts: The evaluation checkouts as a JSON array.
name: The jobs list for this evaluation, as a JSON array.

8.7 Dashboard registration

The user can register a dashboard using the "/api/dashboard/register" API. This request accepts two mandatory parameters.

specification: The specification name. This parameter is mandatory.
names: The dashboard jobs names, where names is a comma separated list of job names. This parameter is mandatory.

For example, to register a dashboard for the emacs.x86_64-linux and emacs-minimal.x86_64-linux jobs of the master specification:

$ curl "http://localhost:8080/api/dashboard/register?spec=master&names=emacs.x86_64-linux,emacs-minimal.x86_64-linux"

The nominal output is a JSON object which contains a unique field:

id: The registered dashboard id.

The dashboard is then accessible at the following address: http://localhost:8080/dashboard/<id>.

8.8 Latest builds

The list of latest builds can be obtained with the API "/api/latestbuilds". The output is a JSON array of builds. Builds are represented as in the "/build/build-id" API.

This request accepts a mandatory parameter and multiple optional ones.

nr: Limit query result to nr elements. This parameter is mandatory.
jobset: Filter query result to builds with the given jobset.
job: Filter query result to builds with the given job name.
system: Filter query result to builds with the given system.

For example, to ask for the ten last builds:

$ curl "http://localhost:8080/api/latestbuilds?nr=10"

or the five last builds where jobset “guix”:

$ curl "http://localhost:8080/api/latestbuilds?nr=5&jobset=guix"

If no builds matching given parameters are found, an empty JSON array is returned.

8.9 Queued builds

The list of queued builds can be obtained with the API "/api/queue". The output is a JSON array of builds. Builds are represented as in the "/build/build-id" API.

This request accepts a mandatory parameter.

nr: Limit query result to nr elements. This parameter is mandatory.