n8n-promotion-pipeline
Skill0 starsChanged 21 days agoMITView on GitHub
Move n8n workflows between environments the supported way: the official @n8n/cli promotion connections (provider, connection, clone, promote, list-changes, reviewed-commit apply), .n8np package export and import with conflict and binding policies, source-control pull, and the gates that run before any of them. Use when the task is to promote dev to staging or prod, set up a promotion connection or Git provider, review what differs between a project and its branch, apply a reviewed commit, export or import a package, wire credential or data-table bindings across instances, build a CI promotion job, or decide between native promotion, source-control environments, package files and the harness deploy script. Not for building a workflow (authoring skills) or editing a live one in place (n8n-instance-ops).
- Reads credentials
- Installs packages
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-self-hostingSkill
- n8n-subworkflowsSkill
- n8n-upgrade-planSkill
- 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, 1 is distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 48
Never travels: credential values, variable values, data table rows, execution history, the encryption key, instance settings.
- Very specific: line 65
Run in this order on the source side.
- Very specific: line 144
Always pass all three --expected-* flags or none.
- Very specific: line 150
Use a projects-scoped connection when teams must promote independently.
≈ “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 promotion pipeline
Written 2026-10-19 from @n8n/cli 0.22.0 (n8n-cli --help and the skill the
package ships). The CLI is official (github.com/n8n-io/n8n, package
@n8n/cli). Re-check the command surface with npx @n8n/cli@<pin> --help
when the pin moves; this file is a cache of that output, not the source.
The question this skill answers: a workflow works on dev. How does it reach production so that a reviewer saw it, the target has what it needs, and nothing arrives by hand?
Four ways a workflow moves, and when each is right
| Mechanism | What it is | Use when | |
Promotion connections (n8n-cli promotion-*) | Instance-to-instance through a Git repo. Source instance promotes (export, commit, push); target instance applys (reset to branch tip, import). Reviewed-commit apply pins the exact SHA a human reviewed. | Licensed customer with two or more instances and a Git host. The default for an enterprise engagement. | |
Source control environments (Settings > Environments; n8n-cli source-control pull) | Each instance bound to a branch. Push from dev, PR between branches, pull on prod. The older feature; still the one with the in-product UI. | Customer already runs it, or wants the editor-side push button. One direction per instance. | |
| Packages (`n8n-cli package export | import, .n8np`, beta) | A file carrying selected workflows, folders or projects plus stubs, with explicit conflict and binding policies on import. | Air-gapped targets, one-off migrations, moving a demo into a customer tenant, seeding a tenant from a template set. |
Harness deploy (scripts/deploy.sh, public API) | PUT by name with the engagement's credential ledger, tag and canvas gates, read-back verification. | Dev only, and community-licensed instances where none of the above exists. Never the production path on a licensed customer. |
Decide on day one, write it into the engagement CLAUDE.md under Promotion
path, and never mix two mechanisms on one target: each assumes it owns the
instance's state.
What travels and what never does
Same rule for all three product mechanisms:
- Travels: workflow JSON, tags, folders, projects, credential stubs (id, name, type, expression-valued fields only), variable stubs (id, name), data table schemas.
- Never travels: credential values, variable values, data table rows, execution history, the encryption key, instance settings.
- Package export has
--credentialExportPolicy expression-values-only|no-valuesand--includeVariableValues; literal credential values never travel under any policy. - Since n8n 2.41.0 (PR n8n-io/n8n#39091, 2026-09-18) the exported package
keeps
versionIdandpublishedVersionIdinworkflow-metadata.json, not inworkflow.json, so a publish no longer dirties the content file. Packages exported before that fail metadata validation on import.
Consequence: every target needs its credential values, variable values and
data table rows set up as environment setup, before the first apply.
scripts/lint-workflow.sh prints the list (the promotion manifest) per
workflow.
Gates before anything is promoted
Run in this order on the source side. All offline, all in scripts/.
drift-check.sh devclean: the repo and the instance agree, so what you review is what will move.validate.sh <file>on every changed workflow: well-formed.lint-workflow.sh workflows/dev --require-tags: no environment literal hosts, every credential named, no$env, tags present, error workflow set, and the manifest of credentials and variables the target must already have.wf-diff.sh <base> <head>on each changed file: the semantic change a reviewer signs off on, not a canvas move.- The customer's review: a pull request on the promotion branch, or
list-changesoutput pasted into the change ticket.
The CI templates in the engagement scaffold run 2 to 4 on every push.
Promotion connections, end to end
Prerequisites: licensed instance with the promotions module; an API key whose
scopes include gitConnection:* (plus variable:list for promote when
workflows reference variables); a Git repository the customer owns; the CLI
pinned in the engagement (npm i --save-exact @n8n/cli@0.22.0) or run as
npx @n8n/cli@0.22.0. Configure with N8N_URL and N8N_API_KEY from the
engagement .env, never flags on the command line.
# 1. Provider: who may talk to the Git host. SSH returns a deploy key to add.
echo '{"name":"Customer GitLab","type":"git","auth":{"authType":"ssh-key","keyType":"ed25519"}}' \
| n8n-cli promotion-provider create --stdin --json > provider.json
jq -r '.publicKey' provider.json # add as a read-write deploy key
# 2. Connection: which repo, which directions.
n8n-cli promotion-connection create --file=connection.json
# 3. Clone each direction you will use. Cloning one does not ready the other.
n8n-cli promotion-connection clone <id> promote # on the source instance
n8n-cli promotion-connection clone <id> apply # on the target instance
# 4. Source side: see what differs, then promote.
n8n-cli promotion-connection list-changes <projectId> promote
n8n-cli promotion-connection promote <id> -m "CR-1234: order intake v3"
# 5. Target side: review, then apply exactly the reviewed commit.
n8n-cli promotion-connection list-changes <projectId> apply --sort=updatedAt --order=desc --json > reviewed.json
jq '{commitSha, changes}' reviewed.json
n8n-cli promotion-connection apply <id> \
--expectedConfigId=$(n8n-cli promotion-connection get <id> --jq '.configs.apply.id') \
--expectedBranch=$(n8n-cli promotion-connection get <id> --jq '.configs.apply.settings.branchName') \
--expectedCommitSha=<full sha from reviewed.json>connection.json (instance scope; projects scope links team projects one
connection each):
{
"name": "Production",
"scope": "instance",
"providerId": "<provider id>",
"target": { "schemaVersion": 1, "remoteUrl": "git@gitlab.example.com:ops/n8n-flows.git" },
"configs": {
"promote": { "settings": { "schemaVersion": 1, "baseBranchName": "main", "createBranchOnPromotion": true } },
"apply": { "settings": { "schemaVersion": 1, "branchName": "main" } }
}
}createBranchOnPromotion: true is what gives the customer a pull request:
promote pushes a branch, the PR merges to main, prod applies main. With
false, promote pushes straight to the base branch and the review gate is
gone. Required field either way.
Exit codes that matter
| Exit | Meaning | Do |
| 0 | Applied | Verify with a real execution on the target, then record it |
| 3 | source-changed: the branch moved since the reviewed SHA | Review again. Nothing was imported |
| 4 | blocked: preflight found missing bindings, access or conflicts | Fix what --json lists under preflight, then run the printed apply-continue with the same three --expected-* values. Nothing was imported |
Always pass all three --expected-* flags or none. The SHA must be the full
SHA. Check $? or the status field before reading counts.
Behaviors to design around
promoteexports all team projects on an instance-scoped connection. Use aprojects-scoped connection when teams must promote independently.applyresets the local checkout to the branch tip and overwrites the instance to match. Workflows on the target that the branch does not carry are at risk;apply-selectionremoves instance workflows the project owns whose ids are absent from the branch. Export the target first (export-all.sh prodand commit) as the rollback point.--forceon promote overwrites a diverged remote branch. Not in CI.authType: tokenmeans HTTP(S) username and password, not a Git host API token.publicKeyis null for a token provider.set-configreplaces the whole direction configuration; send every setting.- A project can be linked to one connection only.
- A provider cannot be deleted while a connection uses it.
Packages
n8n-cli package export -p <projectId> -o release-2026-10-19.n8np \
--workflowVersionPolicy published-strict \
--credentialExportPolicy no-values \
--missingWorkflowDependencyPolicy fail
n8n-cli package import --file release-2026-10-19.n8np -p <targetProjectId> \
--workflowConflictPolicy new-version \
--workflowPublishingPolicy preserve-published-state \
--credentialMatchingMode name-and-type --credentialMissingMode must-preexist \
--variableMissingMode must-preexist \
--dataTableMissingMode create --dataTableSchemaConflictPolicy fail \
--overwriteDeletionPolicy archive \
--bindings '{"credentials":{"<sourceId>":"<targetId>"}}'Policies worth stating in the handoff: published-strict refuses to export a
workflow that has unpublished changes, so what ships is what runs;
must-preexist for credentials and variables turns a missing value into a
failed import instead of a workflow that starts and fails later;
overwriteDeletionPolicy archive keeps the archive-not-delete rule.
--workflowIdPolicy source keeps ids stable across instances, which is what
makes sub-workflow references survive; new is the default and re-mints them.
Source-control environments
The older model: Settings > Environments binds an instance to a branch, push
from the editor, n8n-cli source-control pull on the target (or the UI).
Detail, including the no-conflict-detection rule and the one-direction-per-
instance rule, is in n8n-enterprise-delivery/SOURCE_CONTROL.md. Prefer
promotion connections for a new engagement; they carry reviewed-commit apply
and per-project scope, which environments do not.
CI shape
Source instance, on merge to the promotion branch (or on a schedule):
export-all (source) -> commit -> validate + lint + wf-diff on the PR
-> human review -> promotion-connection promote -m "<ticket>"Target instance, on approval:
export-all (target) + commit # rollback point
-> list-changes apply --json # capture commitSha
-> apply --expected-* # exit 3 or 4: stop, nothing imported
-> health-check + a real execution of each changed workflowSecrets in CI: N8N_URL and N8N_API_KEY per instance as masked variables.
The promotion API key is powerful (gitConnection:* plus whatever else it
carries); scope it to the project where the instance supports it, rotate it on
team change, and never reuse the dev key on prod.
Handoff wording
Under Promotion in the customer's HANDOFF.md: the mechanism chosen and why
the other three were not; the connection name, scope, repo and branches; who
reviews and where (PR, ticket); the exact apply command with the three
--expected-* flags; what exit 3 and exit 4 mean and who acts; the
environment-setup list (credentials, variables, data table rows) per target;
and the rollback (export-all snapshot plus apply of the previous SHA).
Related
CLI_REFERENCE.mdin this directory: the command and flag tables for@n8n/cli0.22.0, captured verbatim.n8n-enterprise-delivery: license tiers, RBAC, external secrets, the promotion checklist.n8n-workflow-as-code: making the diff a reviewer sees readable.n8n-instance-ops: the activation cache, which still applies after an apply that republishes a workflow.
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.

