Deployment Automation

Deployment Automation

Use this skill when the job is safe release execution after the system is already buildable.

deployment-automation is the repo's release-execution anchor for:

• preview releases and shareable review environments
• staging → production promotion and sign-off gates
• rollout strategy choice: replace, rolling, blue-green, canary, progressive
• post-deploy verification and stop conditions
• rollback response and bad-release containment
• release-hardening packets around an existing deploy path

Read these support docs before deciding the packet:

• references/deployment-modes-and-boundaries.md
• references/release-packet-templates.md
• references/strategy-selection-and-stop-conditions.md
• references/rollout-and-rollback-checklist.md
• references/platform-routing-notes.md

When to use this skill

• A preview or branch deployment exists, but nobody agrees what it is supposed to prove before merge.
• A release already works mechanically, but staging/prod promotion still depends on tribal knowledge.
• The main decision is rollout strategy, release gates, verification depth, or rollback readiness.
• A deploy failed and the next job is containment, rollback, and safe recovery rather than broad platform redesign.
• The team needs a vendor-neutral release packet before using a platform-specific operator skill.
• You need to tighten an existing deploy path with preflight checks, sign-off logic, and explicit stop conditions.

When not to use this skill

• The main job is writing or refactoring GitHub Actions / GitLab / Jenkins / Buildkite workflows → workflow-automation
• The main job is installing Docker, kubectl, cloud CLIs, auth bootstrap, or making the machine runnable → system-environment-setup
• The main job is dashboards, alerts, traces, or long-lived telemetry architecture → monitoring-observability
• The main job is Vercel-specific linking, domains, aliases, environment variables, or claim URLs → vercel-deploy
• The system cannot build, package, or run tests yet → fix build/setup problems before reopening deployment automation
• The main job is secret rotation, IAM policy, signing, or compliance architecture → route to the relevant security skill

Instructions

Step 1: Freeze the release profile

Normalize the request before suggesting steps.

release_profile:
  mode: preview-release | environment-promotion | container-paas-rollout | kubernetes-rollout | rollback-response | release-hardening
  runtime_shape: static-frontend | web-app | api-service | worker-job | multi-service | unknown
  artifact_shape: platform-build | image | build-output | package | unknown
  target_environment: preview | staging | production | mixed | unknown
  promotion_model: same-artifact-promotion | rebuild-per-env | direct-deploy | unknown
  rollout_strategy: replace | rolling | blue-green | canary | progressive | feature-flag-assisted | unknown
  stateful_risk: low | medium | high | unknown
  verification_depth: health-only | smoke-tests | release-checklist | automated-analysis | unknown

Pick exactly one primary mode per run:

• preview-release — shareable verification before merge or promotion
• environment-promotion — staging → production or multi-env promotion with gates
• container-paas-rollout — managed app/container platform release planning
• kubernetes-rollout — rollout controller behavior, stop conditions, and rollback path
• rollback-response — bad deploy containment and recovery
• release-hardening — add missing preflight, approvals, or verification around an existing flow

Step 2: Gather the smallest truthful evidence set

Do not invent a release flow from vibes. Capture the minimum real facts: 1. What artifact is actually being shipped? 2. Which environment is in scope right now? 3. Is the same artifact promoted across environments, or rebuilt per environment? 4. What is the current deploy command, provider action, or controller? 5. What health checks, smoke checks, or sign-off signals already exist? 6. What is the real rollback method? 7. Are there schema/data changes that make rollback asymmetric?

If any answer is unknown, state it explicitly and default to the smallest safe interpretation.

Step 3: Enforce boundaries early

Use these route-outs before generating a packet:

Step 4: Load the right support packet instead of expanding the front door

After classification, use the matching reference packet:

• preview-release → references/release-packet-templates.md#preview-release-packet
• environment-promotion → references/release-packet-templates.md#environment-promotion-packet
• container-paas-rollout → references/release-packet-templates.md#containerpaas-rollout-packet
• kubernetes-rollout → references/release-packet-templates.md#kubernetes-rollout-packet
• rollback-response → references/release-packet-templates.md#rollback-response-packet
• release-hardening → references/release-packet-templates.md#release-hardening-packet

