Pre-Deployment Checklist

Verify that a release is safe to deploy by systematically checking CI status, migrations, feature flags, rollback readiness, and monitoring. Catch issues before they reach production.

Workflow

Step 1: Identify What Is Being Deployed

Gather deployment details:

# What commits are going out?
git log --oneline <last-deployed-tag>..HEAD

# What files changed?
git diff --stat <last-deployed-tag>..HEAD

# Any migration files?
git diff --name-only <last-deployed-tag>..HEAD | grep -i migrat

# Any config or infra changes?
git diff --name-only <last-deployed-tag>..HEAD | grep -E '(\.env|docker|terraform|k8s|helm|config)'

Classify the deployment risk:

• Low risk: UI changes, copy updates, non-critical bug fixes.
• Medium risk: New features behind feature flags, minor API changes.
• High risk: Database migrations, auth changes, payment flow changes, infrastructure changes.
• Critical risk: Breaking API changes, data migrations, security patches.

Step 2: Run the Pre-Deploy Checklist

Work through each section. Mark items as checked, N/A, or blocked.

CI/CD Pipeline

• All CI checks are green on the deploy branch.
• Build artifacts are generated and available.
• No flaky test failures have been skipped or ignored.
• Linting and type checking pass.

Code Review

• All changes have been reviewed and approved.
• No open review comments marked as "must fix."
• Security-sensitive changes have had security review.

Database Migrations

• Migrations are backward-compatible (can roll back without data loss).
• Migrations have been tested against a copy of production data.
• Large table migrations have a plan for zero-downtime execution.
• Rollback migration exists and has been tested.
• No migration locks that could block reads/writes for extended periods.

Feature Flags

• New features are behind feature flags where appropriate.
• Feature flag default values are set correctly (off for gradual rollout).
• Kill switches exist for risky features.
• Flag naming follows team conventions.

API Changes

• API changes are backward-compatible or versioned.
• API documentation is updated.
• Downstream consumers have been notified of breaking changes.
• Deprecation warnings are in place for removed endpoints.

Configuration

• Environment variables are set in the target environment.
• Secrets are stored in the secrets manager, not in code.
• Config differences between staging and production are documented.
• Third-party service credentials are valid and not expired.

Monitoring and Alerting

• Key metrics dashboards are accessible and bookmarked.
• Alerts are configured for error rate, latency, and throughput.
• Log aggregation is set up for the new changes.
• Health check endpoints are functioning.

Rollback Plan

• Rollback procedure is documented and tested.
• Rollback can be executed in under 5 minutes.
• Rollback triggers are defined (error rate > X%, latency > Y ms).
• Data rollback strategy exists if migrations are involved.
• On-call engineer is aware of the deployment.

Communication

• Deployment is announced in the team channel.
• Affected stakeholders are notified (support, product, customers if needed).
• Deployment window avoids peak traffic and freeze periods.
• On-call handoff is clear if deploying near shift change.

Step 3: Generate the Deployment Record

Document what is being deployed, who is deploying, and the rollback plan.

Step 4: Post-Deploy Verification

After deployment, verify:

• Health checks pass on all instances.
• Key user flows work end-to-end (smoke test).
• Error rates are at or below pre-deploy baseline.
• No unexpected log entries or warnings.
• Database migrations completed successfully.
• Feature flags are in expected state.

Output Format

## Deployment Checklist: <Service Name>

**Date**: YYYY-MM-DD HH:MM TZ
**Deployer**: <name>
**Environment**: <staging | production>
**Risk Level**: Low | Medium | High | Critical
**Commits**: <count> commits (<first-sha>..<last-sha>)

### Changes Summary
- <one-line summary of each significant change>

### Checklist

| Category           | Status | Notes               |
|--------------------|--------|---------------------|
| CI/CD              | PASS   |                     |
| Code Review        | PASS   |                     |
| Migrations         | N/A    | No migrations       |
| Feature Flags      | PASS   | flag-x defaults off |
| API Changes        | PASS   | backward-compatible |
| Configuration      | PASS   |                     |
| Monitoring         | PASS   | dashboard: <link>   |
| Rollback Plan      | PASS   | see below           |

### Rollback Plan
**Trigger**: Error rate > 1% or p99 latency > 2s for 5 minutes
**Procedure**: `<rollback command or steps>`
**Data rollback**: <strategy if applicable>
**Owner**: <who will execute rollback>

### Post-Deploy Verification
- [ ] Health checks green
- [ ] Smoke test passing
- [ ] Error rate baseline
- [ ] Logs clean

Examples

User: "I'm about to deploy the auth service to production" Action: Check CI status, review recent commits, identify any migrations or config changes, generate a full checklist with rollback plan.

User: "We have a database migration going out, make sure we're ready" Action: Focus on migration safety: backward compatibility, rollback migration, lock duration, data volume assessment. Generate a migration-focused checklist.

User: "Hotfix for the payment bug, need to deploy ASAP" Action: Generate an abbreviated checklist appropriate for a hotfix (CI, review, rollback, monitoring) while flagging any items that should not be skipped even under time pressure.

Best Practices

• Never skip the rollback plan, even for "simple" changes. The cost of having a plan you don't use is near zero. The cost of needing one you don't have is high.
• Deploy during business hours when the team is awake and available. Friday evening deploys are an anti-pattern.
• For high-risk deploys, have a second person available to monitor while you deploy.
• Use progressive rollouts (canary, blue-green, percentage-based) for anything touching critical paths.
• Keep deployments small and frequent. Large batch deploys are harder to debug when something goes wrong.
• Automate as much of the checklist as possible over time. Every manual check is a potential miss.
• Post-deploy verification is not optional. "It deployed successfully" is not the same as "it works correctly."