n8n-upgrade-plan
Skill0 starsChanged 20 days agoMITView on GitHub
Plan and execute an n8n version upgrade on a customer instance without breaking the workflows that run there: inventory the node types and typeVersions in use, pull the breaking changes between the current and target versions from the docs server, decide what to re-test, take the rollback snapshot, upgrade, and reconcile the drift the upgrade creates. Use when the task mentions upgrading n8n, "is version X safe", a customer asking which version to run, doctor reporting a version gap, an n8n-mcp pin that trails the instance, or typeVersion drift after an upgrade. Not for upgrading the harness's own MCP server pin (knowledge/registry.yaml and the customer harness docs cover that).
In this repository27 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- n8n-agentsSkill
- n8n-binary-and-dataSkill
- n8n-canvas-docsSkill
- n8n-code-javascriptSkill
- n8n-code-pythonSkill
- n8n-code-toolSkill
- n8n-credential-mappingSkill
- n8n-enterprise-deliverySkill
- n8n-error-handlingSkill
- n8n-expression-syntaxSkill
- n8n-gotchasSkill
- n8n-instance-opsSkill
- n8n-mcp-tools-expertSkill
- n8n-multi-instanceSkill
- n8n-node-configurationSkill
- n8n-node-devSkill
- n8n-project-organizationSkill
- n8n-promotion-pipelineSkill
- n8n-self-hostingSkill
- n8n-subworkflowsSkill
- n8n-validation-expertSkill
- n8n-workflow-as-codeSkill
- n8n-workflow-mapSkill
- n8n-workflow-patternsSkill
- using-n8n-mcp-skillsSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 60
Every workflow with a node type that has a breaking entry in the range.
- Distinctive: line 61
Every workflow with mixed versions of one type.
- Distinctive: line 62
Every workflow with a Code node (runner changes), a webhook (path and auth handling), or an AI node (model and tool-calling changes land …
- Distinctive: line 89
Never leave the repo and the instance disagreeing after an upgrade.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
n8n upgrade plan
An upgrade is the one change that touches every workflow at once. The
customer's RUNBOOKS/upgrade-n8n-safely.md in the care kit holds the
operator steps; this skill is the engineering plan around it.
1. Know what runs
./scripts/doctor.sh prod # current version, reachability
./scripts/drift-check.sh prod # repo must agree with the instance first
./scripts/node-inventory.sh workflows/prod # node types, typeVersions, mixed versionsThe inventory is the list to check. A node type the estate does not use cannot break the upgrade. Mixed versions of one type mean two code paths to test, not one.
2. Pull the breaking changes
On the docs server (n8n-docs, no credentials), for each type in the
inventory:
get_node({ nodeType: "nodes-base.httpRequest", mode: "versions" })
get_node({ nodeType: "nodes-base.httpRequest", mode: "breaking" })
get_node({ nodeType: "nodes-base.httpRequest", mode: "migrations" })versions lists the typeVersions the bundled n8n knows; breaking the
behavior changes between them; migrations what to change in parameters.
The bundled n8n version is in tools_documentation(); if it is older than the
target, bump the pin first (the registry flags this) or read the release notes
by hand at docs.n8n.io/changelog/release-notes.
Then the release notes for the range, for the changes no node schema carries:
env var renames and removals, task-runner defaults, database migrations,
licence or module changes (N8N_DISABLED_MODULES), and anything marked
"breaking" in a minor. Write the list into the change ticket.
3. Decide the test set
Re-test, in this order, on dev after the dev upgrade:
- Every workflow with a node type that has a breaking entry in the range.
- Every workflow with mixed versions of one type.
- Every workflow with a Code node (runner changes), a webhook (path and auth handling), or an AI node (model and tool-calling changes land often).
- One of everything else, by tag.
Existing eval datasets run as-is; n8n-enterprise-delivery/EVAL_LOOP.md.
4. Rollback point, then upgrade dev
./scripts/export-all.sh dev && git add -A && git commit -m "snapshot dev before upgrade to <x.y.z>"Plus the database backup the runbook prescribes; the export is the workflow rollback, the database backup is the instance rollback. Upgrade dev, run the test set, read executions, not just status codes.
5. Reconcile the drift the upgrade made
An upgrade bumps typeVersion on nodes it migrates. drift-check will report
it as a parameter or typeVersion change. That drift is real and the decision
is explicit:
- adopt:
export-all, review the diff withwf-diff, commit, so the repo carries the migrated version; - or redeploy from the repo, if the migration changed behavior you do not want and the old typeVersion still runs on the new release.
Never leave the repo and the instance disagreeing after an upgrade; the next promotion would carry the wrong version.
6. Promote the upgrade
Staging then prod through the customer's change window, same snapshot and
test discipline, same drift reconciliation. Record versions, dates and the
breaking-change list in INSTANCE.md and the runbook.
Related
n8n-self-hosting/DAY2.md: the upgrade mechanics per deployment shape.n8n-instance-ops: activation cache after a restart; webhooks after a proxy change.n8n-gotchas: version-boundary removals.knowledge/registry.yamlin the harness: when the n8n-mcp pin or the vendored skills trail the instance version.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

