> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Operations Runbook

> Runbook for deployments, incidents, and monitoring.

# Operations Runbook

This page is the published runbook for deployments, incidents, and monitoring.

For production Supabase migration reliability, use the dedicated runbook:

* [Supabase Migration Reliability (Production)](/operations/supabase-migration-reliability)

## CI/CD Checklist

* Run lint, docs lint, typecheck, tests, and builds before merge.
* Treat Mintlify link checks and docs build validation as part of the normal verification path.
* Use release tags only after the repo contract is green.
* Track container builds, migration validation, dependency review, and secret scanning as hardening backlog until they are added to the default workflows.

## Common Incidents

1. **Webhook outage** – inspect `/internal/runtime`, check verification errors, replay affected envelopes.
2. **Rate-limit breach** – pause campaigns, adjust scheduler backoff, document `130429`/`131056` errors.
3. **Journey/campaign failure** – review `journey_runs`, replay via `/internal/webhooks/:id/replay`, log in adversarial notes.

## Monitoring Targets

* webhook latency
* queue depth
* template validation failures
* per-phone-number throughput
* pair-rate backoff events
* delivery error distributions
* feature-flag drift

## Routine Tasks

* Rotate credentials, log audit events.
* Update adversarial notes after fixes.
* Sweep retention policies for raw payloads and rejections.

## gb-agent connector triage

Use this block when an operator reports a stuck or surprising gb-agent draft state. Full surface details in [Platform → gb-agent Connector](/platform/gb-agent-connector).

| Symptom                                                 | Likely cause                                                    | First check                                                                                                                      |
| ------------------------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| Inbox trigger disabled with "Endpoint not configured"   | No connector URL/token in workspace settings                    | Settings → Integrations → gb-agent; confirm Vault secret exists                                                                  |
| Inbox trigger disabled with "Endpoint unsafe"           | Configured URL is not https or contains userinfo/query/fragment | Replace with clean https URL; the UI mapper rejects unsafe URLs deliberately                                                     |
| "Draft already queued" on every attempt                 | A pending draft from the connector exists in `message_drafts`   | Resolve the existing draft (Accept/Edit/Reject) or run release\_stuck\_outbox\_jobs if it is leased and stuck                    |
| Operator reports the handoff preview card is missing    | Feature flag `inbox.gbAgentHandoffPreview` is OFF               | Set `NEXT_PUBLIC_FLAG_INBOX_GB_AGENT_HANDOFF_PREVIEW=1` on apps/app Vercel project; redeploy                                     |
| Operator reports an action they did not click was taken | Should never happen — the connector is dry-run-only             | File as a bug; check `responder_runs.metadata.policyDecisions` for `requiresHumanApproval: true` and `externalSendQueued: false` |