docs: migration-safety for NocoDB/n8n plan + backlog status accuracy#47
Merged
Merged
Conversation
📝 WalkthroughWalkthroughTwo documentation files updated to establish migration safety gating for NocoDB/n8n composable cutover: migration plan marked EXECUTION HELD with new Task 0 prerequisites for pre-seeding OpenBao secrets, and deployment status notes reflect this hold plus pfSense sync operationalization details. ChangesMigration Safety Hold & OpenBao Pre-Seeding
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~4 minutes Possibly related PRs
Suggested labels
Poem
Important Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (2 errors, 1 inconclusive)
✅ Passed checks (7 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
…s accuracy Outcome of auditing the remaining deployment backlog. plan/development/nocodb-n8n-composable-migration.md: - Add a "Migration Safety" section + Task 0 (pre-seed existing secrets). The existing plan's `type: random` definitions are correct for a clean deploy but, on an in-place migration of the LIVE services, would regenerate stateful secrets: n8n N8N_ENCRYPTION_KEY (stored workflow credentials become permanently undecryptable), NocoDB JWT (sessions invalidated), and the Postgres passwords the existing data volumes were initialised with (auth failure). manage-secrets only generates when a key is ABSENT, so the existing values must be pre-seeded into secret/services/<svc> first. - Status set to EXECUTION HELD pending live OpenBao access for Task 0. CLAUDE.md deployment status: - pfSense sync -> Completed (runs as an orb-agent worker, 15-min cadence; no separate playbook was ever the plan). - NocoDB/n8n note now reflects reality: deployed via legacy deploy.sh; composable migration planned but held. Docs only.
JacobHaig
force-pushed
the
docs/backlog-status-and-migration-safety
branch
from
529c61f to
b9d8269
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plan/development/nocodb-n8n-composable-migration.md (1)
1133-1140:⚠️ Potential issue | 🟠 Major | ⚡ Quick winTask 9 status instruction contradicts the migration hold and should be updated.
This section says to move NocoDB/n8n to Completed, but the same document sets EXECUTION HELD pending Task 0 prerequisites. Keep status as held/in-progress until live secret pre-seeding is verified.
Suggested doc fix
-### Step 2: Update Deployment Status - -Move NocoDB and n8n from "In Progress" to "Completed" in the deployment status section, adding: - -```markdown -- **NocoDB composable deployment** — 4-phase playbook, Jinja2 templates, OpenBao integration -- **n8n composable deployment** — 4-phase playbook, Jinja2 templates, OpenBao integration -``` +### Step 2: Update Deployment Status + +Keep NocoDB/n8n in **In Progress (EXECUTION HELD)** until Task 0 is completed and validated on the live cluster, then update to Completed in a follow-up PR.As per coding guidelines,
plan/**/*.mdmust remain internally consistent and must not contradict CLAUDE.md deployment conventions.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plan/development/nocodb-n8n-composable-migration.md` around lines 1133 - 1140, The deployment status update incorrectly marks NocoDB and n8n as Completed despite the document-wide EXECUTION HELD on Task 0; revert the suggested "move to Completed" change in Step 2 and instead keep both "NocoDB composable deployment" and "n8n composable deployment" listed as In Progress (EXECUTION HELD) with a note that they will be moved to Completed only after Task 0 (live secret pre-seeding) is verified, and update the Step 2 heading text to instruct updating to Completed in a follow-up PR once Task 0 validation is done (referencing the Step 2 section, Task 9 mention, and Task 0 prerequisite).
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 213-214: Add a single blank line immediately before the "### In
Progress" heading in CLAUDE.md (i.e., insert an empty line between the last
bullet of the "Completed" section and the line that starts with "### In
Progress") to satisfy markdownlint rule MD022; ensure you only add one newline
and do not alter surrounding text or bullets.
---
Outside diff comments:
In `@plan/development/nocodb-n8n-composable-migration.md`:
- Around line 1133-1140: The deployment status update incorrectly marks NocoDB
and n8n as Completed despite the document-wide EXECUTION HELD on Task 0; revert
the suggested "move to Completed" change in Step 2 and instead keep both "NocoDB
composable deployment" and "n8n composable deployment" listed as In Progress
(EXECUTION HELD) with a note that they will be moved to Completed only after
Task 0 (live secret pre-seeding) is verified, and update the Step 2 heading text
to instruct updating to Completed in a follow-up PR once Task 0 validation is
done (referencing the Step 2 section, Task 9 mention, and Task 0 prerequisite).
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository UI (base), Organization UI (inherited)
Review profile: ASSERTIVE
Plan: Pro
Run ID: 7d0e2c34-5cd9-4f17-a72a-349d6dbb386d
📒 Files selected for processing (2)
CLAUDE.mdplan/development/nocodb-n8n-composable-migration.md
Comment on lines
213
to
+214
| ### In Progress | ||
| - NocoDB and n8n deployment via composable pattern | ||
| - pfSense sync as independent scheduled workflow (every 15 min) | ||
| - NocoDB and n8n deployment via composable pattern — both are deployed today via the **legacy** `deploy.sh` path (bash-generated secrets in an on-VM `secrets/` dir). Migration to the composable pattern is planned in `plan/development/nocodb-n8n-composable-migration.md` but **execution is HELD**: it's an in-place migration of live services with stateful secrets (n8n `N8N_ENCRYPTION_KEY`, NocoDB JWT, Postgres passwords) that must be pre-seeded into OpenBao before cutover or they'd be regenerated — needs live OpenBao access first (see that plan's "Migration Safety"). |
There was a problem hiding this comment.
Add a blank line before ### In Progress to satisfy markdownlint MD022.
Insert one empty line between the last bullet in “Completed” and the ### In Progress heading.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 213-213: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@CLAUDE.md` around lines 213 - 214, Add a single blank line immediately before
the "### In Progress" heading in CLAUDE.md (i.e., insert an empty line between
the last bullet of the "Completed" section and the line that starts with "### In
Progress") to satisfy markdownlint rule MD022; ensure you only add one newline
and do not alter surrounding text or bullets.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Outcome of auditing the remaining deployment backlog (per "go through all remaining items"). The audit found most "In Progress" items are further along than the status notes implied, and surfaced a real data-loss footgun in the existing NocoDB/n8n migration plan. Docs only — no code/behavior change.
nocodb-n8n-composable-migration.md— Migration Safety + Task 0The existing 9-task plan (2026-05-10) is sound for a clean deploy, but its
_secret_definitions: type: randomwould, on an in-place migration of the live services, regenerate stateful secrets:N8N_ENCRYPTION_KEYNC_AUTH_JWT_SECRETmanage-secrets.ymlonly generates arandomsecret when it's absent at its OpenBao path — and the legacydeploy.shstored these under a VMsecrets/dir / different keys. So a naive first run regenerates them. Added a Migration Safety section + Task 0 (read the live values, pre-seed them intosecret/services/<svc>at the exact keys, verify withcheck-secrets.yml, diff the rendered.envbeforecompose up). Status → EXECUTION HELD pending live OpenBao access, per decision.CLAUDE.md— status accuracydeploy.shpath; composable migration planned but held (links the safety section).Validation
Docs only;
plan/ASCII-art gate passes; secret/IP audit clean.Context
This is the planning/docs half of working through the backlog. Companion follow-up: implementation-plan docs for the Planned items (NemoClaw automation, Cowork, cross-agent, Kubernetes). Execution of the NocoDB/n8n migration itself is deferred until we can read live OpenBao.
Documentation: Migration Safety for NocoDB/n8n Composable Deployment + Backlog Status
Scope: Documentation and planning only; no code changes.
Changes:
Migration Safety Pre-requisite (Task 0) added to
plan/development/nocodb-n8n-composable-migration.md: Identifies a critical risk in the in-place migration of already-deployed NocoDB and n8n services — their stateful secrets (n8nN8N_ENCRYPTION_KEY, NocoDBNC_AUTH_JWT_SECRET, Postgres passwords) would be regenerated on first composable deploy if not pre-seeded into OpenBao at the exact paths thatmanage-secrets.ymlexpects. Regenerating these causes unrecoverable data loss (workflow credentials become undecryptable) and service breakage (session invalidation, auth failures). Task 0 prescribes capturing live values from the current deployment, writing them to OpenBao, validating withcheck-secrets.yml, and diffing.envbefore compose-up.Plan Status Updated: Migration marked "EXECUTION HELD" pending live OpenBao access to execute Task 0; execution deferred until the prerequisite can be safely completed.
Deployment Backlog Clarified in
CLAUDE.mdunder "Deployment Status → In Progress":deploy.shwith on-VMsecrets/directories. Composable migration is planned but execution is held due to stateful-secret safety concerns outlined above.Architectural Decision: The PR documents a discovered gap in the composable deployment pattern:
type: randomsecret definitions (correct for clean deploys) are unsafe for in-place migrations of stateful services without a pre-seeding step. This becomes a standing requirement for any service with persistent state (data volumes, session keys, encryption keys).Security Impact: Establishes a migration safety gate that prevents unintended secret regeneration during in-place deployments, protecting stored credentials and service state from loss or corruption.