GitHub Merge Queue Approval Evidence Template: Incident Comment Macros for Safe Rollbacks (2026)
When rollback incidents hit, teams often lose time debating whether a merge queue bypass is justified. The technical fix is usually quick; the slow part is approval alignment and missing evidence. If one approver asks for context in chat and another asks in the PR thread, your queue-to-merge time stretches while production is already degraded.
This guide gives a copy-paste approval evidence template and PR comment macros so incident responders can make bounded, auditable decisions without improvising process during pressure.
Table of contents
1. Why approval evidence templates matter
Templates are not bureaucracy. They are latency control for incident decisions. A good evidence template removes clarification loops and forces the same minimum signal each time.
| Without template | With template | Operational effect |
|---|---|---|
| Approvals happen in fragmented chat threads | All evidence and approvals in PR + incident timeline | Faster handoffs and cleaner postmortem |
| Expiry omitted or implicit | Explicit UTC expiry required field | Reduces policy drift after recovery |
| Risk controls assumed but not stated | Compensating controls mandatory | Lower chance of secondary incident |
| Unclear restoration ownership | Named restoration owner in same comment | Branch protections restored faster |
2. Required evidence fields
Use these fields for every emergency bypass request. Keep wording short and factual.
| Field | What to write | Why it matters |
|---|---|---|
| Incident ID | Immutable incident ticket/reference | Connects all actions to one timeline |
| Severity and impact | SEV level + customer/system impact in one line | Justifies urgency |
| Rollback target | PR number + last known good commit | Defines exact blast radius |
| Baseline path failure evidence | Timeout, cancellation, queue starvation, or policy block with links | Prevents unjustified bypass |
| Compensating controls | Smoke tests, canary %, watch window, alert ownership | Limits post-merge risk |
| Approver A + B | Incident commander + service owner (or delegate) | Enforces dual control |
| Expiry timestamp (UTC) | Short validity window (30-60 min typical) | Prevents lingering policy exceptions |
| Restoration owner | Named individual responsible for policy restore | Creates explicit closure path |
3. Copy-paste PR comment macros
Macro A: Bypass request
Emergency bypass request (rollback)
Incident: INC-2026-02-16-221
Severity/impact: SEV-1, checkout API returning 5xx in prod
Rollback PR: #8421
Rollback target: 8f17c2d (last known good)
Baseline queue path failure evidence:
- required-ci timeout twice
- queue wait exceeded 18m SLO
- workflow run links: [run-1], [run-2]
Compensating controls:
- smoke suite: /health + checkout + payments
- canary: 5% for 10 minutes
- on-call watch: @oncall-payments
Approver A (IC): @alice
Approver B (Service Owner): @bob
Expiry (UTC): 2026-02-16T23:40:00Z
Restoration owner: @carol
Macro B: Approver acknowledgment
Approval recorded.
Role: Incident Commander
Decision: Approved for bounded rollback bypass
Conditions:
- Expiry honored exactly at 2026-02-16T23:40:00Z
- Compensating controls executed and logged
- Restoration owner confirms baseline policy restore in this thread
Macro C: Expiry extension (if needed)
Expiry extension request
Reason extension is required: smoke tests delayed by runner backlog
Previous expiry: 2026-02-16T23:40:00Z
Proposed new expiry: 2026-02-17T00:05:00Z
Updated evidence links: [run-3]
Reapproval required from both approvers before old expiry.
Macro D: Restoration completion
Bypass restoration completed
Timestamp (UTC): 2026-02-17T00:01:12Z
Restored items:
- Required check set returned to baseline
- Temporary override removed
- Branch ruleset diff attached
Post-incident follow-up:
- RC item #1: stabilize required-ci timeout
- RC item #2: add queue latency alert at 10m
4. Incident timeline sequence
- Open rollback PR and add Macro A with complete evidence block.
- Get dual approvals in-thread (not only in chat).
- Execute bounded bypass and merge rollback.
- Run compensating checks and log results in same thread.
- Restore baseline policy before expiry time.
- Post Macro D and link root-cause action items.
This sequence ensures your incident timeline has a clean audit chain: request -> approval -> execution -> restoration.
5. 15-minute workflow
| Minute | Action | Owner |
|---|---|---|
| 0-3 | Draft Macro A with links to failing queue runs | Requester |
| 3-6 | Collect dual approvals (Macro B style) | IC + service owner |
| 6-10 | Merge rollback and execute smoke/canary checks | Responder + on-call |
| 10-15 | Restore baseline policy and post Macro D | Restoration owner |
6. Audit package checklist
- Rollback PR link with Macro A/B/C/D chain intact
- Incident timeline links to queue failure evidence and merge event
- UTC expiry timestamp plus restoration confirmation
- Branch rule diff or screenshot proving baseline restore
- Post-incident issue links for CI/queue remediation
Skip none of these. If your team has a compliance review later, this package is what auditors and SRE leads will request first.
7. Guardrail metrics
| Metric | Healthy range | Escalate when |
|---|---|---|
| Bypass approvals missing expiry | 0% | Any occurrence |
| Bypass approvals missing dual sign-off | 0% | Any occurrence |
| Time to restore baseline policy | < 30 min | > 60 min |
| Emergency bypass frequency | 0-2 per month | > 4 per month |
If bypass frequency rises, treat it as CI/queue reliability debt, not a process success signal.
8. FAQ
What evidence is mandatory before emergency bypass approval?
Incident ID, severity and impact, rollback target, baseline queue failure evidence, compensating controls, dual approvers, expiry, and restoration owner.
Who should provide approvals in the template?
Use two roles: incident commander plus service owner (or named delegate). Requester-only approval is a governance failure.
Can we reuse one approval comment across multiple rollback PRs?
No. Each rollback PR needs its own evidence block and expiry because risk differs across change sets.
How long should bypass approvals stay valid?
Keep validity short, typically 30 to 60 minutes, then require refreshed evidence and reapproval.
Where should audit evidence be stored after incident closure?
Store in both PR discussion and incident timeline, and link follow-up actions for restoration and root-cause fixes.