Design a deployment pipeline

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-deployment-pipeline/raw' -o ~/'.claude/skills/design-deployment-pipeline/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-deployment-pipeline/files/LICENSE.txt' -o ~/'.claude/skills/design-deployment-pipeline/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-deployment-pipeline/raw' -o '.cursor/skills/design-deployment-pipeline/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-deployment-pipeline/files/LICENSE.txt' -o '.cursor/skills/design-deployment-pipeline/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-deployment-pipeline/raw' -o '.agents/skills/design-deployment-pipeline/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-deployment-pipeline/files/LICENSE.txt' -o '.agents/skills/design-deployment-pipeline/LICENSE.txt'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

A good pipeline makes the safe path the easy path. Every change takes the same route, every gate is automatic where it can be, and going back is one click.

When to use

• You are planning CI/CD for a new service or app.
• Deploys cause downtime or broken releases.
• You want staging, then production, with checks in between.
• You are choosing between rolling, blue-green and canary releases.

When not to use

• You only need the CI file for one platform. Use configure-github-actions-ci or set-up-gitlab-ci.
• You are launching a simple static site. Use launch-website-checklist.

Steps

1. Map the stages: commit checks, build, test, deploy to staging, verify, deploy to production, verify.
2. Build the artifact once (a container image, bundle or zip) and tag it with the commit SHA.
3. Promote that same artifact through each environment. Never rebuild for production.
4. Put fast gates first: lint, type-check and unit tests, then integration tests, then dependency and secret scanning.
5. Decide which gates are automatic and which need a human. Keep manual approvals for production only.
6. Choose a rollout strategy from the table below.
7. Make database changes backward-compatible, as described under "Migrations".
8. Define health checks and the metrics that decide success: error rate, latency and key business events.
9. Write the rollback plan: how to redeploy the previous artifact, who can do it, and how long it takes.
10. Notify the team on each production deploy with the version, author and a link to the changes.

Rollout strategies

| Strategy | How it works | Good for | Cost |
| --- | --- | --- | --- |
| Recreate | stop old, start new | dev or internal tools | brief downtime |
| Rolling | replace instances a few at a time | most stateless services | old and new run together |
| Blue-green | start a full new copy, switch traffic | instant switch and rollback | double capacity during deploy |
| Canary | send 1-10% of traffic to new, watch, then widen | risky changes at scale | needs good metrics |
| Feature flag | ship code dark, turn on per user | separating deploy from release | flag clean-up work |

Migrations

Use expand and contract so old and new code both work during a deploy:

1. Expand: add the new column or table. Do not remove or rename anything yet.
2. Deploy code that writes both, then backfill old rows.
3. Deploy code that reads only the new shape.
4. Contract: drop the old column in a later release.

Gotchas

• Rebuilding per environment means production runs something you never tested.
• A rollback cannot undo a destructive migration. Back up the database before any drop.
• Health checks that only test "the process is up" miss broken features. Add one real request.
• Keep secrets and tokens in the platform's secret store, scoped per environment, never in the pipeline file.
• Long approval queues tempt people to bypass the pipeline. Keep gates fast.

Portability

Works with any CI tool, such as GitHub Actions, GitLab CI, CircleCI, Jenkins or Buildkite, and with any host: Kubernetes, ECS, Cloud Run, Fly.io, Vercel or Cloudflare. If you use a managed platform, its preview and instant-rollback features are the equivalent of blue-green.

Example prompt

"Design a deployment pipeline for our API: GitHub Actions, Docker on Cloud Run, a Postgres database. We want staging, a manual production approval, canary releases and one-click rollback."

Done when

• Each stage, gate and approval is written down, with who owns it.
• One artifact is built per commit and promoted unchanged.
• The rollout strategy, success metrics and rollback steps are agreed and tested once.
• Migrations follow expand and contract.

---

Adapted from "deployment-pipeline-design" in wshobson/agents (MIT, Copyright (c) 2024 Seth Hobson). See LICENSE.txt.

Bundled files

• LICENSE.txt

Licence

Adapted from Seth Hobson (wshobson/agents, deployment-pipeline-design) (Copyright (c) 2024 Seth Hobson), MIT License. Adapted by TheSkillVault on 2026-11-02: rewritten as a tool-neutral design checklist with an original strategy table, an expand-and-contract migration section and a rollback plan; vendor-specific Argo, Azure and GitHub YAML samples were dropped. Not the original file.

Licence: MIT License. Attribution when you reuse it: Based on work by Seth Hobson (wshobson/agents, deployment-pipeline-design) (Copyright (c) 2024 Seth Hobson, MIT License), https://github.com/wshobson/agents/tree/7e2fb559cf4b824b27f1fec49fe88f7511066d26/plugins/cicd-automation/skills/deployment-pipeline-design; adapted by TheSkillVault, https://theskillvault.ai