Add docs/ (note: this is largely unimplemented)
This commit is contained in:
Drew DeVault
parent
a3f8114937
commit
db54f210ec
|
|
@ -0,0 +1,200 @@
|
|||
API
|
||||
|
||||
The build.sr.ht API allows you to insert jobs, monitor their progress, and
|
||||
access some information about the build system. Authentication to this API is
|
||||
brokered by meta.sr.ht. This API uses standard sr.ht error responses.
|
||||
|
||||
API ENDPOINTS
|
||||
|
||||
POST /api/jobs
|
||||
Scopes: jobs:write
|
||||
Inserts a new job into the job queue.
|
||||
|
||||
{
|
||||
"manifest": "string", The build manifest
|
||||
"note": "string", Human-friendly description of this build
|
||||
(optional)
|
||||
"tags": [...], Arbitrary list of strings that identify this
|
||||
build and can be used to navigate the
|
||||
dashboard (optional)
|
||||
"access:read": [ List of users that have read access to this
|
||||
job (optional). The user submitting the
|
||||
build will be included regardless of this
|
||||
value. The special username "*" indicates
|
||||
public read access to this build.
|
||||
"string" Username
|
||||
],
|
||||
"access:write": [ List of users that have write access to this
|
||||
job (optional). The user submitting the
|
||||
build will be included regardless of this
|
||||
value.
|
||||
"string" Username
|
||||
],
|
||||
"triggers": [...], Post-build triggers (optional)
|
||||
"execute": boolean, True to start the build immediately
|
||||
(optional - defaults to true)
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
"id": integer
|
||||
}
|
||||
|
||||
GET /api/jobs/:id
|
||||
Scopes: jobs:read
|
||||
Gets information about a job by its ID.
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
"id": integer,
|
||||
"status": "job status enum",
|
||||
"logs": {
|
||||
"setup": "url", URL of captured stdout/stderr of setup
|
||||
phase (packages, repos, etc)
|
||||
"build": "url", URL of captured stdout/stderr of build
|
||||
phase (task outputs)
|
||||
},
|
||||
"tasks": [
|
||||
{
|
||||
"name": "setup",
|
||||
"status": "task status enum"
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
|
||||
Job status enum:
|
||||
- pending: waiting for user intervention to start
|
||||
- queued: queued to start when a worker is available
|
||||
- running: job is in-progress
|
||||
- success: build completed without errors
|
||||
- failed: build completed with errors
|
||||
|
||||
Task status enum:
|
||||
- pending: waiting for earlier tasks to complete
|
||||
- running: task is in-progress
|
||||
- success: task completed without errors
|
||||
- failed: task completed with errors
|
||||
|
||||
GET /api/jobs/:id/manifest
|
||||
Scopes: jobs:read
|
||||
Returns the build manifest for this job.
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
"manifest": "string"
|
||||
}
|
||||
|
||||
POST /api/jobs/:id/start
|
||||
Scopes: jobs:write
|
||||
Starts a build that has been postponed with "execute": false. Requires write
|
||||
access.
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
}
|
||||
|
||||
POST /api/jobs/:id/cancel
|
||||
Scopes: jobs:write
|
||||
Cancels a build that has yet to start. Requires write access.
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
}
|
||||
|
||||
POST /api/jobs/:id/duplicate
|
||||
Scopes: jobs:write
|
||||
Duplicates a job. Any JSON parameters passed into this endpoint will
|
||||
overwrite the corresponding parameters of the original job.
|
||||
|
||||
{
|
||||
(see description)
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
"id": integer ID of new job
|
||||
}
|
||||
|
||||
POST /api/groups
|
||||
Scopes: jobs:write
|
||||
Creates a new job group.
|
||||
|
||||
{
|
||||
"jobs": [...], List of job IDs to group
|
||||
"triggers": [...], Post-build triggers (optional)
|
||||
}
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
"id": "string"
|
||||
}
|
||||
|
||||
POST /api/groups/:id/start
|
||||
Scopes: jobs:write
|
||||
Starts all pending jobs in this build group (i.e. ones created with
|
||||
"execute": false).
|
||||
|
||||
Response:
|
||||
|
||||
{
|
||||
}
|
||||
|
||||
BUILD TRIGGERS
|
||||
|
||||
Build triggers can be used to perform specific tasks at the completion of a job
|
||||
or group of jobs. They are described with JSON:
|
||||
|
||||
{
|
||||
"condition": "string", One of "success", "failure", "always".
|
||||
"action": "string", Name of the action to perform
|
||||
...
|
||||
}
|
||||
|
||||
Several actions are available, and each one extends the build trigger JSON with
|
||||
additional attributes.
|
||||
|
||||
job:
|
||||
Inserts another job. The "job" property should be filled out as if it were
|
||||
being POSTed to /api/jobs.
|
||||
|
||||
{
|
||||
"job": (see description)
|
||||
}
|
||||
|
||||
email:
|
||||
Sends an email to one or more recipients. The subject line will be:
|
||||
Build #[id] [failed|success]: [description]
|
||||
|
||||
{
|
||||
"to": [...], List of email addresses (strings)
|
||||
}
|
||||
|
||||
irc:
|
||||
Sends a message to an IRC channel:
|
||||
Build #[id] [failed|success]: [description]
|
||||
|
||||
{
|
||||
"server": "string", Address of IRC server
|
||||
"port": integer, Port to use (optional - defaults to 6667)
|
||||
"ssl": boolean, Optional (default: false)
|
||||
"nick": "string",
|
||||
"user": "string", Optional
|
||||
"pass": "string", Optional
|
||||
"realname": "string", Optional
|
||||
"channels": [...], List of channels to send to
|
||||
}
|
||||
|
||||
webhook:
|
||||
HTTP POSTs the response of GET /api/jobs/:id to a given address
|
||||
|
||||
{
|
||||
"url": "string"
|
||||
}
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
MANIFESTS
|
||||
|
||||
A build manifest is a YAML file that describes how to perform a build. Here's an example:
|
||||
|
||||
image: archlinux
|
||||
packages:
|
||||
- cmake
|
||||
- wlc-git
|
||||
- xorg-server-xwayland
|
||||
- xcb-util-image
|
||||
- json-c
|
||||
- pango
|
||||
- cairo
|
||||
- wayland
|
||||
- gdk-pixbuf2
|
||||
- asciidoc
|
||||
repos:
|
||||
- https://github.com/SirCmpwn/sway
|
||||
tasks:
|
||||
- setup: |
|
||||
cd sway
|
||||
mkdir build
|
||||
cd build
|
||||
cmake ..
|
||||
- build: |
|
||||
cd sway
|
||||
cd build
|
||||
make
|
||||
|
||||
The minimum build manifest has an image and at least one task. The various
|
||||
properties available are described here:
|
||||
|
||||
image: string
|
||||
Which OS image to build in. List available images with /api/images.
|
||||
|
||||
packages: list
|
||||
A list of package names to install on the image. The details of this process
|
||||
varies from image to image.
|
||||
|
||||
repos: list (string)
|
||||
A list of git repositories to clone into the home directory of the build
|
||||
user in the build environment.
|
||||
|
||||
tasks: list (string)
|
||||
A list of scripts to execute in the build environment. These scripts are run
|
||||
with the following preamble:
|
||||
|
||||
#!/usr/bin/env bash
|
||||
. ~/.buildenv
|
||||
set -x
|
||||
set -e
|
||||
|
||||
~/.buildenv contains environment variables specified by the `environment`
|
||||
directive.
|
||||
|
||||
The text of each script may be encrypted with the build server's PGP key,
|
||||
which is provided via /api/pgp-key. In this case, `set -x` is omitted from
|
||||
the preamble, and the script will be decrypted before being sent to the
|
||||
build environment.
|
||||
|
||||
environment: dictionary (string: string OR string: list)
|
||||
A list of key/value pairs for options to set in the build environment via
|
||||
~/.buildenv.
|
||||
Loading…
Reference in New Issue