Use references/strategy-selection-and-stop-conditions.md when choosing between replace / rolling / blue-green / canary / progressive paths. Use references/rollout-and-rollback-checklist.md as the minimum release-safety checklist before finalizing.

Step 5: Apply release-execution rules

• Separate build from release. A passing build does not prove the release is safe.
• Separate deploy from exposure. Traffic shifts, promotion gates, and feature flags may matter more than the initial deploy command.
• Separate app rollback from data rollback. Never imply they are the same.
• Prefer the smallest rollout strategy that matches the team’s verification maturity.
• Prefer same-artifact promotion when reproducibility matters. If the system rebuilds per env, call out the risk explicitly.
• Verification is mandatory. Health + one core flow is the minimum acceptable finish line.
• Stop conditions beat optimism. Name what should halt promotion or trigger rollback.

Step 6: Produce a release packet, not a DevOps lecture

Your output should always include:

# Release Packet
- Mode:
- Runtime / provider:
- Artifact:
- Environment(s):
- Promotion model:
- Rollout strategy:

## Preconditions
- Existing deploy path:
- Required auth/config:
- Known blockers / migrations:

## Steps
1. ...
2. ...
3. ...

## Verification
- Health checks:
- Smoke checks:
- Human/automatic sign-off:
- Stop conditions:

## Rollback / recovery
- Immediate rollback path:
- What rollback does not undo:

## Handoffs
- Adjacent skills or provider-specific follow-up:

Step 7: Prefer hardening over wrapper proliferation

If the request feels like “deployment is messy,” prefer: 1. classify the release mode, 2. name the current source of truth, 3. add preflight / verification / rollback structure, 4. route platform detail to the correct adjacent skill.

Do not respond by inventing another generic deployment wrapper, re-explaining all of Kubernetes, or absorbing CI authoring into this skill.

Output format

Return: 1. chosen release mode, 2. evidence gathered and unknowns, 3. rollout strategy with rationale, 4. verification plan, 5. rollback or recovery plan, 6. route-outs or remaining risks.

Examples

Example 1: Preview deploy confusion

Input: "Every PR gets a preview URL, but reviewers keep approving broken flows. What should the deployment process actually require before merge?"

Output shape: classify as preview-release, define what the preview proves, list smoke checks, and separate preview verification from later staging/prod promotion.

Example 2: Staging to production promotion

Input: "We deploy to staging automatically, but production promotion is still a manual Slack ritual. Give us the safest release packet."

Output shape: classify as environment-promotion, name artifact and gates, require post-promote checks, and specify rollback plus schema caveats.

Example 3: Failed production deploy

Input: "The latest release is timing out in production and it also included a migration. We need the safest rollback plan."

Output shape: classify as rollback-response, contain blast radius, separate app rollback from migration risk, and define post-recovery verification.

Best practices

1. Keep the front door about release decisions, not platform encyclopedias. 2. Name the real artifact, environment, and rollback path before suggesting anything. 3. Prefer short release packets that an operator can run under pressure. 4. Route provider-specific and adjacent concerns out early. 5. Treat verification and stop conditions as required output, not optional polish.

References

• Kubernetes Deployments
• Argo Rollouts
• Vercel Deployments

Deployment Modes and Boundaries

Purpose

Use this note to keep deployment-automation focused on release execution instead of expanding into every adjacent DevOps concern.

Primary modes

1. Preview release

Use when the output is a shareable preview deployment or pre-merge release candidate.

Good fit:

• PR or branch preview deploys
• reviewer checklists for preview URLs
• deciding what a preview proves vs what still requires staging/prod verification

Route out when:

• the real job is provider-specific Vercel setup → vercel-deploy
• the real job is GitHub Actions / pipeline design → workflow-automation

2. Environment promotion

Use when the same release moves through staging → prod or across multiple environments.

Good fit:

• promotion gates and approvals
• artifact-promotion policy
• release checklist and sign-off logic
• post-promote health checks

Route out when:

• the environment/runtime itself is not set up yet → system-environment-setup

3. Container/PaaS rollout

Use when the service already packages into an image/build artifact and the release target is a managed platform.

Good fit:

• release path for Render/Fly/Railway-like platforms
• release checks, rollback notes, provider handoff

