Pipeline definition

A complete example

This definition has all three triggers, two inputs, a matrix, a cloned environment, and jobs that clone repositories with permissions.git: read.

{  "name": "ci",  "environment": { "clone": "staging" },  "triggers": {    "schedule": ["0 3 * * 1-5"],    "webhook": true,    "after": { "pipeline": "build", "result": "success" }  },  "inputs": {    "target": { "options": ["staging", "prod"], "default": "staging" },    "note": { "default": "" }  },  "jobs": {    "lint": {      "packages": ["git", "[email protected]", "[email protected]"],      "permissions": { "git": "read" },      "steps": [        { "run": "git clone --branch main https://github.com/acme/payments workspace/payments" },        { "run": "cargo clippy --workspace", "cwd": "workspace/payments" }      ]    },    "test": {      "needs": ["lint"],      "if": "always() && needs.lint.result == 'success'",      "packages": ["git", "[email protected]", "[email protected]"],      "matrix": { "db": ["postgres16", "postgres17"] },      "timeoutMinutes": 30,      "permissions": { "registry": "push", "git": "read" },      "secrets": ["DEPLOY_TOKEN"],      "env": { "DB": "${{ matrix.db }}" },      "steps": [        { "run": "git clone https://github.com/acme/payments workspace/payments" },        { "run": "git clone https://github.com/acme/shared-config config" },        {          "name": "test",          "run": "cargo test --workspace",          "cwd": "workspace/payments",          "env": { "CI": "1", "TARGET": "${{ inputs.target }}", "NOTE": "${{ webhook.body.note }}" }        }      ]    }  }}

Rules for the whole document

A definition is camelCase JSON. Every object refuses an unknown key: a misspelled need or timeout is an error that names the key. A save checks the whole definition and reports every problem at once, each with its job and step.

The platform stores the definition in a canonical form. It keeps the order of jobs, inputs and matrix as you wrote them, sorts other maps and leaves out every default. Two spellings of one definition give the same hash, so a save of an equal definition makes no new version.

Pipeline keys

Triggers

A person can always start a run with the API, the CLI or an SDK, so there is no manual key. The keys of triggers add three more ways to start a run. A run from any of them uses the newest version at the time it starts.

A run from a trigger takes the default of every input. A definition with a trigger and a required input that has no default is refused, because no person is there to give a value.

A pipeline cannot follow itself. A chain of after triggers stops at a depth of 5, and the finishing run records the refusal. The target of after must exist when you save.

Webhook

The first save with "webhook": true makes the secret and returns the URL once. A save with "webhook": false deletes the secret. To replace the secret, rotate it, and the old URL stops at once. The call needs no token, so keep the URL secret.

A JSON body of at most 256 KiB is available as webhook.body. A body that is not JSON runs with no body. A pipeline takes 30 webhook calls in one minute. See the webhook route.

Cron

Five fields, minute hour day-of-month month weekday, in UTC. Each field is a comma list of *, N, A-B, any of those with /STEP, and N/STEP for N to the field's maximum.

There are no month or day names, no @daily macros, no seconds field and no L, W or #. When both day of month and weekday are restricted, a time matches if either does: 0 0 1 * 1 is the 1st and every Monday. A tick that the platform misses while it is down is dropped, not replayed.

Inputs

Each input is {options, default, required}. Every value is text: a 3 or true that you send is the text you wrote. Names follow [A-Za-z_][A-Za-z0-9_-]{0,39}.

A run can give only inputs the pipeline declares. A declared input with no value and no default reads as the empty string. Inside the pipeline, read inputs as ${{ inputs.name }}.

Environments

environment is a name, or {clone: name}, on the pipeline and on any job. A job's own value overrides a run request's, which overrides the pipeline's.

A clone is made once per run for each distinct clone target, named ci-{run}-{n}, and deleted when the run ends. Jobs with the same target share the one clone. Both forms can carry ${{ }}. Neither form can be empty. {clone: ...} takes no other key. The jobs of a run reach their environment through a hidden session the run creates, see Sessions.

Jobs

Each job is one sandbox. Its steps run in it in order, as one script. A failing step stops the job.

packages and image are exclusive: a job uses one. With none of them a job gets the platform base image with the package git. Job names follow [a-z0-9][a-z0-9-]{0,39}.

One more key is accepted and validated and does nothing yet: artifacts (list of paths).

Save the home

saveTo names a volume of the pipeline owner. fromSnapshot and saveTo name the same volume when both are set. A job with saveTo and no fromSnapshot starts from the newest version of the volume, or empty when the volume does not exist yet. An unpinned name is read when the job starts.

Two jobs that save to one name need an order in needs. A save counts one snapshots unit of the quota. A job that fails saves nothing. The run shows home and saved for each job. See Home and the save checks.

Permissions

{  "name": "web-tests",  "jobs": {    "test": {      "permissions": { "git": "read" },      "steps": [        { "run": "git clone https://github.com/acme/web" },        { "run": "make test", "cwd": "web" }      ]    }  }}

A job with git: read can read every repository the GitHub App is installed on, a webhook run included. A GitLab credential reads only the one project that the connector picked. A job env that sets GIT_CONFIG_COUNT replaces the platform's credential helper.

Matrix

The first axis varies slowest, each axis in the order written. {db: [a, b], os: [x, y]} makes (a, x) (a, y) (b, x) (b, y). An instance is named test (a, x), and a job with no matrix is named by its job name alone. needs.test.result reads one result for the whole job: failure if any instance failed, else cancelled if any was cancelled, else success if any succeeded, else skipped.

Steps

A step is one shell command. run is required: a step without it is refused with a step needs `run` .

Variables that the platform sets

Every step also gets these variables. A job or step env entry with the same name replaces it.

Expressions

${{ ... }} interpolates into the fields marked interpolated above. if takes the expression bare or wholly inside one ${{ }}.

The body of a webhook call is text that the sender controls. For that reason it reaches a script only through an environment variable. Read it in env and use "$NAME" in run. A run, cwd, image, packages or environment that reads webhook.body is an error at save. A run or cwd that reads ${{ env.NAME }} is also an error when NAME gets its value from webhook.body.

Where each name is available:

Reading a name that does not exist, such as inputs.nope, is an error. A save finds it where it can, and otherwise the job fails.

Literals are 'single' strings ('' for a quote inside), "double" strings with no escapes, numbers, true and false. Operators, tightest first: !, == and !=, &&, ||, and parentheses. Every value is text. == is case-sensitive, except that a number compares numerically with text that parses as one, and true or false compares with that text. Truthy is true, a non-empty string or a non-zero number.

The functions success(), failure(), always() and cancelled() work in if only. An if that calls none of them is success() && (the condition), so a job whose needs failed does not run unless its if says so, for example with always(). There is no indexing, no string function and no arithmetic; a step has a shell for those.