Skip to content

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.

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.

Type string Default therunbook.app/v1

The language version. Optional; when present it must be therunbook.app/v1 (spec.unsupported_api_version).

Example
apiVersion: therunbook.app/v1
kind: Runbook
metadata: { id: hello }
spec:
steps:
- id: say_hello

Type string Default Runbook

The document kind. Optional; when present it must be Runbook (spec.unsupported_kind).

Example
kind: Runbook
metadata: { id: hello }
spec:
steps:
- id: say_hello

Type object Required

Who the runbook is and who owns it. Only id is required.

Example
metadata:
id: post-deploy
title: Post-deploy verification
spec:
steps:
- id: check

Type string Required

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.

Example
metadata: { id: cert-expiry-sweep }
spec:
steps:
- id: list_certificates

Type string

A human title. Without one, the title is derived from the ID (cert-expiry-sweep becomes “Cert expiry sweep”).

Example
metadata:
id: cert-expiry-sweep
title: Certificate expiry sweep
spec:
steps:
- id: list_certificates

Type string

A longer description, shown on the runbook’s page.

Example
metadata:
id: cert-expiry-sweep
description: Finds certificates that expire in the next 30 days and renews them.
spec:
steps:
- id: list_certificates

Type list of strings

Tags for finding and grouping the runbook.

Example
metadata:
id: cert-expiry-sweep
tags: [security, weekly]
spec:
steps:
- id: list_certificates

Type list of recipients

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.

Example
metadata:
id: cert-expiry-sweep
owners: [team:platform]
spec:
steps:
- id: list_certificates

Type object Required

The procedure: its inputs, steps and outputs. Only steps is required.

Example
metadata: { id: hello }
spec:
steps:
- id: say_hello

Settings for each run (execution) of the runbook.

Type object

Run-level settings: the run’s title and tags, its timeout, and a concurrency limit.

Example
metadata: { id: nightly-backup-check }
spec:
execution:
title: Backup check
timeout: 2h
steps:
- id: check

Type string or template

The title each run gets. It may interpolate expressions, so runs are told apart in lists.

Example
metadata: { id: post-deploy }
spec:
inputs:
service: { type: string, required: true }
execution:
title: "Verify ${{ inputs.service }}"
steps:
- id: check

Type list of strings or templates

Tags on every run. Runs can be listed by tag, and webhook subscriptions with a tag filter receive only matching runs’ events.

Example
metadata: { id: post-deploy }
spec:
inputs:
service: { type: string, required: true }
execution:
tags: [deploy, "${{ inputs.service }}"]
steps:
- id: check

Type duration

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.

Example
metadata: { id: post-deploy }
spec:
execution: { timeout: 4h }
steps:
- id: check

Type duration Default 30m

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.

Example
metadata: { id: db-migration }
spec:
execution: { timeout: 2h, cleanup_timeout: 15m }
steps:
- id: migrate
finally:
- id: release_lock

Type object

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.

Example
metadata: { id: deploy }
spec:
inputs:
service: { type: string, required: true }
execution:
concurrency:
key: "deploy-${{ inputs.service }}"
limit: 1
steps:
- id: deploy

Type string or template Required

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).

Example
metadata: { id: deploy }
spec:
inputs:
region: { type: string, required: true }
execution:
concurrency: { key: "region-${{ inputs.region }}", limit: 1 }
steps:
- id: deploy

Type positive integer Required

How many runs with the same key may be open at once.

Example
metadata: { id: load-test }
spec:
execution:
concurrency: { key: load-test, limit: 2 }
steps:
- id: run

Type queue | reject | cancel_previous Default queue

What a start does when the pool is full:

  • queue waits for a slot (the run is queued and a execution.queued webhook fires);
  • reject refuses the start (409 execution.concurrency_conflict) and writes nothing;
  • cancel_previous cancels the waiting runs and the running one (the oldest, when limit is more than 1) and queues the new run first in line; it starts once the cancelled run has finished its cleanup.
Example
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: build

Type map of declarations

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.

Example
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 }}.

Type map of declarations

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.

Example
metadata: { id: incident-triage }
spec:
fields:
severity: { type: enum, options: [sev1, sev2, sev3], default: sev3, indexed: true }
steps:
- id: classify
set: { fields: { severity: sev2 } }

