Write a CI/CD pipeline playbook for a service or team. Use when asked to document a CI/CD pipeline, write a deployment process, define release gates, document build and test stages, or create a deployment guide. Produces a structured playbook covering pipeline stages, environment definitions, deployment gates, rollback procedures, and on-call responsibilities.
SKILL.md
CI/CD Playbook Skill
Produce a complete, actionable CI/CD playbook for a service or team — covering everything a new engineer needs to understand, contribute to, and operate the pipeline safely.
A good playbook is not a diagram. It is a document that answers: what runs, when, why, who owns it, and what to do when it breaks.
[2–3 sentences describing what this service does and why the CI/CD pipeline is structured the way it is. Include the deployment target and how frequently the team ships.]
Deployment frequency: [Multiple times per day / Daily / Weekly / On-demand]
[X minutes]
[X minutes]
What runs: [Build command] + [Linter — e.g. ESLint, golangci-lint, flake8]
Trigger: Every commit to any branch
Blocking: Yes — PR cannot be merged if this fails
Typical duration: [X minutes]
Owner if it fails: PR author
Common failure causes:
[e.g. Missing dependency — run npm install locally before pushing]
[e.g. Lint rule violation — run npm run lint --fix to auto-fix most issues]
Stage 2 — Unit Tests
What runs: [Test command — e.g. npm test, go test ./..., pytest]
Coverage gate: [X]% minimum — pipeline fails below this threshold
Trigger: Every commit
Blocking: Yes
Typical duration: [X minutes]
Coverage report: [Where to find it — e.g. uploaded to Codecov, available in CI artifacts]
Stage 3 — Integration Tests
What runs: [Test suite description — e.g. "API integration tests against a test database using Docker Compose"]
Environment: [Ephemeral test environment / shared test DB / etc.]
Trigger: Every commit to main and feature branches targeting mainBlocking: Yes
Typical duration: [X minutes]
If slow: [e.g. "Integration tests can be skipped locally with SKIP_INTEGRATION=true — never skip in CI"]
Stage 4 — Security Scan
Tools: [e.g. Snyk, Trivy, OWASP Dependency Check, Semgrep]
What it checks: [Dependency vulnerabilities / SAST / secrets detection — list what applies]
Blocking on: Critical and High severity findings
Non-blocking on: Medium and Low (flagged, not blocking)
Trigger: Every commit to main
How to handle a flagged vulnerability:
Check if a fix is available — upgrade the dependency
If no fix available, open a security ticket and add a suppression with justification
Never suppress without a ticket and owner
Stage 5 — Build Artefact
What is produced: [Docker image / binary / zip — be specific]
Registry: [ECR / GCR / Docker Hub / Artifactory — URL]
Tagging convention:[service-name]:[git-sha] (also tagged :latest on main)
Trigger: Commits to main only (not feature branches)
Stage 6 — Deploy to Staging
Deployment method: [e.g. Helm upgrade / kubectl apply / ecs deploy / Terraform apply]
Staging URL: [URL]
Trigger: Automatic on successful artefact build from mainWho can deploy to staging: Any engineer (automatic)
Environment variables: Managed in [Vault / AWS SSM / GitHub Secrets / etc.]
Staging is not production: [Any differences in config, scale, or data — state them here]
Stage 7 — Smoke Tests (Staging)
What runs: [Description — e.g. "10 critical path tests covering login, core API endpoints, and payment flow"]
Tool: [e.g. Playwright / Postman / custom script]
Pass criteria: All smoke tests pass within [X seconds] timeout
Blocking: Yes — production deploy will not proceed if smoke tests fail
Smoke test suite location: [Link to test files or folder]
Stage 8 — Manual Approval Gate
Required for: [Production deploys / deploys affecting >X% of traffic / deploys to specific regions]
Who can approve: [e.g. Any engineer on the team / Lead engineer / On-call engineer]
Approval timeout: [e.g. 24 hours — auto-cancelled if no approval]
How to approve: [GitHub Actions approve step / Slack command / other — with link]
When to withhold approval:
Active incident in production
Deploy is outside the deployment window (see below)
On-call engineer has not been notified
Stage 9 — Deploy to Production
Deployment method: [Same as staging or different — specify]
Deployment window: [e.g. Monday–Thursday 09:00–16:00 UTC — no deploys on Fridays or before bank holidays]
Canary / progressive rollout: [Yes — X% initial traffic, full rollout after Y minutes / No — full deploy]
Deployment notifications: [Slack channel — #deployments]
Who is on-call during deploy: Deploying engineer is responsible until post-deploy checks pass.
Stage 10 — Post-Deploy Checks
Automated checks (run for [X minutes] after deploy):
Error rate: <[X]% (baseline: [Y]%)
P99 latency: <[X]ms (baseline: [Y]ms)
[Key business metric]: within [X]% of baseline
Where to watch: [Datadog / Grafana / CloudWatch dashboard — link]
Hotfix process: [Describe when and how to use a hotfix branch — what level of incident justifies bypassing the standard process]
Rollback Procedure
Automated rollback: [Yes — triggered if post-deploy error rate exceeds [X]% / No — manual only]
Manual rollback steps:
# 1. Identify the last known good image tag
[command to list recent deployments]
# 2. Deploy the previous version
[deployment command with previous tag]
# 3. Confirm rollback is live
[smoke test command or health check URL]
# 4. Notify the team
[Slack command or template]
Rollback decision authority: Any engineer on-call can initiate a rollback without waiting for approval.
After a rollback:
Create a post-deploy incident report (see [incident-postmortem skill])
Do not re-deploy the same commit without fixing the root cause
Notify [stakeholder / support team] of the rollback and expected fix timeline
Secrets and Configuration Management
Secret store: [Vault / AWS SSM / GitHub Secrets / Doppler — specify]
How to add a new secret:
[Step 1]
[Step 2]
Who has access: [Role or team]
Rotation policy: [How often secrets are rotated and who owns it]
Never do: Commit secrets to source control, even in .env files. The pipeline includes secret scanning (Stage 4) which will flag this.
Common Failures and Fixes
Failure
Likely cause
Fix
Build fails with "module not found"
Dependency not installed
Run [install command] and commit lock file
Integration tests timeout
Test DB not seeded / external service down
Check [service] status; re-run pipeline
Smoke tests fail after staging deploy
Environment variable missing
Check [config location]; compare staging and prod env vars
Production deploy stuck at approval
Approver not notified
Tag @[on-call handle] in #deployments
Post-deploy error rate spike
Bad deploy / upstream dependency
Check [dashboard]; initiate rollback if >5 min
On-Call Responsibilities During Deploy
The deploying engineer is responsible for monitoring post-deploy checks for [X minutes] after a production deploy
If you cannot monitor after deploying, hand off explicitly to another engineer in #deployments
For deploys outside business hours: only hotfixes — always page the on-call engineer before deploying
Anti-Patterns
Do not describe a rollback procedure that has never been tested — a theoretical rollback is not a rollback plan; test it in staging before production
Do not allow deploys on Fridays or before holidays without an explicit on-call engineer who will monitor through the weekend
Do not commit secrets to source control even in non-production branches — secret scanning in the pipeline catches this, but prevention is the standard
Do not skip post-deploy monitoring after a production deploy — the deploying engineer must watch error rates and latency for the specified observation window
Do not suppress a security scan finding without a linked ticket and a named owner — suppressions without accountability accumulate into unmanaged risk
Quality Checks
Every stage has a clear owner when it fails
Rollback procedure is tested — not theoretical
Secrets management section names the actual tool used (not "use secrets management")
Deployment window is specific — not "during business hours"
Post-deploy check thresholds are calibrated to actual baseline metrics
