Approvals and destructive steps
An approval asks named approvers to choose between options. Later steps
read the choice as steps.<id>.outputs.decision, with the approver’s
comment and who decided_by.
metadata: { id: ship-or-hold, owners: [team:release-managers] }spec: inputs: version: { type: string, required: true } steps: - id: go_no_go approval: prompt: Ship ${{ inputs.version }} to every region? options: - { id: ship, title: Ship it } - { id: hold, title: Hold the release } approvers: { teams: [release-managers] } timeout: 2h escalate_to: [team:eng-leads] - id: rollout if: "${{ steps.go_no_go.outputs.decision == 'ship' }}" actor: agent destructive: true instructions: Roll out ${{ inputs.version }} everywhere.Who decides
Section titled “Who decides”approversnamesusersandteams; they resolve when you publish, and publishing requires at least one (spec.approvers_required).min(default 1) is how many approvers must choose the same option. Each person votes once.- People decide in the web app, from their inbox, from Slack or with the CLI:
runbook me tasks --kind approval # what's waiting on merunbook step decide "$SR" --option ship --comment "Canaries are clean"Timeouts and escalation
Section titled “Timeouts and escalation”- Requestedapproval.requested to the approvers
- EscalatedAt timeout: to escalate_to (or the owners)
- ExpiredAt escalation_timeout, undecided
- Paused or failedBy on_expired
timeoutstarts the clock. At it,on_timeout: escalate(the default) hands the approval toescalate_to, or to the runbook’sowners; the original approvers can still decide.escalation_timeout(default: the same astimeout) is how long the escalated approval waits. Undecided by then, it expires, andon_expiredeither pauses the run for a person (pause, the default) or fails the step (fail).on_timeout: { decide: <option> }instead decides automatically at the timeout. The option must be markedauto: true.
Agents and approvals
Section titled “Agents and approvals”Approvals aren’t in an agent’s work brief. allow_agents: true lets an
agent decide one; it requires min: 1, and an agent’s decision is recorded
apart from human signatures. Agents never cast human approvals, whatever
token they hold.
Destructive steps
Section titled “Destructive steps”destructive: true marks a step that changes something you can’t easily
undo: a rollback, a deletion, a failover. The publication rules keep a
destructive step out of reach of decisions no person made:
| A decision made by | May lead to a destructive step? |
|---|---|
| A person | Yes |
An agent (allow_agents) |
Never (spec.agent_approval_destructive) |
A timeout (on_timeout: decide) |
Only if the step sets allow_auto_decision: true (spec.auto_decision_destructive) |
metadata: { id: auto-rollback }spec: steps: - id: keep_or_roll_back approval: prompt: The error rate doubled after the deploy. Roll back? options: [keep, { id: roll_back, auto: true }] approvers: { teams: [oncall] } timeout: 15m on_timeout: { decide: roll_back } - id: roll_back if: "${{ steps.keep_or_roll_back.outputs.decision == 'roll_back' }}" actor: agent destructive: true allow_auto_decision: true instructions: Roll back to the previous release.