Type boolean Default false

Makes a field searchable: runbook run list --field severity=sev1. At most 10 indexed fields per runbook (spec.indexed_field_limit).

Example
metadata: { id: incident-triage }
spec:
fields:
severity: { type: string, indexed: true }
steps:
- id: classify

Type boolean Default false

Refuses edits to the field once the run has started (data.locked_field), for values that must not change during a run.

Example
metadata: { id: incident-triage }
spec:
fields:
ticket_url: { type: url, locked: true }
steps:
- id: open_ticket

Type map of values

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).

Example
metadata: { id: release }
spec:
inputs:
version: { type: string, required: true }
vars:
result: undetermined
tag: "release-${{ inputs.version }}"
steps:
- id: record
set: { vars: { result: shipped } }

Type map of expressions

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.

Example
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 }}"

Type template

A Markdown summary rendered when the run finishes, with expressions interpolated. It shows at the top of the run report.

Example
metadata: { id: canary }
spec:
inputs:
service: { type: string, required: true }
steps:
- id: measure
check: true
report: |
## Canary for ${{ inputs.service }}
Verdict: ${{ steps.measure.verdict }}

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.

Type object

One declaration. Only type is needed; {} alone is not a valid declaration.

Example
service: { type: string, required: true }

Type string Required

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.

Example
deadline: { type: datetime, required: true }

Type string

The label shown on the start form and run page.

Example
service: { type: string, title: Service name }

Type string

Help text shown under the field.

Example
service: { type: string, description: The Kubernetes deployment to check. }

Type boolean Default false

The value must be given. For an input that means at start; for step outputs, in the step’s report.

Example
service: { type: string, required: true }

Type value

The value used when none is given. It must match the declaration.

Example
environment: { type: enum, options: [staging, production], default: staging }

Type list

The allowed values of an enum or multi_enum.

Example
region: { type: enum, options: [us-east, us-west, eu-west] }

Type number

The least allowed value: a number’s value, a string’s length in characters, or a list’s item count.

Example
replicas: { type: integer, min: 1, max: 20 }

Type number

The greatest allowed value, measured like min.

Example
reason: { type: text, max: 2000 }

Type regular expression

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).

Example
ticket: { type: string, pattern: "OPS-[0-9]+" }

Type declaration

The declaration of each item of a list.

Example
regions: { type: list, items: { type: string }, default: [us-west, eu-west] }

Type map of declarations

The properties of an object. Objects are closed: undeclared properties are refused.

Example
owner:
type: object
properties:
name: { type: string, required: true }
slack: { type: string }

Settings every task inherits unless it sets its own.

Type object

Task defaults. A task’s own key replaces the default one by one.

Example
metadata: { id: agent-checks }
spec:
defaults: { actor: agent, timeout: 15m, on_failure: handoff }
steps:
- id: check_health
- id: check_errors

Type human | agent | any Default any

The default actor of every task.

Example
metadata: { id: agent-checks }
spec:
defaults: { actor: agent }
steps:
- id: check_health

Type duration

The default timeout of every task. It applies to tasks only, not to containers, waits or approvals.

Example
metadata: { id: agent-checks }
spec:
defaults: { timeout: 10m }
steps:
- id: check_health

Type fail | continue | handoff Default fail

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.

Example
metadata: { id: agent-checks }
spec:
defaults: { actor: agent, on_failure: handoff }
steps:
- id: check_health

Type object

How a failed task is retried. Tasks inherit it; a task’s own retry replaces it key by key.

Example
metadata: { id: flaky-checks }
spec:
defaults:
retry: { max_attempts: 3, backoff: 30s, on: [timeout] }
steps:
- id: check_health

Type positive integer Default 1

The most attempts a task gets, the first included. 1 means no retry.

Example
metadata: { id: flaky-checks }
spec:
defaults:
retry: { max_attempts: 3 }
steps:
- id: check_health

Type duration

How long to wait before each retry.

Example
metadata: { id: flaky-checks }
spec:
defaults:
retry: { max_attempts: 3, backoff: 1m }
steps:
- id: check_health

Type list of failure types

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.

