Deployment Checklist
A practical deployment checklist for small software teams: pre-flight checks, rollout, verification and rollback steps you can trigger from CI.
- Typical schedule per deployment
- The checklist 5 sections, 24 items
- Variables
{{service}}{{version}}{{environment}} - Start from CI
Use this checklist whenever a change goes out to a shared environment that people or customers depend on. That covers production, and also any staging environment that other teams test against. It suits teams that deploy often enough to forget a step, but not so often that every step is fully automated.
Who owns it
The person who presses the deploy button owns the run. They do not have to do every step themselves, but they decide whether the deployment goes ahead, and they stay reachable until the post-deployment checks are done. If a step is assigned to someone else, such as a database reviewer, assign it in the run so the audit trail shows who confirmed it.
Common pitfalls
- No rollback plan until it is needed. Write down the exact rollback command, and check that the previous artifact still exists, before you deploy.
- Migrations that cannot be reversed. Deploy schema changes that are backwards compatible with the running version, and remove old columns in a later release.
- "It's green" without looking. A passing health check only proves the process is up. Check error rates and one real user flow.
- Deploying into a busy period. Avoid deploying just before the end of the day or a weekend, and avoid times when nobody who knows the change is around.
Trigger the run from your pipeline when a release tag is pushed. The checklist then exists before anyone starts, and every deployment leaves a record of who checked what.
The checklist: Deploy {{service}} {{version}} to {{environment}}
Before you deploy
-
Release notes or changelog for
{{version}}are written and linkedInclude ticket links and anything that changes behaviour for users or other services.
-
CI pipeline is green on the exact commit being deployed
-
The change has been reviewed and approved by someone other than the author
-
Database migrations are reviewed and backwards compatible with the running version
New code must work with the old schema and old code with the new schema, so a rollback stays possible.
-
New configuration values and secrets exist in
{{environment}} -
Rollback plan is written down: command, previous version number, and who decides
-
Previous artifact or image is still available for rollback
-
Deployment window agreed and no conflicting deploys or maintenance are scheduled
-
Recent backup or snapshot of the database is confirmed optional
Worth it before risky migrations; skip it for stateless changes.
Communicate
-
Team channel notified that the
{{service}}deploy is starting -
Support or customer-facing staff informed about user-visible changes optional
-
Status page maintenance notice posted if downtime is expected optional
Deploy
-
Feature flags for unfinished work are switched off in
{{environment}} -
Migrations applied and their output checked for errors
-
New version
{{version}}rolled outPrefer a gradual rollout (one instance or a canary first) when your platform supports it.
-
All instances report the new version and are healthy
Verify
-
Smoke test of the critical user flow passes (log in, core action, payment if relevant)
-
Error rate and latency dashboards look normal for 15 minutes after the deploy
-
Logs show no new error types
-
Background jobs, queues and scheduled tasks are processing
-
New features behave as expected in
{{environment}}
Close out
-
Team channel updated: deploy finished, or rolled back with a reason
-
Tickets moved to done and the release tagged in the issue tracker
-
Follow-ups captured as tickets (cleanup migrations, flag removal, monitoring gaps)
Checklist as Markdown
Start this checklist from your pipeline
On a pushed tag, POST /api/v1/runs with template "Deploy {{service}} {{version}} to {{environment}}" and the tag as version.
curl -X POST https://runbook.metastic.ch/api/v1/runs \
-H "Authorization: Bearer $RUNBOOK_TOKEN" \
-H "Content-Type: application/json" \
-d '{"template": "Deploy {{service}} {{version}} to {{environment}}", "variables": {"service": "…", "version": "…", "environment": "…"}}'Frequently asked questions
What is the difference between a deployment checklist and a release checklist?
A deployment checklist covers the technical act of putting a version into an environment: pre-flight checks, rollout, verification and rollback. A release checklist covers the wider business event around it, such as announcements, documentation and support readiness. Many teams run both, and one release can contain several deployments.
Should every deployment use a checklist, even with full CI/CD?
Automated pipelines remove most of the manual steps, but the judgement calls remain: is the migration safe, is anyone around to watch, does support know? Keep the checklist short for routine deploys, and mark the heavier steps as optional so they are visible without being mandatory.
How do I start this checklist automatically from CI?
Create an API token in Runbook and add a step to your pipeline that calls POST /api/v1/runs with the
template name and the variables service, version and environment. The run then appears with the
correct version filled in, and the link can be posted to your team chat.
Updated