n8n Playbooks — Index
Single entry point for all n8n-related playbooks (issue #2641
Task 5 — n8n playbook restructure). There were 23+ n8n playbooks scattered flat under
docs/playbooks/ with overlapping content; this index groups them by purpose so the right one
is one lookup away.
Status — Phase 2 complete: the 24 files below have been physically moved into this
docs/playbooks/n8n/directory (issue #2641 Task 5 Phase 2). Every cross-reference across the repo (other playbooks, ops docs, role indexes, scripts, GH Actions workflows, Prometheus/ Alertmanager configs) was rewritten to the new path. A prior attempt at full consolidation (PR #2645, closed unmerged) already drafted 3 merged playbooks (n8n-incident-response.md,n8n-credential-rotation.md,n8n-workflow-modification.md) — that content never landed onmainand is not part of this move. Historical/append-only records (CHANGELOG.md,docs/secrets-rotation-log.mdand its dated archives, closed design plans underdocs/plans/, and applied Supabase migrations) were deliberately left referencing the old paths — they document state at the time, not current navigation.
Incident response
Runtime failures: crashes, stuck executions, hangs, rate limits.
| Playbook | Covers |
|---|---|
n8n-bms4-stuck-execution-cleanup.md | Executions stuck in “running” state on bms-4 |
n8n-bms4-worker-crash-storm.md | Queue-mode worker containers crash-looping |
n8n-crashed-executions-db-connection-drop.md | PostgreSQL connection drop mid-execution |
n8n-workflow-db-query-hang.md | A workflow’s DB query node hangs indefinitely |
n8n-error-flow-discord-rate-limit.md | error-flow hits Discord webhook rate limits |
n8n-alert-router-empty-webhook.md | mezmo-alert-router / similar receives an empty webhook body |
n8n-alertmanager-incidents.md | Alertmanager → n8n → Supabase incidents pipeline failures |
n8n-redis-singleton-lock.md | Redis singleton-lock contention in queue mode |
Credential rotation
Rotating a secret n8n depends on, or that n8n itself issues.
| Playbook | Covers |
|---|---|
n8n-bms4-api-key-rotation.md | BMS4_N8N_API_KEY (self-hosted REST API key) |
n8n-cloud-api-key-rotation.md | N8N_CLOUD_API_KEY (n8n Cloud REST API key) |
n8n-db-password-rotation.md | N8N_DB_PASSWORD (bms-4 PostgreSQL) |
n8n-supabase-credential-rotation.md | Supabase credential used inside bms-4 n8n workflows |
n8n-cloud-supabase-credential-rotation.md | Supabase credential used inside n8n Cloud workflows |
n8n-waha-monitor-401-credential-drift.md | WAHA monitor credential drift (legacy — verify still relevant, WAHA decommissioned on vps-h1 2026-07-02) |
n8n-user-password-reset.md | n8n instance user/admin password reset |
n8n-supabase-vault-runtime-secrets.md | Supabase Vault-backed runtime secrets consumed by n8n |
github-app-token-n8n.md | GitHub App token used by n8n’s GitHub-automation workflows |
Workflow management (keep as-is per #2641)
| Playbook | Covers |
|---|---|
n8n-workflow-creation.md | Creating a new workflow via REST API |
n8n-http-request-quirks.md | n8n 2.26.x HTTP Request / IF node quirks (specifyBody, isTrue, $json overwrite) |
n8n-ssh-worker-pattern.md | Pattern for n8n nodes that SSH into a worker to run claude CLI |
Reference / other
| Playbook | Covers |
|---|---|
n8n-backup-secret-scrubbing.md | Ensuring workflow JSON backups don’t leak credential values |
Archive candidates — verify before removing
Flagged by #2641 as possibly obsolete. Not deleted in this PR — confirm each is genuinely
superseded before moving it to docs/archive/:
| Playbook | Why it’s flagged |
|---|---|
n8n-claude-proxy-removal.md | claude-proxy was removed from bms-4 on 2026-06-24 — this playbook documents that removal itself, so it is historical record, not an active runbook |
n8n-bms4-exporter-missing-key.md | Issue asked to verify relevance first — not independently confirmed obsolete in this pass |
n8n-ssh-credential-type-mismatch.md | Same — verify relevance first |
Related
docs/n8n-operations.md— bms-4 instance ops workbook (architecture, containers, deployment, backup/restore)docs/n8n-cloud-operations.md— n8n Cloud instance ops workbookdocs/n8n-workflow-inventory.md— cross-instance workflow inventory + HTTP retry/auth audit (#2641 Task 1+2)docs/p24-auth-worker-operations.md— the p24-auth CF Worker auth pattern thatcheck-p24-workflows-connection.shenforcesdocs/playbooks/secret-rotation-access-matrix.md— which credentials in this index are Tier 1/2 (agent-rotatable) vs human-action