Route out when:

• the task is deep provider-specific product usage rather than generic release structure

4. Kubernetes rollout

Use when manifests/controllers/rollout strategy are the main concerns.

Good fit:

• rolling / blue-green / canary rollout planning
• readiness/health stop conditions
• Argo/Helm/Kustomize handoff notes

Route out when:

• the job is cluster bootstrap, CLI install, auth, or infra provisioning
• the job is ongoing monitoring/alerting architecture

5. Rollback response

Use when a release already failed and the job is safe containment and recovery.

Good fit:

• identifying blast radius
• choosing redeploy / switchback / flag-disable path
• separating app rollback from data/schema caveats

Boundary rules

deployment-automation owns

• selecting rollout/promotion mode
• deploy preflight
• immediate post-deploy verification
• rollback path definition
• release packet creation and handoff

deployment-automation does not own

• CI workflow authoring → workflow-automation
• machine/runtime/tool installation → system-environment-setup
• dashboards, alerts, traces, log pipelines → monitoring-observability
• secret rotation / IAM / compliance architecture → security skills
• narrow Vercel operational detail → vercel-deploy

Structural red flags

If the recommendation starts to include any of these, it is drifting out of scope:

• a full GitHub Actions tutorial
• Docker/kubectl/cloud-CLI installation steps
• a full observability stack setup
• secret storage architecture design
• a huge Kubernetes manifest cookbook with no release packet

Useful phrasing

• "This skill assumes the system can already build."
• "The primary job is safe release execution, not CI authoring or machine setup."
• "Verification and rollback are required stages, not optional notes."
• "If the deploy target is specifically Vercel, route provider-specific detail to vercel-deploy."

Platform Routing Notes

Route to workflow-automation

Use workflow-automation when the real task is:

• writing or refactoring GitHub Actions / GitLab / Jenkins / Buildkite files
• deciding task runners or release scripts inside the repo
• building reusable pipeline templates
• local-vs-CI command parity or release-job structure

deployment-automation may consume an existing workflow, but should not become a CI-YAML encyclopedia.

Route to system-environment-setup

Use system-environment-setup when the real task is:

• installing provider CLIs, Docker, kubectl, SDKs, or runtimes
• fixing PATH/auth/bootstrap issues on a machine
• making the local development or release machine runnable

deployment-automation may check whether required tools/auth exist, but should not own setup.

Route to monitoring-observability

Use monitoring-observability when the real task is:

• creating dashboards or alerts
• setting up tracing or log aggregation
• defining long-lived telemetry or SLO monitoring
• incident detection architecture

deployment-automation may require immediate post-deploy health or smoke checks, but should not own the broader telemetry stack.

Route to vercel-deploy

Use vercel-deploy when the task is specifically about:

• deploying directly to Vercel
• Vercel project linking, aliases, domains, environment variables, or claim URLs
• Vercel preview/prod workflow details

deployment-automation should stay vendor-neutral and only route into Vercel-specific operations when that platform is the real center of gravity.

Route to security-specific skills

Use a security skill when the main concern is:

• secret rotation or storage architecture
• IAM scopes and least privilege
• artifact signing / SBOM / attestation
• compliance evidence or audit design

deployment-automation should refuse unsafe handling rather than trying to solve the whole security layer itself.

Release Packet Templates

Use these packet skeletons when deployment-automation has already chosen the right mode.

Preview release packet

# Preview Release Packet

## Target
- Provider/runtime:
- URL/output:
- What reviewers must verify:

## Preconditions
- Build/test status:
- Required config present:
- Known differences from staging/prod:

## Deploy steps
1. ...
2. ...
3. ...

## Verification
- Smoke checks:
- Visual / flow checks:
- Promote or discard decision:

## Route-outs
- Provider-specific follow-up:
- Adjacent skills if needed:

Environment promotion packet

# Environment Promotion Packet

## Artifact and environments
- Artifact:
- Promote from:
- Promote to:
- Promotion model:

## Gates
- Required approvals:
- Freeze/change-window notes:
- Blocking risks:

## Rollout
1. ...
2. ...
3. ...

## Verification
- Before promotion:
- After promotion:
- Stop conditions:

