API

This is an API reference for select parts of the dashboard and the entirety of the runner.

Dashboard

Requests are authenticated using the cookies obtained from the login route. Please refer to the permissions to see when authentication is required.

Authentication

GET /me

Returns the self user with status 200, or if not authenticated 401.

Example response:

{
  "id": 1,
  "name": "example"
}

POST /login

Attempts to log in with the username and password specified in the body. Returns 200 on successful authentication, 400 if the credentials aren't supplied properly, 401 if the credentials are incorrect. More importantly, this will return a cookie that can be used to authenticate requests to restricted endpoints.

Example request:

{
  "username": "demouser",
  "password": "demouser"
}

POST /logout

Logs out, if applicable. Returns 200.

Triggering

POST /trigger/:token

Triggers the pipeline associated with that token. Returns 400 if the pipeline cannot be run, 204 if the constraints are not met (see here) or 200 as soon as the run starts.

Runs

GET /api/runs/:pipelineId/:runID/log

Gets the log associated with the given pipeline ID and run ID. Returns 200 and the log, or 404 if it was not found. runId can be set to last to refer to the run that was started last.

GET /api/runs/:pipelineID/:runID/archive?file=filename&mode=mode

Gets the archived file associated with the given pipeline ID and run ID. Requires a URI component encoded file name. Similarly, two modes are supported. stream returns the resource as a stream (best performance) and should be preferred. file transfers the entire file and adds significant overhead, but is required e.g. for browser downloads. Returns 200 and the archived file 400 if no file was specified, or 404 if it was not found. runId can be set to last to refer to the run that was started last.

Runner

GET /

Returns 200 without a body. Does not require authorization.

POST /run

When sending a pipeline request to a runner, the following format is required:

{
    "runId": "12345",
    "plan": {}
}

The runId is optional (defaults to a random hex string). If the pipeline is being triggered by a panel or something that has a run ID, this will force the runner to use this ID to make debugging easier.

The following describes the current pipeline plan.

Field	Type	Nullable	Description
stages	stage[]	No	A possibly empty array of pipeline stages.
archive	string[]	Yes	The paths of all the filenames that will be archived.

The following describes the current stage plan.

Field	Type	Nullable	Description
name	string	No	The name of the stage.
image	string	No	The name of the Docker image to use for the stage.
runtime	string	Yes	The runtime for the container. Defaults to the default system runtime.
environment	string[]	Yes	A possibly empty array of KEY=VALUE environment variables.
script	string[]	Yes	A possibly empty array of shell commands to execute in the container.

POST /logs/:runID

Gets the log associated with the given run ID from the runner's filesystem. Returns 200 and plaintext if the log was found, 400 if the request was detected to be malicious, and 404 if the log could not be found.