Example
metadata: { id: flaky-checks }
spec:
defaults:
retry: { max_attempts: 2, on: [timeout] }
steps:
- id: check_health

Type duration

The default remind_after of every task.

Example
metadata: { id: weekly-review }
spec:
defaults: { remind_after: 4h }
steps:
- id: review
actor: human

Type duration

The default remind_every of every task. Needs remind_after.

Example
metadata: { id: weekly-review }
spec:
defaults: { remind_after: 4h, remind_every: 1d }
steps:
- id: review
actor: human

Type duration

The default escalate_after of every task. Comes with escalate_to.

Example
metadata: { id: weekly-review }
spec:
defaults: { escalate_after: 2d, escalate_to: [team:leads] }
steps:
- id: review
actor: human

Type list of recipients

The default escalate_to of every task. Comes with escalate_after.

Example
metadata: { id: weekly-review }
spec:
defaults: { escalate_after: 2d, escalate_to: [team:leads, user:dana] }
steps:
- id: review
actor: human

Type map of paths

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.

Example
metadata: { id: error-check }
spec:
skills:
error_rates: ./skills/check-error-rates
steps:
- id: check
skill: error_rates

Type object

Settings for agents that work this runbook’s runs.

Example
metadata: { id: post-deploy }
spec:
agents:
params: { repo: acme/api, workflow: runbook-resume.yml }
steps:
- id: check
actor: agent

Type object

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).

Example
metadata: { id: post-deploy }
spec:
agents:
params: { repo: acme/api, workflow: runbook-resume.yml, ref: main }
steps:
- id: check
actor: agent

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.

Type object

Schedules and webhook triggers.

Example
metadata: { id: nightly-sweep }
spec:
triggers:
schedule:
- { id: nightly, cron: "0 2 * * *", timezone: Europe/London }
steps:
- id: sweep

Type list

Runs on a cron schedule. Each tick starts one run, however many servers see it, recorded as started by schedule:<id>.

Example
metadata: { id: weekly-audit }
spec:
triggers:
schedule:
- { id: monday_morning, cron: "0 9 * * MON", timezone: America/New_York }
steps:
- id: audit

Type string Required

The schedule’s ID: lowercase letters, digits and _, starting with a letter.

Example
metadata: { id: nightly-sweep }
spec:
triggers:
schedule: [{ id: nightly, cron: "0 2 * * *" }]
steps:
- id: sweep

Type string Required

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.

Example
metadata: { id: business-hours-check }
spec:
triggers:
schedule: [{ id: every_15m, cron: "*/15 9-17 * * MON-FRI" }]
steps:
- id: check

Type IANA time zone Default UTC

The zone the cron fields are matched in (spec.invalid_timezone).

Example
metadata: { id: nightly-sweep }
spec:
triggers:
schedule: [{ id: nightly, cron: "0 2 * * *", timezone: America/Los_Angeles }]
steps:
- id: sweep

Type map of values

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).

Example
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: sweep

Type duration

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.

Example
metadata: { id: nightly-sweep }
spec:
triggers:
schedule: [{ id: nightly, cron: "0 2 * * *", catch_up: 6h }]
steps:
- id: sweep

Type list

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.

Example
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: check

Type string Required

The trigger’s ID, the last segment of its URL.

Example
metadata: { id: on-alert }
spec:
triggers:
webhook: [{ id: pagerduty }]
steps:
- id: triage

Type map of declarations

The payload fields expressions may read, as declarations. Fields the sender adds beyond these are ignored.

Example
metadata: { id: on-alert }
spec:
inputs:
service: { type: string }
triggers:
webhook:
- id: alertmanager
payload:
service: { type: string }
inputs: { service: "${{ payload.service }}" }
steps:
- id: triage

Type expression → boolean

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).

Example
metadata: { id: on-deploy }
spec:
triggers:
webhook:
- id: github
payload:
environment: { type: string }
when: "${{ payload.environment == 'production' }}"
steps:
- id: verify

Type map of values or expressions

The run’s inputs, literal or computed from payload. A field the call leaves out leaves that input to its default.

Example
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: verify

Type expression → string

A key for repeated calls: a call whose dedupe equals an earlier one’s returns that run instead of starting another.

