Release management workflow
Build, test, stage, and promote code to production safely.
A release that breaks production costs hours of incident response, angry users, and lost revenue. This template shows how discipline prevents that: automated tests catch 80% of bugs, staging lets QA find the other 15%, and production is a deliberate manual gate with monitoring in place so on-call can roll back in seconds if needed.
The workflow separates fast feedback loops (code → build → Dev, minutes) from safety gates (staging approval, production monitoring) so you move fast when it's safe and slow down when stakes are high. It's the difference between a release that ships daily and one that ships once a quarter in fear.
When to use this template
- Release runbooks — new on-call engineers understand the flow from code to production, including where to check logs and which person has permission to promote each stage.
- Team onboarding — show the team how code moves from "committed" to "in users' hands", including which checks are automatic and which require human judgment.
- Incident postmortems — when a bad release gets through, use this diagram to identify which gate failed (test didn't catch it? QA approved it? monitoring didn't alert?) and close that gap next time.
How to adapt it
Customize the environments to your setup (maybe you use Canary instead of Staging, or you have a Pre-Prod gate for database migrations). Common extensions:
- Add a feature flag node before Production, showing how you gate features by percentage of traffic (1% → 10% → 100%) to catch bugs gradually.
- Insert a security scan (dependency check, static analysis) after build and before Dev to catch vulnerabilities before they ship.
- Show the rollback trigger — add a dashed path from Monitoring back to "Revert to previous version" so the team knows on-call can undo a release if metrics spike.
Visual edits regenerate clean code, so you can add stages, parallel checks, or approval gates without Mermaid syntax.
Mermaid code
Copy it anywhere Mermaid is supported — GitHub, Notion, or your docs.
flowchart TD
A["Code committed<br/>to main"] --> B["Automated build<br/>& test"]
B --> C{"Tests pass?"}
C -->|No| D["Notify team<br/>Fix and retry"]
D --> B
C -->|Yes| E["Build Docker image<br/>Tag with commit SHA"]
E --> F["Push to Dev<br/>Automated deployment"]
F --> G["Smoke tests<br/>Health checks"]
G --> H{"Staging ready?"}
H -->|No| I["Rollback to<br/>previous version"]
H -->|Yes| J["Stage for QA<br/>Manual testing"]
J --> K{"QA approved?"}
K -->|No| L["Log issues<br/>Assign fixes"]
L --> B
K -->|Yes| M["Production<br/>Manual promotion"]
M --> N["Monitor metrics<br/>Alert on errors"]
Frequently asked questions
- What does a release workflow diagram show?
- It traces code from commit through build, test, staging, and production gates, showing which checks are automated (fast, repeatable) and which require human approval (QA, release lead). It makes it clear which failures block forward progress and which allow rollback, so teams know the risk at each stage.
- Why have separate Dev, Staging, and Production environments?
- Dev catches build failures fast (minutes). Staging matches production config so QA finds integration issues before they hit real users. Production is where the stakes are high — metrics monitoring and rollback procedures protect against bad releases. Each environment is a safety net.
- When should automated smoke tests run?
- Right after deployment to Dev or Staging, before humans test manually. Smoke tests verify that the app boots, the database connects, and core endpoints respond — they catch infrastructure misconfigurations and broken dependencies within seconds. They're cheap to run and catch ~80% of catastrophic failures.
- What should I monitor after production deployment?
- Error rate (spikes = broken code), latency (P50, P95, P99 to spot slowdowns), and business metrics (signups, orders, revenue) in the first 5 minutes post-release. Set alert thresholds so on-call can roll back within 1–2 minutes if metrics degrade. Annotate this diagram with those thresholds so the team agrees on what "bad" means.