## Rollback
- Immediate rollback path:
- Data/schema caveats:

Container/PaaS rollout packet

# Container/PaaS Rollout Packet

## Runtime
- Image/build source:
- Platform:
- Release command or provider action:

## Release plan
- Direct deploy or staged rollout:
- Verification checks:
- Rollback path:

## Handoffs
- Provider-specific follow-up:
- Adjacent skills if needed:

Kubernetes rollout packet

# Kubernetes Rollout Packet

## Delivery surface
- Manifest source:
- Deployment/controller:
- Strategy:

## Preflight
- Image/tag:
- Namespace/env:
- Migration/secrets assumptions:

## Rollout
- Apply/promote steps:
- Readiness and health checks:
- Stop conditions:

## Rollback
- Previous ReplicaSet/version:
- Traffic/data caveats:

Rollback response packet

# Rollback Response Packet

## Failure signal
- What failed:
- Blast radius:
- Confidence:

## Immediate containment
1. ...
2. ...
3. ...

## Recovery path
- Redeploy previous artifact / switch traffic / disable flag:
- Data/schema caveats:

## Verification after recovery
- Health:
- Smoke:
- Follow-up hardening:

Release hardening packet

# Release Hardening Packet

## Current path
- Existing deploy trigger:
- Current sign-off:
- Current rollback method:

## Missing safety controls
- Preflight gaps:
- Verification gaps:
- Approval / audit gaps:
- Stop-condition gaps:

## Minimal hardening plan
1. ...
2. ...
3. ...

## Follow-up route-outs
- CI authoring:
- Observability:
- Provider-specific operations:

Rollout and Rollback Checklist

Use this checklist when producing a deployment packet.

1. Preflight

• Artifact/build source is named explicitly
• Target environment is named explicitly
• Required auth/config already exists
• Current deploy command or provider action is known
• Blocking migrations/stateful risks are named
• Same-artifact-promotion vs rebuild-per-env is identified

2. Rollout strategy

Choose the smallest safe strategy:

• direct replace
• rolling update
• blue/green
• canary
• progressive delivery
• feature-flag-assisted release

Questions:

• What is the blast radius if this deploy is bad?
• Do we have trustworthy health checks or smoke checks?
• Do we need human approval before production?
• Can we switch traffic back quickly?

3. Verification

Minimum acceptable verification after deploy:

• health endpoint or equivalent availability signal
• one smoke test proving the core user flow still works
• provider/runtime release status check
• explicit note on who signs off or what auto-stops promotion

Optional higher-confidence verification:

• synthetic checks
• release KPI checks
• canary analysis
• queue/worker health checks
• manual business-critical path review

4. Rollback

Always name the real rollback method:

• redeploy previous artifact/image
• provider rollback / previous release restore
• traffic switchback
• feature-flag disable
• manual recovery runbook

Always name what rollback does not solve automatically:

• schema/data compatibility
• irreversible migrations
• emitted events/side effects
• cache invalidation or stale clients

5. Output requirements

A good deployment packet should always include:

• rollout mode
• environment and artifact
• preconditions
• steps
• verification
• rollback
• handoffs / remaining risks

Strategy Selection and Stop Conditions

Use this note when the release mode is clear but the rollout strategy is not.

Strategy chooser

Decision rules

1. Prefer the smallest strategy that matches the blast radius. 2. Do not prescribe canary or progressive delivery if telemetry and rollback are weak. 3. If the system rebuilds per environment, call out the reproducibility risk before recommending promotion. 4. If data/schema changes are irreversible, state that app rollback alone is incomplete. 5. If preview environments are the only evidence source, do not pretend they replace staging or production verification.

Stop-condition prompts

• What exact signal should halt the rollout?
• Who can approve expansion or production promotion?
• How long should the observation window last?
• What must remain stable: availability, latency, queue depth, business KPI, or manual reviewer sign-off?
• What action happens automatically if the signal fails?

Route-out reminders

• Need dashboards/alerts or SLO design? → monitoring-observability
• Need workflow YAML or release job authoring? → workflow-automation
• Need provider-specific Vercel behavior? → vercel-deploy
• Need machine/bootstrap work before rollout? → system-environment-setup