Example
metadata: { id: on-deploy }
spec:
triggers:
webhook:
- id: github
payload:
deployment_id: { type: string }
dedupe: "${{ payload.deployment_id }}"
steps:
- id: verify

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.

Type list of steps Required

The steps, run in order unless control flow says otherwise. Every step has an id. At most 256 steps with IDs per runbook.

Example
metadata: { id: two-steps }
spec:
steps:
- id: first
- id: second

Type list of steps

Steps that always run when the run ends: succeeded, failed, timed out or cancelled. end isn’t allowed inside (spec.end_in_finally).

Example
metadata: { id: guarded }
spec:
steps:
- id: change
finally:
- id: notify
instructions: Post the outcome to the channel.

Type string Required

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>.

Example
- id: check_error_rate

Type string or template

The step’s title. A task without one gets a title from its ID (check_error_rate becomes “Check error rate”).

Example
- id: check
title: Check the 5xx rate

Type expression → boolean

Runs the step only when this is true; otherwise the step is skipped.

Example
metadata: { id: maybe-notify }
spec:
inputs:
notify: { type: boolean, default: true }
steps:
- id: post_update
if: "${{ inputs.notify }}"

Type fail | continue | handoff Default fail

What a failure of this step does:

  • fail fails the enclosing group, and with it the run unless a catch handles it;
  • continue records the failure and moves on;
  • handoff (tasks only, spec.handoff_requires_task) hands the step to a person instead of failing.
Example
- id: optional_check
on_failure: continue

Type duration

The most one attempt of a task may take. Tasks only (spec.timeout_requires_task); waits and approvals have their own timeout.

Example
- id: smoke_test
actor: agent
timeout: 10m

Type map of strings

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.

Example
- id: notify_customer
labels: { audience: customer, channel: email }

A task is work for a person or an agent: a step without a control key.

Type human | agent | any Default any

Who may claim the task. The server tells people from agents by their credential, not by what they say.

Example
- id: run_smoke_tests
actor: agent

Type recipient or template

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.

Example
- id: review_change
actor: human
assignee: team:oncall

Type guidance | strict Default guidance

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).

Example
- id: approve_spend
actor: human
assignee: team:finance
assignment: strict

Type Markdown, or an object

What to do, in Markdown, with expressions interpolated. Give an object to write different instructions for people and agents.

Example
- id: check_dashboard
instructions: |
Open the **errors** dashboard and compare the last hour with the
hour before the deploy.

Type Markdown

Instructions for whoever does the step, unless a more specific one is given.

Example
- id: rotate_key
instructions:
default: Rotate the API key in the vault.
agent: Run ./scripts/rotate-key.sh and attach its output.

Type Markdown

Instructions shown to a person.

Example
- 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.

Type Markdown

Instructions in an agent’s work brief.

Example
- id: rotate_key
actor: agent
instructions:
agent: Run ./scripts/rotate-key.sh and report the new key ID as an output.

Type boolean Default false

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.

Example
- id: error_rate_ok
check: true
instructions: Is the 5xx rate under 1%?

Type list of strings

Items to tick while doing the task (runbook step checklist --tick).

Example
- id: smoke_test
actor: human
checklist:
- Login page loads
- Dashboard shows data

Type map of declarations

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.

Example
- id: measure
outputs:
error_rate: { type: number, required: true }
sample_url: { type: url }

Type object

Evidence the report must or may carry. Kinds are link, log, file and screenshot.

Example
- id: check_dashboard
evidence: { required: [link], accepted: [screenshot] }

Type list of evidence kinds

Kinds the report must include; a report without them is refused.

Example
- id: check_dashboard
evidence: { required: [link] }

Type list of evidence kinds

Kinds the report may include. Without accepted, any kind is accepted.

Example
- id: check_dashboard
evidence: { accepted: [link, screenshot] }

Type skill alias

Attaches one skill declared in spec.skills. The agent fetches its files with runbook step skill-file.

Example
metadata: { id: error-check }
spec:
skills:
error_rates: ./skills/check-error-rates
steps:
- id: check
actor: agent
skill: error_rates

Type list of skill aliases

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).

Example
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]

Type map of values

Parameters for the task, passed to whoever does it (often to its skill). Values may be expressions.

