deploy-pipeline-runbook · diff
git:20260512.ac6f87e to git:20260515.c726437
74 added, 38 removed. Audit A to A.
---
name: deploy-pipeline-runbook
description: Coordinate multi-system deployment steps as a review-first runbook with explicit approval before any external write or promotion action.
---
# Deploy Pipeline Runbook
- This is an experimental, trust-sensitive runbook.
+ This is a trust-sensitive runbook for multi-system deployments. Every write or promotion action requires explicit human approval.
## When to Use
-
- - A release spans multiple systems or vendors
- - Order matters across billing, database, application, and notification steps
- - Rollback needs to be planned before execution starts
+ - A release spans multiple systems or vendors (billing, database, app, notifications).
+ - Order of operations matters and rollback must be planned before execution starts.
+ - A failed step in one system could corrupt state in a downstream system.
## Core Rules
-
- - Treat this as a runbook, not default automation
- - Inspect current state before each external step
- - Dry-run whenever the target system supports it
- - Summarize side effects before approval
- - Require explicit approval before any write, promotion, or announcement action
- - Define rollback before the first irreversible step
+ - Inspect current state before each external step.
+ - Dry-run whenever the target system supports it.
+ - Show side effects before asking for approval — never surprise.
+ - Require explicit approval before every write, promotion, or announcement.
+ - Define the rollback path before the first irreversible step.
## Runbook Structure
- 1. **Preparation**
- - identify systems touched
- - identify exact intended change per system
- - confirm credentials and access paths
+ ### 1. Preparation
+ - List every system touched.
+ - State the exact intended change per system (e.g., "bump subscription plan from X to Y in billing API").
+ - Confirm credentials, access paths, and required permissions.
+ - Identify which steps are reversible and which are not.
- 2. **Sequence the rollout**
- - config or billing prerequisites
- - schema or migration steps
- - deploy or promotion step
- - smoke checks
- - stakeholder notifications
+ ### 2. Sequence the rollout
+ 1. Config or billing prerequisites.
+ 2. Schema migrations or data backfills.
+ 3. Application deploy or feature promotion.
+ 4. Smoke checks and health validation.
+ 5. Stakeholder notifications.
- 3. **Approval checkpoint**
- - show the exact next write action
- - show expected side effects
- - show rollback path
+ ### 3. Approval checkpoint (required before every write)
- 4. **Execute one step at a time**
- - verify after each step
- - stop on the first unexpected state transition
+ Use this exact format:
- 5. **Closeout**
- - record what changed
- - record follow-up checks
- - record rollback status
+ ```
+ NEXT ACTION: [exact command or API call]
+ SYSTEM: [target system / environment]
+ SIDE EFFECTS: [what changes, what is created, what is sent]
+ IRREVERSIBLE: yes/no — [why]
+ ROLLBACK: [exact steps to undo this if it fails]
+ Approve? (yes to proceed)
+ ```
+
+ ### 4. Execute one step at a time
+ - Run the approved action.
+ - Verify the outcome before moving to the next step.
+ - Stop immediately on any unexpected state or error.
+
+ ### 5. Closeout
+ ```
+ COMPLETED: [timestamp]
+ CHANGES MADE: [summary of what changed per system]
+ FOLLOW-UP CHECKS: [monitoring, alerts, or manual verifications needed]
+ ROLLBACK STATUS: available / partially available / consumed
+ ```
+
+ ## Rollback Plan Template
+
+ Define this before step 1 of execution:
+
+ ```
+ IF [step N] fails:
+ 1. [immediate containment action]
+ 2. [system-specific undo command or API call]
+ 3. [verification that rollback succeeded]
+ 4. [notification to stakeholders]
+ ```
+
+ ## Safety Constraints
+ - Do not proceed past an approval checkpoint without an explicit affirmative response from the user.
+ - Do not infer approval from silence, partial answers, or "looks good" statements — require a clear "yes".
+ - Do not skip the dry-run step for systems that support it.
+ - Do not perform rollback steps that were not defined in the pre-execution rollback plan.
+ - Do not make assumptions about current system state — inspect it before each step.
+
+ ## Validation / Done Criteria
+ - Rollback plan was defined and documented before the first irreversible step.
+ - Every approval checkpoint was acknowledged with an explicit user affirmative.
+ - Closeout block was produced: timestamp, per-system changes, follow-up checks, rollback status.
+ - No step was executed without a prior outcome verification of the previous step.
+
## Typical Systems
- - billing platforms
- - databases
- - deploy targets
- - messaging or incident channels
+ - Billing platforms (plan changes, entitlements)
+ - Databases (migrations, backfills)
+ - Application deploy targets (containers, serverless, CDN)
+ - Messaging or incident channels (Slack, PagerDuty, email)
- The specific vendors are optional. The safety model is not.
+ The specific vendor does not change the safety model.