Runbook Template

Runbooks live in each project repo (next to the code, versioned with it), not in this wiki. This page is the template only — there is no wiki-side index of runbooks, because an index would be per-client state and this wiki never holds that. docs/runbook.md is instead a day-one provisioning file, so “does this system have a runbook?” is answered by looking in the repo, not by trusting a table. When a runbook and the wiki disagree, the repo runbook wins.

Deploy / rollback shape

sequenceDiagram
  participant Dev as Engineer
  participant CI as Pipeline
  participant Env as Environment
  Dev->>CI: Merge to main
  CI->>Env: Deploy build
  Env-->>Dev: Health check
  Note over Dev,Env: On failure
  Dev->>CI: Re-run last-good build
  CI->>Env: Rollback deploy

The template

Copy into /docs/runbook.md in the project repo and fill every <placeholder>.

# <System name> — Runbook

## Overview
- Purpose: <what this system does>
- Owner / team lead: <name>
- Repo: <repo url>  |  Environments: <qa / uat / prod urls>

## Deploy
1. <trigger — e.g. squash-merge PR to main>
2. <pipeline name in Azure DevOps>
3. <post-deploy health check + expected result>

## Rollback
1. <how to identify last-good build>
2. <re-deploy / swap-slot steps>
3. <verify rollback succeeded>

## Logs & monitoring
- Logs: <where — e.g. App Insights / log stream>
- Dashboards / alerts: <links>

## Restart
- <how to safely restart the service / app>

## Backup & restore
- Backup: <what, schedule, where stored>
- Restore: <step-by-step, and how to verify>

## Dependencies
- <DBs, queues, third-party APIs, Key Vault secrets>

## Contacts
- L2 team lead: <name>  |  Original dev: <name>

## Gotchas
- <known traps, manual steps, ordering constraints>

Tip

Keep it operational — the steps a tired on-shift engineer runs at speed. Architecture belongs in an ADR, not here.

See also Support Model and Incident Response.