Example
- id: scale
actor: agent
with: { replicas: 6, region: eu-west }

Type object

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.

Example
- id: query_logs
actor: agent
agent:
hints: { tools: [grafana], commands: [kubectl logs] }

Type object

The explicit home for hints, passed to the agent as data.

Example
- id: query_logs
actor: agent
agent:
hints: { tools: [grafana] }

Type list

Tools the agent should prefer.

Example
- id: query_logs
actor: agent
agent:
hints: { tools: [grafana, sentry] }

Type list

Commands the agent should prefer.

Example
- id: query_logs
actor: agent
agent:
hints: { commands: ["kubectl logs deploy/api --since=1h"] }

Type list

The older spelling of agent.hints.tools, still accepted. Giving a hint both ways is refused (spec.duplicate_agent_hint).

Example
- id: query_logs
actor: agent
agent: { tools: [grafana] }

Type list

The older spelling of agent.hints.commands, still accepted.

Example
- id: query_logs
actor: agent
agent: { commands: ["kubectl get pods"] }

Type boolean Default false

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.

Example
- id: drop_old_tables
actor: agent
destructive: true

Type boolean Default false

Lets an approval’s automatic decision (on_timeout: { decide: … }) lead to this destructive task. Agent decisions never may.

Example
- id: roll_back
actor: agent
destructive: true
allow_auto_decision: true

Type boolean Default false

Lets the person or agent doing the task report it skipped (step.not_skippable otherwise).

Example
- id: update_status_page
actor: human
skippable: true

Type object

How a failed attempt is retried; the same keys as spec.defaults.retry, which it replaces key by key.

Example
- id: smoke_test
actor: agent
retry: { max_attempts: 3, backoff: 30s, on: [timeout, failed] }

Type duration

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.

Example
- id: sign_off
actor: human
remind_after: 2h

Type duration

Repeats the reminder this often. Needs remind_after (spec.followup_invalid).

Example
- id: sign_off
actor: human
remind_after: 2h
remind_every: 4h

Type duration

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.

Example
- id: sign_off
actor: human
escalate_after: 1d
escalate_to: [team:eng-leads]

Type list of recipients

Who the step escalates to. Comes with escalate_after.

Example
- id: sign_off
actor: human
escalate_after: 1d
escalate_to: [team:eng-leads, user:dana]

Type list of steps

Makes the step a group: its steps run in order. A group can catch its failures and run finally steps.

Example
- id: migrate
steps:
- id: back_up
- id: apply

Type list of steps

Steps that run when one of the group’s steps fails. When they succeed, the group succeeds.

Example
- id: migrate
steps:
- id: apply
catch:
- id: restore
instructions: Restore from the backup.

Type list of failure types

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).

Example
- id: migrate
steps:
- id: apply
catch_on: [timeout]
catch:
- id: kill_migration

Type list of steps

Steps that always run after the group, whether it succeeded or failed.

Example
- id: maintenance
steps:
- id: drain_traffic
- id: patch
finally:
- id: restore_traffic

Type list of steps

Branches that run at the same time, at most 20 (spec.limit_exceeded). Each branch is one step, often a group.

Example
- id: canaries
parallel:
- id: canary_us
check: true
- id: canary_eu
check: true

Type all | any | object Default all

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.

Example
- id: mirrors
join: any
parallel:
- id: mirror_a
- id: mirror_b

Type positive integer

The number of branches that must succeed.

Example
- id: quorum
join: { at_least: 2 }
parallel:
- id: replica_a
- id: replica_b
- id: replica_c

Type boolean Default false

With join: all, cancels the other branches as soon as one fails. (any and at_least already cancel once decided.)

Example
- id: preflight
fail_fast: true
parallel:
- id: disk_space
- id: replication_lag

Type object

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.

Example
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 }}.

Type expression → list Required

The list to iterate. A run whose list is longer than max_items fails the step.

Example
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 }}.

Type name Default item

The item variable’s name. It can’t shadow inputs, vars, fields, steps, outputs, index or iteration (spec.alias_collision).

Example
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 }}.

Type expression → string

A stable key per item, shown instead of the index. Keys must be unique.

Example
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: restart

