A deployment checklist you can reuse
Most failed releases fail for ordinary reasons: a missing environment variable, a migration that locks a table, a cache that serves old files. A short checklist catches those before users do. Copy the lists below and trim them to fit your project.
Why a checklist and not memory
Deploys happen often enough to feel routine and rarely enough to forget a step. Under time pressure people skip the dull checks first, and those are exactly the ones that matter. Writing the steps down also lets someone new deploy safely, and the list improves each time a release goes wrong and you add the missing item.
Before you deploy
- All automated tests pass on the exact commit you will ship, not on a neighbour.
- The change has been reviewed, and you know what it touches.
- New environment variables and secrets exist in the target environment, with real values.
- Database migrations have been run against a copy of production-sized data, and you know how long they take.
- Migrations are backward compatible: the old code still runs against the new schema while the rollout is in progress.
- A recent backup exists, and someone has tested a restore from it.
- Feature flags for unfinished work are switched off.
- The team knows a release is happening, and nobody else is deploying at the same moment.
- You avoid the last hour before a weekend or holiday, when fewer people are around to help.
During the deploy
- Record the version or commit you are replacing, so you can return to it.
- Run migrations in the order your plan says; additive schema changes usually go first.
- Deploy the code. Where possible, roll it out to a small share of servers or users before everyone.
- Watch error rates and logs while the rollout runs, not only afterwards.
- Purge or version caches for changed static files so browsers do not mix old scripts with new pages.
Right after: smoke tests
A smoke test is a short, shallow check that the most important paths work at all. It takes minutes and proves the release is alive before you announce it.
- The home page loads with status 200. A quick check from a terminal:
curl -sI example.com. - Sign-in works, if the product has accounts.
- The single most valuable action works end to end, such as a search, a form submission or a checkout in test mode.
- Pages that changed in this release look right on a phone and on a desktop.
- Error tracking shows no new kinds of errors.
- Scheduled jobs and background workers picked up the new code.
The rollback plan
Decide before deploying what will make you roll back and how. A good plan answers three questions:
| Question | Example answer |
|---|---|
| What triggers a rollback? | Error rate clearly above normal, or the main action failing |
| Who decides? | The person running the deploy, without needing a meeting |
| What is the command? | Redeploy the previous build, or flip the feature flag off |
Code is easy to roll back; data is not. If a migration deleted or reshaped data, going back may need a restore. That is why destructive schema steps, such as dropping a column, belong in a later release, after the code that stopped using them has been live for a while.
After the dust settles
- Keep an eye on metrics for the next few hours; some problems appear only under real traffic.
- Update the changelog and tell support staff what changed.
- If anything went wrong, write a short blameless note: what happened, why, and which checklist item would have caught it.
Questions
Is a checklist still needed with full CI/CD?
Yes, but it shrinks. Automate every item you can, and keep the human ones: timing, communication and the rollback decision.
How long should a smoke test take?
Short enough that nobody is tempted to skip it. A few minutes is typical.