Key reference
Every key a runbook can use, in the order you’d meet them. The list of
keys comes from the compiler itself, so a key that isn’t here is refused
(spec.unknown_key). Every example is checked with runbook spec validate.
Paths are dotted: [] stands for any item of a list, and <name> for a
name you choose, such as an input’s. A step anywhere (inside steps,
parallel, foreach, catch and so on) takes the same keys as
spec.steps[]. For what a diagnostic means, see
diagnostics.
Document
Section titled “Document”A runbook is one YAML document with metadata and spec. Keys starting
with x- are allowed at every level: they are kept verbatim and never
executed. Every other unknown key is refused with spec.unknown_key.
apiVersion
Section titled “apiVersion”The language version. Optional; when present it must be
therunbook.app/v1 (spec.unsupported_api_version).
apiVersion: therunbook.app/v1kind: Runbookmetadata: { id: hello }spec: steps: - id: say_helloThe document kind. Optional; when present it must be Runbook
(spec.unsupported_kind).
kind: Runbookmetadata: { id: hello }spec: steps: - id: say_hellometadata
Section titled “metadata”Who the runbook is and who owns it. Only id is required.
metadata: id: post-deploy title: Post-deploy verificationspec: steps: - id: checkmetadata.id
Section titled “metadata.id”The runbook’s ID within its project: kebab case (lowercase letters and
digits, separated by single hyphens), at most 63 bytes
(spec.invalid_id). It names the runbook in the CLI, the API and call.
metadata: { id: cert-expiry-sweep }spec: steps: - id: list_certificatesmetadata.title
Section titled “metadata.title”A human title. Without one, the title is derived from the ID
(cert-expiry-sweep becomes “Cert expiry sweep”).
metadata: id: cert-expiry-sweep title: Certificate expiry sweepspec: steps: - id: list_certificatesmetadata.description
Section titled “metadata.description”A longer description, shown on the runbook’s page.
metadata: id: cert-expiry-sweep description: Finds certificates that expire in the next 30 days and renews them.spec: steps: - id: list_certificatesmetadata.tags
Section titled “metadata.tags”Tags for finding and grouping the runbook.
metadata: id: cert-expiry-sweep tags: [security, weekly]spec: steps: - id: list_certificatesmetadata.owners
Section titled “metadata.owners”The people or teams who own the runbook: team:<slug>, user:<name> or a
bare user name. Owners get reminders when a step has no one else to
remind, and an approval’s timeout escalates to them when it names no
escalate_to. They resolve against your server when you publish.
metadata: id: cert-expiry-sweep owners: [team:platform]spec: steps: - id: list_certificatesThe procedure: its inputs, steps and outputs. Only steps is required.
metadata: { id: hello }spec: steps: - id: say_helloRuns: spec.execution
Section titled “Runs: spec.execution”Settings for each run (execution) of the runbook.
spec.execution
Section titled “spec.execution”Run-level settings: the run’s title and tags, its timeout, and a concurrency limit.
metadata: { id: nightly-backup-check }spec: execution: title: Backup check timeout: 2h steps: - id: checkspec.execution.title
Section titled “spec.execution.title”The title each run gets. It may interpolate expressions, so runs are told apart in lists.
metadata: { id: post-deploy }spec: inputs: service: { type: string, required: true } execution: title: "Verify ${{ inputs.service }}" steps: - id: checkspec.execution.tags
Section titled “spec.execution.tags”Tags on every run. Runs can be listed by tag, and webhook subscriptions with a tag filter receive only matching runs’ events.
metadata: { id: post-deploy }spec: inputs: service: { type: string, required: true } execution: tags: [deploy, "${{ inputs.service }}"] steps: - id: checkspec.execution.timeout
Section titled “spec.execution.timeout”The most a whole run may take. A run past it times out and its cleanup
(finally) runs. It also bounds signal waits, which have no limit of
their own.
metadata: { id: post-deploy }spec: execution: { timeout: 4h } steps: - id: checkspec.execution.cleanup_timeout
Section titled “spec.execution.cleanup_timeout”How long the run’s cleanup (its finally steps after a timeout, a
failure or a cancel) may take before the run is closed anyway.
metadata: { id: db-migration }spec: execution: { timeout: 2h, cleanup_timeout: 15m } steps: - id: migrate finally: - id: release_lockspec.execution.concurrency
Section titled “spec.execution.concurrency”Limits how many runs with the same key run at once. Runs beyond the limit
are queued, refused or replace the running one, by on_conflict.
metadata: { id: deploy }spec: inputs: service: { type: string, required: true } execution: concurrency: key: "deploy-${{ inputs.service }}" limit: 1 steps: - id: deployspec.execution.concurrency.key
Section titled “spec.execution.concurrency.key”The pool a run joins. Runs share a limit only when their keys are equal, so a key built from an input limits per value (per service, per region).
metadata: { id: deploy }spec: inputs: region: { type: string, required: true } execution: concurrency: { key: "region-${{ inputs.region }}", limit: 1 } steps: - id: deployspec.execution.concurrency.limit
Section titled “spec.execution.concurrency.limit”How many runs with the same key may be open at once.
metadata: { id: load-test }spec: execution: concurrency: { key: load-test, limit: 2 } steps: - id: runspec.execution.concurrency.on_conflict
Section titled “spec.execution.concurrency.on_conflict”What a start does when the pool is full:
queuewaits for a slot (the run isqueuedand aexecution.queuedwebhook fires);rejectrefuses the start (409 execution.concurrency_conflict) and writes nothing;cancel_previouscancels the waiting runs and the running one (the oldest, whenlimitis more than 1) and queues the new run first in line; it starts once the cancelled run has finished its cleanup.
metadata: { id: preview-env }spec: inputs: branch: { type: string, required: true } execution: concurrency: key: "preview-${{ inputs.branch }}" limit: 1 on_conflict: cancel_previous steps: - id: buildData: inputs, fields, vars and outputs
Section titled “Data: inputs, fields, vars and outputs”spec.inputs
Section titled “spec.inputs”The values a run is started with, each a typed declaration (see Declarations). A start with a missing required input, or a value of the wrong type, is refused before the run exists.
metadata: { id: post-deploy }spec: inputs: service: { type: enum, options: [api, web], required: true } version: { type: string, pattern: "v[0-9]+\\.[0-9]+\\.[0-9]+" } steps: - id: check instructions: Check ${{ inputs.service }} at ${{ inputs.version }}.spec.fields
Section titled “spec.fields”Typed values on the run that steps can set, such as a severity or a
ticket link. They show on the run page, and up to 10 can be indexed to
search runs by them. Fields take every declaration key,
plus indexed and locked.
metadata: { id: incident-triage }spec: fields: severity: { type: enum, options: [sev1, sev2, sev3], default: sev3, indexed: true } steps: - id: classify set: { fields: { severity: sev2 } }spec.fields.<name>.indexed
Section titled “spec.fields.<name>.indexed”Makes a field searchable: runbook run list --field severity=sev1. At
most 10 indexed fields per runbook (spec.indexed_field_limit).
metadata: { id: incident-triage }spec: fields: severity: { type: string, indexed: true } steps: - id: classifyspec.fields.<name>.locked
Section titled “spec.fields.<name>.locked”Refuses edits to the field once the run has started
(data.locked_field), for values that must not change during a run.
metadata: { id: incident-triage }spec: fields: ticket_url: { type: url, locked: true } steps: - id: open_ticketspec.vars
Section titled “spec.vars”The run’s working variables, with their starting values. Steps change
them with set, and expressions read them as vars.<name>. A variable’s
starting value may be an expression over inputs and other variables
(cycles are refused with spec.variable_cycle).
metadata: { id: release }spec: inputs: version: { type: string, required: true } vars: result: undetermined tag: "release-${{ inputs.version }}" steps: - id: record set: { vars: { result: shipped } }spec.outputs
Section titled “spec.outputs”The run’s results, computed when it ends. They show on the run page and in
the run report, and a parent’s call step reads them.
metadata: { id: canary }spec: steps: - id: measure check: true outputs: error_rate: { type: number, required: true } outputs: error_rate: "${{ steps.measure.outputs.error_rate }}" verdict: "${{ steps.measure.verdict }}"spec.report
Section titled “spec.report”A Markdown summary rendered when the run finishes, with expressions interpolated. It shows at the top of the run report.
metadata: { id: canary }spec: inputs: service: { type: string, required: true } steps: - id: measure check: true report: | ## Canary for ${{ inputs.service }} Verdict: ${{ steps.measure.verdict }}Declarations
Section titled “Declarations”A declaration types one value: an input, a field, a step’s or signal’s
outputs, a call’s outputs or a webhook trigger’s payload. The same keys
apply everywhere. Declarations are closed: a value with an undeclared
property is refused, and no type accepts null.
spec.inputs.<name>
Section titled “spec.inputs.<name>”One declaration. Only type is needed; {} alone is not a valid
declaration.
service: { type: string, required: true }spec.inputs.<name>.type
Section titled “spec.inputs.<name>.type”The value’s type:
| Type | Values |
|---|---|
string |
One line of text |
text |
Text that may span lines |
number |
Any JSON number |
integer |
A whole number that fits in 64 bits |
boolean |
true or false |
enum |
One of options |
multi_enum |
A list of distinct options |
list |
A list of items |
object |
An object with properties |
date |
YYYY-MM-DD |
datetime |
An RFC 3339 timestamp |
duration |
A duration such as 90s, 15m or 1h30m |
url |
An absolute http or https URL |
email |
An email address |
user |
A person in your directory |
Anything else is refused with spec.unsupported_type.
deadline: { type: datetime, required: true }spec.inputs.<name>.title
Section titled “spec.inputs.<name>.title”The label shown on the start form and run page.
service: { type: string, title: Service name }spec.inputs.<name>.description
Section titled “spec.inputs.<name>.description”Help text shown under the field.
service: { type: string, description: The Kubernetes deployment to check. }spec.inputs.<name>.required
Section titled “spec.inputs.<name>.required”The value must be given. For an input that means at start; for step outputs, in the step’s report.
service: { type: string, required: true }spec.inputs.<name>.default
Section titled “spec.inputs.<name>.default”The value used when none is given. It must match the declaration.
environment: { type: enum, options: [staging, production], default: staging }spec.inputs.<name>.options
Section titled “spec.inputs.<name>.options”The allowed values of an enum or multi_enum.
region: { type: enum, options: [us-east, us-west, eu-west] }spec.inputs.<name>.min
Section titled “spec.inputs.<name>.min”The least allowed value: a number’s value, a string’s length in characters, or a list’s item count.
replicas: { type: integer, min: 1, max: 20 }spec.inputs.<name>.max
Section titled “spec.inputs.<name>.max”The greatest allowed value, measured like min.
reason: { type: text, max: 2000 }spec.inputs.<name>.pattern
Section titled “spec.inputs.<name>.pattern”A pattern the whole string must match (it is anchored at both ends). The
dialect runs in linear time: no backreferences or lookaround
(spec.invalid_pattern, spec.pattern_limit).
ticket: { type: string, pattern: "OPS-[0-9]+" }spec.inputs.<name>.items
Section titled “spec.inputs.<name>.items”The declaration of each item of a list.
regions: { type: list, items: { type: string }, default: [us-west, eu-west] }spec.inputs.<name>.properties
Section titled “spec.inputs.<name>.properties”The properties of an object. Objects are closed: undeclared properties
are refused.
owner: type: object properties: name: { type: string, required: true } slack: { type: string }Defaults: spec.defaults
Section titled “Defaults: spec.defaults”Settings every task inherits unless it sets its own.
spec.defaults
Section titled “spec.defaults”Task defaults. A task’s own key replaces the default one by one.
metadata: { id: agent-checks }spec: defaults: { actor: agent, timeout: 15m, on_failure: handoff } steps: - id: check_health - id: check_errorsspec.defaults.actor
Section titled “spec.defaults.actor”The default actor of every task.
metadata: { id: agent-checks }spec: defaults: { actor: agent } steps: - id: check_healthspec.defaults.timeout
Section titled “spec.defaults.timeout”The default timeout of every task. It applies to tasks only, not to
containers, waits or approvals.
metadata: { id: agent-checks }spec: defaults: { timeout: 10m } steps: - id: check_healthspec.defaults.on_failure
Section titled “spec.defaults.on_failure”The default on_failure of every task. handoff here is a common way to
make every agent failure a person’s job instead of the run’s end.
metadata: { id: agent-checks }spec: defaults: { actor: agent, on_failure: handoff } steps: - id: check_healthspec.defaults.retry
Section titled “spec.defaults.retry”How a failed task is retried. Tasks inherit it; a task’s own retry
replaces it key by key.
metadata: { id: flaky-checks }spec: defaults: retry: { max_attempts: 3, backoff: 30s, on: [timeout] } steps: - id: check_healthspec.defaults.retry.max_attempts
Section titled “spec.defaults.retry.max_attempts”The most attempts a task gets, the first included. 1 means no retry.
metadata: { id: flaky-checks }spec: defaults: retry: { max_attempts: 3 } steps: - id: check_healthspec.defaults.retry.backoff
Section titled “spec.defaults.retry.backoff”How long to wait before each retry.
metadata: { id: flaky-checks }spec: defaults: retry: { max_attempts: 3, backoff: 1m } steps: - id: check_healthspec.defaults.retry.on
Section titled “spec.defaults.retry.on”Retry only failures of these types: timeout, failed or call_failed.
Without on, any failure is retried. A lapsed lease isn’t a failure and
never uses an attempt.
metadata: { id: flaky-checks }spec: defaults: retry: { max_attempts: 2, on: [timeout] } steps: - id: check_healthspec.defaults.remind_after
Section titled “spec.defaults.remind_after”The default remind_after of every task.
metadata: { id: weekly-review }spec: defaults: { remind_after: 4h } steps: - id: review actor: humanspec.defaults.remind_every
Section titled “spec.defaults.remind_every”The default remind_every of every task. Needs remind_after.
metadata: { id: weekly-review }spec: defaults: { remind_after: 4h, remind_every: 1d } steps: - id: review actor: humanspec.defaults.escalate_after
Section titled “spec.defaults.escalate_after”The default escalate_after of every task. Comes with escalate_to.
metadata: { id: weekly-review }spec: defaults: { escalate_after: 2d, escalate_to: [team:leads] } steps: - id: review actor: humanspec.defaults.escalate_to
Section titled “spec.defaults.escalate_to”The default escalate_to of every task. Comes with escalate_after.
metadata: { id: weekly-review }spec: defaults: { escalate_after: 2d, escalate_to: [team:leads, user:dana] } steps: - id: review actor: humanSkills and agents
Section titled “Skills and agents”spec.skills
Section titled “spec.skills”The skills the runbook uses, by alias. Each value is a path whose last
segment names a skill uploaded to the project (runbook skill push).
Publishing pins each alias to the latest uploaded version of that skill.
metadata: { id: error-check }spec: skills: error_rates: ./skills/check-error-rates steps: - id: check skill: error_ratesspec.agents
Section titled “spec.agents”Settings for agents that work this runbook’s runs.
metadata: { id: post-deploy }spec: agents: params: { repo: acme/api, workflow: runbook-resume.yml } steps: - id: check actor: agentspec.agents.params
Section titled “spec.agents.params”Opaque parameters passed untouched to agent.work_available webhook
subscribers, so a launcher knows where to start the agent. At most 4,096
bytes encoded (spec.agents_params_too_large). The older
spec.agents.dispatch was removed (spec.agents_dispatch_removed).
metadata: { id: post-deploy }spec: agents: params: { repo: acme/api, workflow: runbook-resume.yml, ref: main } steps: - id: check actor: agentTriggers: spec.triggers
Section titled “Triggers: spec.triggers”Triggers start runs on their own. Only the latest published version’s triggers act, and an archived runbook’s never do. Each kind takes at most 16 entries, with IDs unique across both.
spec.triggers
Section titled “spec.triggers”Schedules and webhook triggers.
metadata: { id: nightly-sweep }spec: triggers: schedule: - { id: nightly, cron: "0 2 * * *", timezone: Europe/London } steps: - id: sweepspec.triggers.schedule
Section titled “spec.triggers.schedule”Runs on a cron schedule. Each tick starts one run, however many servers
see it, recorded as started by schedule:<id>.
metadata: { id: weekly-audit }spec: triggers: schedule: - { id: monday_morning, cron: "0 9 * * MON", timezone: America/New_York } steps: - id: auditspec.triggers.schedule[].id
Section titled “spec.triggers.schedule[].id”The schedule’s ID: lowercase letters, digits and _, starting with a
letter.
metadata: { id: nightly-sweep }spec: triggers: schedule: [{ id: nightly, cron: "0 2 * * *" }] steps: - id: sweepspec.triggers.schedule[].cron
Section titled “spec.triggers.schedule[].cron”Five fields: minute, hour, day of month, month and day of week, with
lists, ranges, steps and names (*/15, 1-5, MON,THU). Refused with
spec.invalid_cron.
metadata: { id: business-hours-check }spec: triggers: schedule: [{ id: every_15m, cron: "*/15 9-17 * * MON-FRI" }] steps: - id: checkspec.triggers.schedule[].timezone
Section titled “spec.triggers.schedule[].timezone”The zone the cron fields are matched in (spec.invalid_timezone).
metadata: { id: nightly-sweep }spec: triggers: schedule: [{ id: nightly, cron: "0 2 * * *", timezone: America/Los_Angeles }] steps: - id: sweepspec.triggers.schedule[].inputs
Section titled “spec.triggers.schedule[].inputs”Literal inputs for each scheduled run. They must match the runbook’s
inputs and give every required input that has no default
(spec.trigger_input_invalid).
metadata: { id: nightly-sweep }spec: inputs: environment: { type: enum, options: [staging, production], required: true } triggers: schedule: - { id: nightly, cron: "0 2 * * *", inputs: { environment: production } } steps: - id: sweepspec.triggers.schedule[].catch_up
Section titled “spec.triggers.schedule[].catch_up”How late a tick missed while the server was down may still start, at most 24 hours. Without it, a missed tick starts only if it’s a few minutes late; otherwise it’s skipped.
metadata: { id: nightly-sweep }spec: triggers: schedule: [{ id: nightly, cron: "0 2 * * *", catch_up: 6h }] steps: - id: sweepspec.triggers.webhook
Section titled “spec.triggers.webhook”Runs started by an HTTP call to
POST /v1/projects/{project}/runbooks/{runbook}/triggers/{id}, with a
token that may start runs in the project, in Authorization or as
?token= for senders that can’t set headers. The body is the sender’s
own JSON. Runs record webhook:<id> as who started them.
metadata: { id: post-deploy }spec: inputs: service: { type: string, required: true } triggers: webhook: - id: on_deploy payload: service: { type: string } status: { type: string } when: "${{ payload.status == 'success' }}" inputs: { service: "${{ payload.service }}" } steps: - id: checkspec.triggers.webhook[].id
Section titled “spec.triggers.webhook[].id”The trigger’s ID, the last segment of its URL.
metadata: { id: on-alert }spec: triggers: webhook: [{ id: pagerduty }] steps: - id: triagespec.triggers.webhook[].payload
Section titled “spec.triggers.webhook[].payload”The payload fields expressions may read, as declarations. Fields the sender adds beyond these are ignored.
metadata: { id: on-alert }spec: inputs: service: { type: string } triggers: webhook: - id: alertmanager payload: service: { type: string } inputs: { service: "${{ payload.service }}" } steps: - id: triagespec.triggers.webhook[].when
Section titled “spec.triggers.webhook[].when”Start a run only when this is true. It reads payload only; a field the
call leaves out makes it false (spec.trigger_when_type).
metadata: { id: on-deploy }spec: triggers: webhook: - id: github payload: environment: { type: string } when: "${{ payload.environment == 'production' }}" steps: - id: verifyspec.triggers.webhook[].inputs
Section titled “spec.triggers.webhook[].inputs”The run’s inputs, literal or computed from payload. A field the call
leaves out leaves that input to its default.
metadata: { id: on-deploy }spec: inputs: service: { type: string, default: api } triggers: webhook: - id: github payload: repository: { type: string } inputs: { service: "${{ payload.repository }}" } steps: - id: verifyspec.triggers.webhook[].dedupe
Section titled “spec.triggers.webhook[].dedupe”A key for repeated calls: a call whose dedupe equals an earlier one’s
returns that run instead of starting another.
metadata: { id: on-deploy }spec: triggers: webhook: - id: github payload: deployment_id: { type: string } dedupe: "${{ payload.deployment_id }}" steps: - id: verifySteps: common keys
Section titled “Steps: common keys”spec.steps is the list of steps. A step’s kind is set by the key it
carries: none of the keys below makes it a task; steps, parallel,
foreach, loop, switch, wait, approval, set, end or call
make it that kind (at most one: spec.control_conflict). These keys work
on every kind.
spec.steps
Section titled “spec.steps”The steps, run in order unless control flow says otherwise. Every step
has an id. At most 256 steps with IDs per runbook.
metadata: { id: two-steps }spec: steps: - id: first - id: secondspec.finally
Section titled “spec.finally”Steps that always run when the run ends: succeeded, failed, timed out or
cancelled. end isn’t allowed inside (spec.end_in_finally).
metadata: { id: guarded }spec: steps: - id: change finally: - id: notify instructions: Post the outcome to the channel.spec.steps[].id
Section titled “spec.steps[].id”The step’s ID: lowercase letters, digits and _, starting with a letter,
at most 63 bytes, unique in the runbook. Expressions read the step as
steps.<id>.
- id: check_error_ratespec.steps[].title
Section titled “spec.steps[].title”The step’s title. A task without one gets a title from its ID
(check_error_rate becomes “Check error rate”).
- id: check title: Check the 5xx ratespec.steps[].if
Section titled “spec.steps[].if”Runs the step only when this is true; otherwise the step is skipped.
metadata: { id: maybe-notify }spec: inputs: notify: { type: boolean, default: true } steps: - id: post_update if: "${{ inputs.notify }}"spec.steps[].on_failure
Section titled “spec.steps[].on_failure”What a failure of this step does:
failfails the enclosing group, and with it the run unless acatchhandles it;continuerecords the failure and moves on;handoff(tasks only,spec.handoff_requires_task) hands the step to a person instead of failing.
- id: optional_check on_failure: continuespec.steps[].timeout
Section titled “spec.steps[].timeout”The most one attempt of a task may take. Tasks only
(spec.timeout_requires_task); waits and approvals have their own
timeout.
- id: smoke_test actor: agent timeout: 10mspec.steps[].labels
Section titled “spec.steps[].labels”Your own tags on the step: at most 16, keys of lowercase letters, digits,
_, ., / or -, values at most 256 characters
(spec.invalid_labels). The engine ignores them; the run returns them with
each step.
- id: notify_customer labels: { audience: customer, channel: email }A task is work for a person or an agent: a step without a control key.
spec.steps[].actor
Section titled “spec.steps[].actor”Who may claim the task. The server tells people from agents by their credential, not by what they say.
- id: run_smoke_tests actor: agentspec.steps[].assignee
Section titled “spec.steps[].assignee”Who the task is for: team:<slug>, user:<name>, a bare user name, or an
expression. It puts the task in their inbox and notifications. By itself
it’s guidance: anyone actor allows may still claim it.
- id: review_change actor: human assignee: team:oncallspec.steps[].assignment
Section titled “spec.steps[].assignment”strict makes the assignee binding: on a human or any task only the
assignees may claim it, and on an agent task it limits who may take
over. Needs an assignee (spec.strict_assignment_without_assignee).
- id: approve_spend actor: human assignee: team:finance assignment: strictspec.steps[].instructions
Section titled “spec.steps[].instructions”What to do, in Markdown, with expressions interpolated. Give an object to write different instructions for people and agents.
- id: check_dashboard instructions: | Open the **errors** dashboard and compare the last hour with the hour before the deploy.spec.steps[].instructions.default
Section titled “spec.steps[].instructions.default”Instructions for whoever does the step, unless a more specific one is given.
- id: rotate_key instructions: default: Rotate the API key in the vault. agent: Run ./scripts/rotate-key.sh and attach its output.spec.steps[].instructions.human
Section titled “spec.steps[].instructions.human”Instructions shown to a person.
- id: rotate_key instructions: human: Rotate the key in the vault UI and paste the new key's ID. agent: Run ./scripts/rotate-key.sh and attach its output.spec.steps[].instructions.agent
Section titled “spec.steps[].instructions.agent”Instructions in an agent’s work brief.
- id: rotate_key actor: agent instructions: agent: Run ./scripts/rotate-key.sh and report the new key ID as an output.spec.steps[].check
Section titled “spec.steps[].check”Makes the task a check: its report also records a verdict, pass,
warn or fail, independent of its status. Later steps read it as
steps.<id>.verdict.
- id: error_rate_ok check: true instructions: Is the 5xx rate under 1%?spec.steps[].checklist
Section titled “spec.steps[].checklist”Items to tick while doing the task (runbook step checklist --tick).
- id: smoke_test actor: human checklist: - Login page loads - Dashboard shows dataspec.steps[].outputs
Section titled “spec.steps[].outputs”What the task reports, as declarations. A report whose outputs don’t
match is refused before anything is recorded. Later steps read
steps.<id>.outputs.<name>. At most 64 KiB per step.
- id: measure outputs: error_rate: { type: number, required: true } sample_url: { type: url }spec.steps[].evidence
Section titled “spec.steps[].evidence”Evidence the report must or may carry. Kinds are link, log, file
and screenshot.
- id: check_dashboard evidence: { required: [link], accepted: [screenshot] }spec.steps[].evidence.required
Section titled “spec.steps[].evidence.required”Kinds the report must include; a report without them is refused.
- id: check_dashboard evidence: { required: [link] }spec.steps[].evidence.accepted
Section titled “spec.steps[].evidence.accepted”Kinds the report may include. Without accepted, any kind is accepted.
- id: check_dashboard evidence: { accepted: [link, screenshot] }spec.steps[].skill
Section titled “spec.steps[].skill”Attaches one skill declared in spec.skills. The agent fetches its files
with runbook step skill-file.
metadata: { id: error-check }spec: skills: error_rates: ./skills/check-error-rates steps: - id: check actor: agent skill: error_ratesspec.steps[].skills
Section titled “spec.steps[].skills”Attaches up to 8 skills (spec.too_many_skills), with no duplicates
(spec.duplicate_skill). A step can’t use both skill and skills
(spec.both_skill_and_skills).
metadata: { id: rollback }spec: skills: error_rates: ./skills/check-error-rates rollback: ./skills/rollback-service steps: - id: roll_back actor: agent skills: [error_rates, rollback]spec.steps[].with
Section titled “spec.steps[].with”Parameters for the task, passed to whoever does it (often to its skill). Values may be expressions.
- id: scale actor: agent with: { replicas: 6, region: eu-west }spec.steps[].agent
Section titled “spec.steps[].agent”Hints for an agent. The server can’t see which tools an agent uses, so these are preferences, never enforced. Limit what an agent can do through the access you give it.
- id: query_logs actor: agent agent: hints: { tools: [grafana], commands: [kubectl logs] }spec.steps[].agent.hints
Section titled “spec.steps[].agent.hints”The explicit home for hints, passed to the agent as data.
- id: query_logs actor: agent agent: hints: { tools: [grafana] }spec.steps[].agent.hints.tools
Section titled “spec.steps[].agent.hints.tools”Tools the agent should prefer.
- id: query_logs actor: agent agent: hints: { tools: [grafana, sentry] }spec.steps[].agent.hints.commands
Section titled “spec.steps[].agent.hints.commands”Commands the agent should prefer.
- id: query_logs actor: agent agent: hints: { commands: ["kubectl logs deploy/api --since=1h"] }spec.steps[].agent.tools
Section titled “spec.steps[].agent.tools”The older spelling of agent.hints.tools, still accepted. Giving a hint
both ways is refused (spec.duplicate_agent_hint).
- id: query_logs actor: agent agent: { tools: [grafana] }spec.steps[].agent.commands
Section titled “spec.steps[].agent.commands”The older spelling of agent.hints.commands, still accepted.
- id: query_logs actor: agent agent: { commands: ["kubectl get pods"] }spec.steps[].destructive
Section titled “spec.steps[].destructive”Marks a task that changes something you can’t easily undo. An approval
that agents may decide, or that decides on its own at a timeout, can’t
lead to a destructive task (spec.agent_approval_destructive,
spec.auto_decision_destructive) unless the task opts in with
allow_auto_decision.
- id: drop_old_tables actor: agent destructive: truespec.steps[].allow_auto_decision
Section titled “spec.steps[].allow_auto_decision”Lets an approval’s automatic decision (on_timeout: { decide: … }) lead
to this destructive task. Agent decisions never may.
- id: roll_back actor: agent destructive: true allow_auto_decision: truespec.steps[].skippable
Section titled “spec.steps[].skippable”Lets the person or agent doing the task report it skipped
(step.not_skippable otherwise).
- id: update_status_page actor: human skippable: truespec.steps[].retry
Section titled “spec.steps[].retry”How a failed attempt is retried; the same keys as
spec.defaults.retry, which it replaces key by key.
- id: smoke_test actor: agent retry: { max_attempts: 3, backoff: 30s, on: [timeout, failed] }spec.steps[].remind_after
Section titled “spec.steps[].remind_after”Sends a step.reminder once the step has been open this long. Reminders
go to the step’s people: approvers, the assignee, whoever claimed it, a
handoff’s assignee; with none, the runbook’s owners. Tasks, waits and
approvals take it.
- id: sign_off actor: human remind_after: 2hspec.steps[].remind_every
Section titled “spec.steps[].remind_every”Repeats the reminder this often. Needs remind_after
(spec.followup_invalid).
- id: sign_off actor: human remind_after: 2h remind_every: 4hspec.steps[].escalate_after
Section titled “spec.steps[].escalate_after”Escalates once the step has been open this long: a step.escalated
notification goes to escalate_to, the task’s inbox entry adds them, and
they may claim it even under assignment: strict. Comes with
escalate_to. Tasks and waits take it; approvals escalate with
approval.escalate_to.
- id: sign_off actor: human escalate_after: 1d escalate_to: [team:eng-leads]spec.steps[].escalate_to
Section titled “spec.steps[].escalate_to”Who the step escalates to. Comes with escalate_after.
- id: sign_off actor: human escalate_after: 1d escalate_to: [team:eng-leads, user:dana]Groups: steps, catch and finally
Section titled “Groups: steps, catch and finally”spec.steps[].steps
Section titled “spec.steps[].steps”Makes the step a group: its steps run in order. A group can catch its
failures and run finally steps.
- id: migrate steps: - id: back_up - id: applyspec.steps[].catch
Section titled “spec.steps[].catch”Steps that run when one of the group’s steps fails. When they succeed, the group succeeds.
- id: migrate steps: - id: apply catch: - id: restore instructions: Restore from the backup.spec.steps[].catch_on
Section titled “spec.steps[].catch_on”Makes catch handle only these failure types: timeout, failed or
call_failed. Others propagate as if the group had no catch. Needs a
catch (spec.catch_on_without_catch).
- id: migrate steps: - id: apply catch_on: [timeout] catch: - id: kill_migrationspec.steps[].finally
Section titled “spec.steps[].finally”Steps that always run after the group, whether it succeeded or failed.
- id: maintenance steps: - id: drain_traffic - id: patch finally: - id: restore_trafficParallel
Section titled “Parallel”spec.steps[].parallel
Section titled “spec.steps[].parallel”Branches that run at the same time, at most 20 (spec.limit_exceeded).
Each branch is one step, often a group.
- id: canaries parallel: - id: canary_us check: true - id: canary_eu check: truespec.steps[].join
Section titled “spec.steps[].join”When the parallel succeeds: all branches, any one, or
{ at_least: n }. Once it has succeeded under any or at_least, or can
no longer succeed, its open branches are cancelled.
- id: mirrors join: any parallel: - id: mirror_a - id: mirror_bspec.steps[].join.at_least
Section titled “spec.steps[].join.at_least”The number of branches that must succeed.
- id: quorum join: { at_least: 2 } parallel: - id: replica_a - id: replica_b - id: replica_cspec.steps[].fail_fast
Section titled “spec.steps[].fail_fast”With join: all, cancels the other branches as soon as one fails.
(any and at_least already cancel once decided.)
- id: preflight fail_fast: true parallel: - id: disk_space - id: replication_lagforeach
Section titled “foreach”spec.steps[].foreach
Section titled “spec.steps[].foreach”Runs its steps once per item of a list. Inside, the item is a variable
(item, or the name in as) and index is its position. Later steps
read the iterations as steps.<id>.items.
metadata: { id: per-region }spec: inputs: regions: { type: list, items: { type: string }, default: [us-west, eu-west] } steps: - id: regions foreach: items: "${{ inputs.regions }}" as: region max_items: 10 steps: - id: deploy instructions: Roll out to ${{ region }}.spec.steps[].foreach.items
Section titled “spec.steps[].foreach.items”The list to iterate. A run whose list is longer than max_items fails
the step.
metadata: { id: per-host }spec: inputs: hosts: { type: list, items: { type: string }, required: true } steps: - id: hosts foreach: items: "${{ inputs.hosts }}" max_items: 50 steps: - id: patch instructions: Patch ${{ item }}.spec.steps[].foreach.as
Section titled “spec.steps[].foreach.as”The item variable’s name. It can’t shadow inputs, vars, fields,
steps, outputs, index or iteration (spec.alias_collision).
metadata: { id: per-region }spec: inputs: regions: { type: list, items: { type: string }, required: true } steps: - id: regions foreach: items: "${{ inputs.regions }}" as: region max_items: 10 steps: - id: verify instructions: Verify ${{ region }}.spec.steps[].foreach.key
Section titled “spec.steps[].foreach.key”A stable key per item, shown instead of the index. Keys must be unique.
metadata: { id: per-service }spec: inputs: services: type: list items: type: object properties: name: { type: string, required: true } required: true steps: - id: services foreach: items: "${{ inputs.services }}" key: "${{ item.name }}" max_items: 20 steps: - id: restartspec.steps[].foreach.concurrency
Section titled “spec.steps[].foreach.concurrency”How many items run at once.
metadata: { id: per-host }spec: inputs: hosts: { type: list, items: { type: string }, required: true } steps: - id: hosts foreach: items: "${{ inputs.hosts }}" concurrency: 5 max_items: 100 steps: - id: patchspec.steps[].foreach.max_items
Section titled “spec.steps[].foreach.max_items”The most items the step accepts, at most 100. It bounds the run’s
worst-case size, which runbook spec validate reports.
metadata: { id: per-host }spec: inputs: hosts: { type: list, items: { type: string }, required: true } steps: - id: hosts foreach: items: "${{ inputs.hosts }}" max_items: 25 steps: - id: patchspec.steps[].foreach.steps
Section titled “spec.steps[].foreach.steps”The steps run for each item.
metadata: { id: per-host }spec: inputs: hosts: { type: list, items: { type: string }, required: true } steps: - id: hosts foreach: items: "${{ inputs.hosts }}" max_items: 25 steps: - id: drain - id: patch - id: undrainspec.steps[].loop
Section titled “spec.steps[].loop”Repeats its steps until a condition holds (or while one does), tested
after each iteration. Inside, iteration counts from 0. Later steps read
steps.<id>.iterations, .satisfied and .exhausted.
metadata: { id: settle }spec: steps: - id: stabilize loop: until: "${{ steps.recheck.outputs.rate <= 0.01 }}" max_iterations: 3 delay: 5m steps: - id: recheck check: true outputs: rate: { type: number, required: true }spec.steps[].loop.until
Section titled “spec.steps[].loop.until”Stop once this is true. A loop takes until or while, not both
(spec.invalid_shape).
metadata: { id: wait-healthy }spec: steps: - id: poll loop: until: "${{ steps.probe.verdict == 'pass' }}" max_iterations: 10 steps: - id: probe check: truespec.steps[].loop.while
Section titled “spec.steps[].loop.while”Keep going while this is true.
metadata: { id: drain-queue }spec: steps: - id: drain loop: while: "${{ steps.batch.outputs.remaining > 0 }}" max_iterations: 50 steps: - id: batch outputs: remaining: { type: integer, required: true }spec.steps[].loop.max_iterations
Section titled “spec.steps[].loop.max_iterations”The most iterations, at most 50. A loop that reaches it without its
condition is exhausted.
metadata: { id: retry-until-green }spec: steps: - id: attempts loop: until: "${{ steps.ci.verdict == 'pass' }}" max_iterations: 5 steps: - id: ci check: truespec.steps[].loop.delay
Section titled “spec.steps[].loop.delay”How long to wait between iterations.
metadata: { id: wait-healthy }spec: steps: - id: poll loop: until: "${{ steps.probe.verdict == 'pass' }}" max_iterations: 12 delay: 5m steps: - id: probe check: truespec.steps[].loop.steps
Section titled “spec.steps[].loop.steps”The steps of one iteration.
metadata: { id: wait-healthy }spec: steps: - id: poll loop: until: "${{ steps.probe.verdict == 'pass' }}" max_iterations: 3 steps: - id: probe check: trueswitch
Section titled “switch”spec.steps[].switch
Section titled “spec.steps[].switch”Runs the steps of the first case whose when is true, or the default
steps when none is.
metadata: { id: route-by-severity }spec: inputs: severity: { type: enum, options: [sev1, sev2, sev3], required: true } steps: - id: route switch: cases: - when: "${{ inputs.severity == 'sev1' }}" steps: - id: page_oncall default: steps: - id: open_ticketspec.steps[].switch.cases
Section titled “spec.steps[].switch.cases”The cases, tested in order.
metadata: { id: route }spec: inputs: env: { type: enum, options: [staging, production], required: true } steps: - id: route switch: cases: - when: "${{ inputs.env == 'production' }}" steps: [{ id: careful_rollout }] - when: "${{ inputs.env == 'staging' }}" steps: [{ id: fast_rollout }]spec.steps[].switch.cases[].when
Section titled “spec.steps[].switch.cases[].when”The case’s condition.
metadata: { id: route }spec: inputs: error_rate: { type: number, required: true } steps: - id: route switch: cases: - when: "${{ inputs.error_rate > 0.05 }}" steps: [{ id: roll_back }]spec.steps[].switch.cases[].steps
Section titled “spec.steps[].switch.cases[].steps”The steps the case runs.
metadata: { id: route }spec: inputs: error_rate: { type: number, required: true } steps: - id: route switch: cases: - when: "${{ inputs.error_rate > 0.05 }}" steps: - id: page_oncall - id: roll_backspec.steps[].switch.default
Section titled “spec.steps[].switch.default”The steps to run when no case matches. Without it, nothing runs.
metadata: { id: route }spec: inputs: error_rate: { type: number, required: true } steps: - id: route switch: cases: - when: "${{ inputs.error_rate > 0.05 }}" steps: [{ id: roll_back }] default: steps: [{ id: keep }]spec.steps[].switch.default.steps
Section titled “spec.steps[].switch.default.steps”The default steps.
metadata: { id: route }spec: inputs: ok: { type: boolean, required: true } steps: - id: route switch: cases: - when: "${{ inputs.ok }}" steps: [{ id: celebrate }] default: steps: - id: investigatespec.steps[].wait
Section titled “spec.steps[].wait”Pauses its branch for a duration (for), until a time (until) or until
a signal arrives (signal): exactly one of the three
(spec.invalid_shape).
- id: soak wait: { for: 30m }spec.steps[].wait.for
Section titled “spec.steps[].wait.for”Wait this long, at most 7 days (spec.limit_exceeded).
- id: soak wait: { for: 2h }spec.steps[].wait.until
Section titled “spec.steps[].wait.until”Wait until this time, written as an RFC 3339 literal (it is checked as a
timestamp, so a datetime input, which is a string, can’t be used here).
A target more than 7 days after the wait starts fails the step
(limit.wait_exceeded).
- id: wait_for_window wait: { until: "2026-12-01T09:00:00Z" }spec.steps[].wait.signal
Section titled “spec.steps[].wait.signal”Wait for a named signal, sent with runbook run signal or
POST /v1/executions/{id}/signals/{name}. Bounded by the run’s own
timeout or the wait’s timeout.
- id: connect_store wait: { signal: store_connected, timeout: 14d }spec.steps[].wait.timeout
Section titled “spec.steps[].wait.timeout”The most the wait may take; past it the step times out.
- id: customer_reply wait: { signal: customer_replied, timeout: 3d }spec.steps[].wait.outputs
Section titled “spec.steps[].wait.outputs”The signal payload’s schema. A payload that doesn’t match is refused
(422 signal.invalid_payload) and the step keeps waiting; a valid one
becomes the step’s outputs. Signal waits only
(spec.wait_outputs_requires_signal).
- id: connect_store wait: signal: store_connected outputs: store_id: { type: string, required: true }approval
Section titled “approval”spec.steps[].approval
Section titled “spec.steps[].approval”A decision between options by named approvers. Later steps read
steps.<id>.outputs.decision, .comment and .decided_by. Agents can’t
decide it unless allow_agents says so.
- id: go_no_go approval: prompt: Ship to every region? options: [ship, hold] approvers: { teams: [release-managers] }spec.steps[].approval.prompt
Section titled “spec.steps[].approval.prompt”The question the approvers answer.
- id: go_no_go approval: prompt: Canaries look clean. Continue the rollout? options: [continue, roll_back] approvers: { teams: [oncall] }spec.steps[].approval.options
Section titled “spec.steps[].approval.options”The choices: strings, or objects with id, title and auto. IDs are
unique and non-empty.
- id: go_no_go approval: prompt: Continue? options: - { id: continue, title: Continue the rollout } - { id: roll_back, title: Roll back now } approvers: { teams: [oncall] }spec.steps[].approval.options[].id
Section titled “spec.steps[].approval.options[].id”The option’s ID, the value of outputs.decision.
- id: go_no_go approval: prompt: Continue? options: [{ id: continue }, { id: stop }] approvers: { users: [dana] }spec.steps[].approval.options[].title
Section titled “spec.steps[].approval.options[].title”The option’s label. Defaults to its ID.
- id: go_no_go approval: prompt: Continue? options: [{ id: continue, title: "Yes, continue" }, { id: stop, title: Stop here }] approvers: { users: [dana] }spec.steps[].approval.options[].auto
Section titled “spec.steps[].approval.options[].auto”Marks the option an automatic decision (on_timeout: { decide: … }) may
choose (spec.auto_option_required).
- id: go_no_go approval: prompt: Errors are up. Roll back? options: [keep, { id: roll_back, auto: true }] approvers: { teams: [oncall] } timeout: 30m on_timeout: { decide: roll_back }spec.steps[].approval.approvers
Section titled “spec.steps[].approval.approvers”Who may decide: users and teams. Publishing requires approvers
(spec.approvers_required); they resolve against your directory.
- id: go_no_go approval: prompt: Ship it? options: [ship, hold] approvers: { users: [dana], teams: [release-managers] }spec.steps[].approval.approvers.users
Section titled “spec.steps[].approval.approvers.users”People who may decide.
- id: sign_off approval: prompt: Sign off on the migration? options: [approve, reject] approvers: { users: [dana, lee] }spec.steps[].approval.approvers.teams
Section titled “spec.steps[].approval.approvers.teams”Teams whose members may decide.
- id: sign_off approval: prompt: Sign off on the migration? options: [approve, reject] approvers: { teams: [dba] }spec.steps[].approval.min
Section titled “spec.steps[].approval.min”How many approvers must choose the same option.
- id: two_person_rule approval: prompt: Delete the production bucket? options: [delete, keep] approvers: { teams: [security] } min: 2spec.steps[].approval.timeout
Section titled “spec.steps[].approval.timeout”How long the approval waits before on_timeout applies.
- id: go_no_go approval: prompt: Ship it? options: [ship, hold] approvers: { teams: [oncall] } timeout: 1h escalate_to: [team:eng-leads]spec.steps[].approval.on_timeout
Section titled “spec.steps[].approval.on_timeout”What happens at timeout: escalate (to escalate_to, or the runbook’s
owners) or { decide: <option> }, an automatic decision for an auto
option. Needs timeout (spec.on_timeout_requires_timeout).
- id: go_no_go approval: prompt: Ship it? options: [ship, hold] approvers: { teams: [oncall] } timeout: 2h on_timeout: escalate escalate_to: [team:eng-leads]spec.steps[].approval.on_timeout.decide
Section titled “spec.steps[].approval.on_timeout.decide”The option chosen automatically at the timeout. It must be an auto
option, and it can’t lead to a destructive task unless that task sets
allow_auto_decision.
- id: go_no_go approval: prompt: Errors are up. Roll back? options: [keep, { id: roll_back, auto: true }] approvers: { teams: [oncall] } timeout: 15m on_timeout: { decide: roll_back }spec.steps[].approval.escalate_to
Section titled “spec.steps[].approval.escalate_to”Who gets the approval when it escalates at its timeout. Without it, the
runbook’s metadata.owners (spec.escalation_recipients_required when
there are none).
- id: go_no_go approval: prompt: Ship it? options: [ship, hold] approvers: { teams: [oncall] } timeout: 30m escalate_to: [team:eng-leads]spec.steps[].approval.escalation_timeout
Section titled “spec.steps[].approval.escalation_timeout”How long the escalated approval waits before it expires.
- id: go_no_go approval: prompt: Ship it? options: [ship, hold] approvers: { teams: [oncall] } timeout: 30m escalate_to: [team:eng-leads] escalation_timeout: 2hspec.steps[].approval.on_expired
Section titled “spec.steps[].approval.on_expired”What an approval that expires undecided does: pause the run for a
person to pick up, or fail the step.
- id: go_no_go approval: prompt: Ship it? options: [ship, hold] approvers: { teams: [oncall] } timeout: 30m escalate_to: [team:eng-leads] on_expired: failspec.steps[].approval.allow_agents
Section titled “spec.steps[].approval.allow_agents”Lets an agent decide. Needs min: 1
(spec.agent_approval_requires_min_one), and no destructive task may
follow from the decision (spec.agent_approval_destructive). An agent’s
decision is recorded apart from human signatures.
- id: triage_choice approval: prompt: Which runbook fits this alert? options: [restart, scale_up, escalate] approvers: { teams: [oncall] } allow_agents: trueset and end
Section titled “set and end”spec.steps[].set
Section titled “spec.steps[].set”Sets variables and fields. Values may be expressions.
metadata: { id: classify }spec: fields: severity: { type: string } vars: result: unknown steps: - id: record set: fields: { severity: major } vars: { result: degraded }spec.steps[].set.vars
Section titled “spec.steps[].set.vars”New values for variables declared in spec.vars.
metadata: { id: tally }spec: vars: { outcome: pending } steps: - id: done set: { vars: { outcome: done } }spec.steps[].set.fields
Section titled “spec.steps[].set.fields”New values for fields declared in spec.fields; each must match its
declaration.
metadata: { id: incident }spec: fields: severity: { type: enum, options: [sev1, sev2, sev3] } steps: - id: escalate set: { fields: { severity: sev1 } }spec.steps[].end
Section titled “spec.steps[].end”Ends the run early with a status. Not allowed in finally
(spec.end_in_finally).
- id: nothing_to_do end: { status: succeeded, message: No certificates expire this month. }spec.steps[].end.status
Section titled “spec.steps[].end.status”The run’s final status.
- id: stop end: { status: cancelled }spec.steps[].end.message
Section titled “spec.steps[].end.message”Why the run ended, shown on the run page.
- id: stop end: { status: failed, message: The preflight found replication lag. }spec.steps[].call
Section titled “spec.steps[].call”Runs another published runbook of the same project as a child run and
waits for it; the step takes the child’s outcome. Calls nest at most 3
deep, and a runbook can’t reach itself (spec.call_depth_exceeded,
spec.call_cycle). Cancelling the run cancels the child.
- id: verify call: runbook: post-deploy-checks with: { service: api }spec.steps[].call.runbook
Section titled “spec.steps[].call.runbook”The child runbook’s ID (its kebab-case slug). It resolves when you
publish (spec.call_unresolved).
- id: verify call: { runbook: post-deploy-checks }spec.steps[].call.version
Section titled “spec.steps[].call.version”Pins a published version. Without it, the version that’s current when you publish is pinned.
- id: verify call: { runbook: post-deploy-checks, version: 4 }spec.steps[].call.with
Section titled “spec.steps[].call.with”The child’s inputs; values may be expressions. They must match the
child’s inputs (spec.call_unknown_input, spec.call_missing_input,
spec.call_input_type).
- id: verify call: runbook: post-deploy-checks with: { service: api, environment: production }spec.steps[].call.outputs
Section titled “spec.steps[].call.outputs”The child’s outputs this step exposes, read as
steps.<id>.outputs.<name>. Each must be one of the child’s outputs, of
a matching type (spec.call_unknown_output, spec.call_output_type).
- id: verify call: runbook: post-deploy-checks with: { service: api } outputs: error_rate: { type: number }