Type positive integer Default 1

How many items run at once.

Example
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: patch

Type positive integer Required

The most items the step accepts, at most 100. It bounds the run’s worst-case size, which runbook spec validate reports.

Example
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: patch

Type list of steps Required

The steps run for each item.

Example
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: undrain

Type object

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.

Example
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 }

Type expression → boolean

Stop once this is true. A loop takes until or while, not both (spec.invalid_shape).

Example
metadata: { id: wait-healthy }
spec:
steps:
- id: poll
loop:
until: "${{ steps.probe.verdict == 'pass' }}"
max_iterations: 10
steps:
- id: probe
check: true

Type expression → boolean

Keep going while this is true.

Example
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 }

Type positive integer Required

The most iterations, at most 50. A loop that reaches it without its condition is exhausted.

Example
metadata: { id: retry-until-green }
spec:
steps:
- id: attempts
loop:
until: "${{ steps.ci.verdict == 'pass' }}"
max_iterations: 5
steps:
- id: ci
check: true

Type duration

How long to wait between iterations.

Example
metadata: { id: wait-healthy }
spec:
steps:
- id: poll
loop:
until: "${{ steps.probe.verdict == 'pass' }}"
max_iterations: 12
delay: 5m
steps:
- id: probe
check: true

Type list of steps Required

The steps of one iteration.

Example
metadata: { id: wait-healthy }
spec:
steps:
- id: poll
loop:
until: "${{ steps.probe.verdict == 'pass' }}"
max_iterations: 3
steps:
- id: probe
check: true

Type object

Runs the steps of the first case whose when is true, or the default steps when none is.

Example
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_ticket

Type list Required

The cases, tested in order.

Example
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 }]

Type expression → boolean Required

The case’s condition.

Example
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 }]

Type list of steps Required

The steps the case runs.

Example
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_back

Type object

The steps to run when no case matches. Without it, nothing runs.

Example
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 }]

Type list of steps Required

The default steps.

Example
metadata: { id: route }
spec:
inputs:
ok: { type: boolean, required: true }
steps:
- id: route
switch:
cases:
- when: "${{ inputs.ok }}"
steps: [{ id: celebrate }]
default:
steps:
- id: investigate

Type object

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).

Example
- id: soak
wait: { for: 30m }

Type duration

Wait this long, at most 7 days (spec.limit_exceeded).

Example
- id: soak
wait: { for: 2h }

Type RFC 3339 time

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).

Example
- id: wait_for_window
wait: { until: "2026-12-01T09:00:00Z" }

Type name

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.

Example
- id: connect_store
wait: { signal: store_connected, timeout: 14d }

Type duration

The most the wait may take; past it the step times out.

Example
- id: customer_reply
wait: { signal: customer_replied, timeout: 3d }

Type map of declarations

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).

Example
- id: connect_store
wait:
signal: store_connected
outputs:
store_id: { type: string, required: true }

Type object

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.

Example
- id: go_no_go
approval:
prompt: Ship to every region?
options: [ship, hold]
approvers: { teams: [release-managers] }

Type string or template Required

The question the approvers answer.

Example
- id: go_no_go
approval:
prompt: Canaries look clean. Continue the rollout?
options: [continue, roll_back]
approvers: { teams: [oncall] }

Type list Required

The choices: strings, or objects with id, title and auto. IDs are unique and non-empty.

Example
- id: go_no_go
approval:
prompt: Continue?
options:
- { id: continue, title: Continue the rollout }
- { id: roll_back, title: Roll back now }
approvers: { teams: [oncall] }

Type string Required

The option’s ID, the value of outputs.decision.

Example
- id: go_no_go
approval:
prompt: Continue?
options: [{ id: continue }, { id: stop }]
approvers: { users: [dana] }

Type string

The option’s label. Defaults to its ID.

Example
- id: go_no_go
approval:
prompt: Continue?
options: [{ id: continue, title: "Yes, continue" }, { id: stop, title: Stop here }]
approvers: { users: [dana] }

Type boolean Default false

Marks the option an automatic decision (on_timeout: { decide: … }) may choose (spec.auto_option_required).

Example
- 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 }

Type object

