Hotfix Release Checklist

A hotfix checklist for urgent production fixes: confirm the cause, keep the change small, get a fast review, deploy with care and merge the fix back to main.

Typical schedule per hotfix
The checklist 5 sections, 20 items
Variables {{service}} {{version}} {{issue}}
Start from CI

Use this template Free, no credit card. Imports the checklist into your Runbook organization.

Use this checklist when a bug in production cannot wait for the next regular release: a broken checkout, a security hole, data being written incorrectly, or a crash for a large group of users. A hotfix skips the normal release rhythm, but it should not skip review and verification. The pressure to be fast is exactly when steps get missed.

Who owns it

One engineer owns the hotfix run from branch to merge-back. If an incident is open, the incident lead decides whether a hotfix is the right response and the hotfix owner reports back to them. A second engineer reviews the change, even if the review is short.

Common pitfalls

Fixing a guess. Under pressure, teams ship a fix for the cause they suspect. Reproduce the bug or find clear evidence in logs before you change code.
Bundling extra changes. A hotfix that also contains "a few small things" from main is a release, not a hotfix. Branch from the deployed version and change only what fixes the problem.
Forgetting to merge back. If the fix only lives on the hotfix branch, the next regular release brings the bug back. Merge or cherry-pick it into main the same day.
No test for the bug. Add a test that fails without the fix. It proves the fix works and keeps the bug from returning.
Skipping the follow-up. A hotfix fixes the symptom. Plan a review of how the bug reached production.

The checklist: Hotfix {{service}} {{version}}

Confirm the problem

Issue {{issue}} is reproduced or confirmed with logs, metrics or user reports
Impact is described: who is affected, since when, and how badly
Decision to hotfix instead of waiting for the next release is recorded with the reason
A workaround or feature flag that limits the impact now is applied optional

Build the fix

Hotfix branch is created from the version currently deployed, not from main
The change is limited to the fix for {{issue}}
A test that fails without the fix and passes with it is added
Change is reviewed by a second engineer
CI is green on the hotfix branch

Deploy

Team and support are told that hotfix {{version}} is going out
Rollback target is noted: the currently deployed version
Hotfix {{version}} is deployed to staging and the fix is confirmed there optional
Skip only if the impact in production is worse than the risk of an untested deploy, and record that.
Hotfix {{version}} is deployed to production

Verify

The original problem from {{issue}} no longer occurs in production
Error rate and the main user flows look normal after the deploy
Affected users or data are identified and a cleanup is planned if needed optional

Close out

Fix is merged or cherry-picked into main and any active release branches
Release notes or changelog mention hotfix {{version}}
Support and affected customers are informed that the issue is fixed
Post-incident review is scheduled to find out how the bug reached production optional

Checklist as Markdown

# Hotfix {{service}} {{version}}

## Confirm the problem
- [ ] Issue {{issue}} is reproduced or confirmed with logs, metrics or user reports
- [ ] Impact is described: who is affected, since when, and how badly
- [ ] Decision to hotfix instead of waiting for the next release is recorded with the reason
- [ ] A workaround or feature flag that limits the impact now is applied (optional)

## Build the fix
- [ ] Hotfix branch is created from the version currently deployed, not from main
- [ ] The change is limited to the fix for {{issue}}
- [ ] A test that fails without the fix and passes with it is added
- [ ] Change is reviewed by a second engineer
- [ ] CI is green on the hotfix branch

## Deploy
- [ ] Team and support are told that hotfix {{version}} is going out
- [ ] Rollback target is noted: the currently deployed version
- [ ] Hotfix {{version}} is deployed to staging and the fix is confirmed there (optional)
  Skip only if the impact in production is worse than the risk of an untested deploy, and record that.
- [ ] Hotfix {{version}} is deployed to production

## Verify
- [ ] The original problem from {{issue}} no longer occurs in production
- [ ] Error rate and the main user flows look normal after the deploy
- [ ] Affected users or data are identified and a cleanup is planned if needed (optional)

## Close out
- [ ] Fix is merged or cherry-picked into main and any active release branches
- [ ] Release notes or changelog mention hotfix {{version}}
- [ ] Support and affected customers are informed that the issue is fixed
- [ ] Post-incident review is scheduled to find out how the bug reached production (optional)

Start this checklist from your pipeline

When a hotfix/* branch is pushed, POST /api/v1/runs with template "Hotfix {{service}} {{version}}" and the ticket ID as issue.

curl -X POST https://runbook.metastic.ch/api/v1/runs \
  -H "Authorization: Bearer $RUNBOOK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "Hotfix {{service}} {{version}}", "variables": {"service": "…", "version": "…", "issue": "…"}}'

See the API and the GitHub Action

Frequently asked questions

What is the difference between a hotfix and a patch release?

A hotfix is an urgent fix deployed outside the normal schedule because the problem cannot wait. A patch release is a planned small release with bug fixes, often on a regular rhythm. Many teams number both as patch versions, but only the hotfix skips the usual release cycle.

Should a hotfix go through code review?

Yes. The review can be short and synchronous, for example on a call, but a second person should look at the change. Most hotfix regressions come from changes made in a hurry by one person under pressure.

Where should a hotfix branch start from?

From the commit or tag that is running in production. If you branch from main, you also ship every unreleased change merged since the last release. After the deploy, merge the fix back into main so the next release includes it.

Updated 2026-11-04