p24-infra Docs

n8n workflow versioning to git

3 min read

Spec 14 — n8n workflow versioning to git

Purpose

n8n workflows are edited via web UI. There is no diff, no rollback, no “who changed this on Tuesday?”. Spec 01 backs the whole DB up encrypted; this spec is complementary — human-readable JSON of every workflow committed to git nightly so we can diff, blame, and PR-review workflow changes.

Depends on spec 03 so the n8n API key isn’t checked in plaintext.

Rulebook

  1. n8n is the source of truth for execution; git is the source of truth for history. We don’t deploy workflows from git into n8n (that’s a different problem). We export from n8n to git for audit.
  2. No credentials in committed JSON. n8n exports credentials as id references only; the secrets stay encrypted in n8n. Verify with a grep before merge.
  3. One commit per night, no matter how many workflows changed. Atomic snapshot. Easier to bisect.

Architecture

GitHub Action (scheduled 04:00 UTC) on hstgr runner:
  1. curl n8n REST /workflows  → workflows.json
  2. curl n8n REST /credentials → credentials-meta.json (names + ids only)
  3. format JSON deterministically (jq -S)
  4. write to infra-src/n8n-workflows-export/
  5. if diff: commit + push (skip CI)

Implementation plan

  1. Create .github/workflows/n8n-workflow-snapshot.yml:
    • Schedule: 0 4 * * *
    • Runs on hstgr runner (has VPS access)
    • Pulls API key from sops (spec 03) or GH App secret
    • Exports workflows + credential metadata
    • Commits to infra-src/n8n-workflows-export/ if changed
  2. Add a README in that folder explaining: “This is auto-generated. Do not edit. To restore, see spec 01 restore drill.”
  3. Add an alert: N8nSnapshotStale — no commit in 26 h.

Acceptance criteria

  • First scheduled run commits N JSON files (one per workflow)
  • Diff between two consecutive runs is empty if no workflow changed
  • Manually editing a workflow in n8n and waiting until next run produces a meaningful diff in the next day’s commit
  • grep -ri "password\|token\|secret" infra-src/n8n-workflows-export/ returns no plaintext values

Cost impact

0 €.

Back-out plan

Disable the workflow. Existing exports stay in git history.

Risks / open questions

  • Risk: n8n’s API may evolve and break the export. Mitigation: workflow opens an issue on non-zero exit.
  • Q: Should the n8n.io Cloud instance also be exported? A: Yes, but its workflow set is currently “TODO: document” — out of scope for now.

Bootstrap

The workflow ships inert. Until N8N_API_KEY_HSTGR is set in GitHub Secrets, every run hits the pre-flight skip path and exits clean. To activate:

  1. Confirm spec 03 bootstrap is done and N8N_API_KEY_HSTGR is in secrets/vps-h1.sops.yaml with the real n8n REST API key. Generate the API key in the n8n UI: Settings → API → Create API Key — give it workflow:read,credential:read scope.
  2. Pre-create the GH label (one-time — otherwise the failure-issue step fails when invoked): 
    gh label create n8n-snapshot --color FF6B6B --description "n8n workflow snapshot job" --repo radieu/p24-infra
  3. Push the secret to GH Secrets via the secrets-sync workflow (it should fire automatically on commit; if not, gh workflow run secrets-sync.yml).
  4. Manually trigger the snapshot to verify: 
    gh workflow run n8n-workflow-snapshot.yml --repo radieu/p24-infra
gh run watch --repo radieu/p24-infra
  5. First successful run produces one commit with one JSON file per existing workflow under infra-src/n8n-workflows-export/workflows/. Diff against the human notes in infra-src/n8n-workflows/*.md to confirm parity.
  6. After 7 days of stable snapshots, the workflow is considered self-managing.

Graph View

Backlinks