Who may decide: users and teams. Publishing requires approvers (spec.approvers_required); they resolve against your directory.

Example
- id: go_no_go
approval:
prompt: Ship it?
options: [ship, hold]
approvers: { users: [dana], teams: [release-managers] }

Type list of user names

People who may decide.

Example
- id: sign_off
approval:
prompt: Sign off on the migration?
options: [approve, reject]
approvers: { users: [dana, lee] }

Type list of team slugs

Teams whose members may decide.

Example
- id: sign_off
approval:
prompt: Sign off on the migration?
options: [approve, reject]
approvers: { teams: [dba] }

Type positive integer Default 1

How many approvers must choose the same option.

Example
- id: two_person_rule
approval:
prompt: Delete the production bucket?
options: [delete, keep]
approvers: { teams: [security] }
min: 2

Type duration

How long the approval waits before on_timeout applies.

Example
- id: go_no_go
approval:
prompt: Ship it?
options: [ship, hold]
approvers: { teams: [oncall] }
timeout: 1h
escalate_to: [team:eng-leads]

Type escalate | object Default escalate

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).

Example
- id: go_no_go
approval:
prompt: Ship it?
options: [ship, hold]
approvers: { teams: [oncall] }
timeout: 2h
on_timeout: escalate
escalate_to: [team:eng-leads]

Type option ID

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.

Example
- 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 }

Type list of recipients

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).

Example
- id: go_no_go
approval:
prompt: Ship it?
options: [ship, hold]
approvers: { teams: [oncall] }
timeout: 30m
escalate_to: [team:eng-leads]

Type duration Default the approval’s timeout

How long the escalated approval waits before it expires.

Example
- id: go_no_go
approval:
prompt: Ship it?
options: [ship, hold]
approvers: { teams: [oncall] }
timeout: 30m
escalate_to: [team:eng-leads]
escalation_timeout: 2h

Type pause | fail Default pause

What an approval that expires undecided does: pause the run for a person to pick up, or fail the step.

Example
- id: go_no_go
approval:
prompt: Ship it?
options: [ship, hold]
approvers: { teams: [oncall] }
timeout: 30m
escalate_to: [team:eng-leads]
on_expired: fail

Type boolean Default false

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.

Example
- id: triage_choice
approval:
prompt: Which runbook fits this alert?
options: [restart, scale_up, escalate]
approvers: { teams: [oncall] }
allow_agents: true

Type object

Sets variables and fields. Values may be expressions.

Example
metadata: { id: classify }
spec:
fields:
severity: { type: string }
vars:
result: unknown
steps:
- id: record
set:
fields: { severity: major }
vars: { result: degraded }

Type map of values

New values for variables declared in spec.vars.

Example
metadata: { id: tally }
spec:
vars: { outcome: pending }
steps:
- id: done
set: { vars: { outcome: done } }

Type map of values

New values for fields declared in spec.fields; each must match its declaration.

Example
metadata: { id: incident }
spec:
fields:
severity: { type: enum, options: [sev1, sev2, sev3] }
steps:
- id: escalate
set: { fields: { severity: sev1 } }

Type object

Ends the run early with a status. Not allowed in finally (spec.end_in_finally).

Example
- id: nothing_to_do
end: { status: succeeded, message: No certificates expire this month. }

Type succeeded | failed | cancelled Required

The run’s final status.

Example
- id: stop
end: { status: cancelled }

Type string or template

Why the run ended, shown on the run page.

Example
- id: stop
end: { status: failed, message: The preflight found replication lag. }

Type object

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.

Example
- id: verify
call:
runbook: post-deploy-checks
with: { service: api }

Type runbook ID Required

The child runbook’s ID (its kebab-case slug). It resolves when you publish (spec.call_unresolved).

Example
- id: verify
call: { runbook: post-deploy-checks }

Type positive integer

Pins a published version. Without it, the version that’s current when you publish is pinned.

Example
- id: verify
call: { runbook: post-deploy-checks, version: 4 }

Type map of values

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).

Example
- id: verify
call:
runbook: post-deploy-checks
with: { service: api, environment: production }

Type map of declarations

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).

Example
- id: verify
call:
runbook: post-deploy-checks
with: { service: api }
outputs:
error_rate: { type: number }