Skip to content

feat(promotion): add environment apply/promote and n8n 2.46 project sync fields - #45

Merged
SomeoneWithOptions merged 1 commit into
mainfrom
feat/promotion-environment-apply
Nov 4, 2026
Merged

SomeoneWithOptions merged 1 commit into
mainfrom
feat/promotion-environment-apply

Conversation

@SomeoneWithOptions

Copy link
Copy Markdown
Owner

What / why

n8n 2.46.4 replaced /promotions/connections with /promotions/environments. #44 added environment management but left whole-instance sync addressing connections, and project sync still assumed the 2.45 field names. This PR finishes the migration: environment apply/apply-continue/promote, plus 2.46 request/response fields on the project sync routes. Every changed command keeps working against 2.45 instances.

Changes

  • New commands (phase 36, manifest implemented, deliveredThrough = 36):
    • n8n promotion environment apply <environment-id> → POST /promotions/environments/{id}/apply
    • n8n promotion environment apply-continue <environment-id> → POST .../apply/continue
    • n8n promotion environment promote <environment-id> → POST .../promote
    • Placement: these live under environment, next to connect/disconnect from feat(promotion): add promotion environments #44, because they take an environment ID and exist only on 2.46. The top-level promotion apply|apply-continue|promote stay connection-only (retired, for ≤2.45), so neither generation's command changes meaning.
    • Apply/apply-continue share the selection command code (--expected-from, --expected-environment-id/--expected-branch/--expected-commit, --input, --confirm-destructive-changes), so the confirmation, stdin --yes rule, exit codes 0/3/4/1 and next-step hints match the connection versions. Unlike the connection apply, the environment apply takes an optional expectedSource, so it gets the expected-source flags.
    • Promote mirrors promotion promote (--force, --yes, --idempotency-key, --output). The one difference: --commit-message is optional, because the 2.46 spec made commitMessage optional.
    • Environment IDs are validated as UUIDs before any request. An expected source that names configId is refused locally, and the error explains it came from ≤2.45.
  • Project sync on both generations:
    • expectedSource models configId and environmentId, both optional. Exactly one must be set, and it is sent as given.
    • Project apply/apply-continue add --expected-environment-id (2.46) next to --expected-config-id (2.45). The two flags are mutually exclusive, validated locally, and the error says which one each n8n version needs.
    • --expected-from passes through whichever ID the changes JSON or blocked result contains. A file with both IDs is refused.
    • Connection apply-continue refuses an environmentId source and points at environment apply-continue.
  • Response shapes:
    • environmentId is modelled next to connectionId/configId on apply, continue, changes and promote results, and text output prints whichever is present (Environment: or Config:).
    • The new counts (folders.updated/moved/renamed, workflows.moved, credentials.updated) are *int and render only when the instance sends them, so a 2.45 result never shows invented zeros.
    • Promote results now keep the verbatim JSON (--output json is lossless for both shapes).
    • Promote review (reviewId, number, webUrl) renders as Review: #N URL. warnings (message, optional linkUrl) are advisory, since the push already happened, so they go to stderr in both output formats.
  • Errors:
    • The feat(promotion): add promotion environments #44 bare-404 hint ("older than 2.46 … use 'n8n promotion connection'") covers the three new commands.
    • Scopes: environment apply/apply-continue → gitConnection:pull, environment promote → gitConnection:push.
    • New 409 text for environment/project apply: the 2.46 refusal of workflows or folders held in different projects.
    • New 409 text for environment promote: remote rejected the push, so --force.
    • New 400 text for environment/project promote: a workflow moved to another or personal project.
  • Help:
    • The promotion group help no longer says apply/promote still address connections.
    • Connection apply/promote point at the environment commands for 2.46.
    • Project, changes and selection help describe both generations.
  • Text-only spec changes (C): the provider PUT/DELETE and repositories/branches descriptions changed only "connection" → "environment". Our provider, discovery and delete help now names both. Provider delete help used to say attached connections "keep their content but lose their credential". Both specs say a provider still in use cannot be deleted (409), so the help now says that, and the 409 hint names environments too.
  • Integration TestPromotionProjectChanges now accepts source.environmentId or source.configId.

Verification

  • make check with the 2.46.4 spec present as openapi.upstream.yml: green (fmt-check, vet, staticcheck all, test, test-race, cross for 5 targets, tidy-check, govulncheck: "No vulnerabilities found.")

  • make docs: regenerated; three new pages under docs/.

  • New client tests (internal/n8n/promotion_environment_sync_test.go): paths and bodies for the three routes, with and without expectedSource and commitMessage; error statuses; refusals before any request (bad UUID, configId source, both IDs, short commit, blank/long commit message, connection continue with an environmentId source); project apply/continue with both source variants; old- and new-shape decoding of apply, promote and changes; verbatim re-encoding. Idempotency header cases were added for all three routes.

  • New CLI tests (internal/cli/promotion_environment_sync_test.go): JSON and text output, new count rows (and their absence for 2.45), blocked/source-changed/unknown exit codes and hints, interactive decline and non-interactive refusal with zero requests, stdin --yes rule, flag exclusivity with per-version error text, --expected-from passthrough for both generations, promote review and warnings on stderr, 404/403/409/400/422 messages, and group help. The three commands were also added to TestIdempotencyKey* (header only when set, invalid key refused before any request).

  • make check passes locally

  • make docs run if CLI help changed (docs/README.md updated)

  • No secrets/keys/tokens in diff or logs

  • No v* tag or release commit in this PR (maintainer releases separately)

Notes for reviewer

  • No new integration tests for the three routes. Apply and promote rewrite every team project or push the remote, and integration tests must not mutate resources they did not create. Unit tests cover both response shapes.
  • Promote warnings go to stderr in JSON mode too. stdout stays the verbatim result, and a human reading a piped run still sees the advisory.
  • The specs were fetched, not committed: 2.46.4 as openapi.upstream.yml, 2.45.7 outside the repo for the diff.

🤖 Generated with Claude Code

…ync fields

n8n 2.46 replaced connections with environments. Add 'n8n promotion
environment apply|apply-continue|promote' for the three phase-36
operations and teach the project sync routes the 2.46 shapes while
keeping 2.45 instances working.

- Environment apply/apply-continue reuse the selection command: expected
  source flags or --expected-from, --input, confirmation, exit codes
  0/3/4/1, and idempotency keys. Promote mirrors 'promotion promote' with
  an optional commit message, as the 2.46 spec allows.
- expectedSource carries environmentId (2.46) or configId (2.45), never
  both. Project apply/apply-continue add --expected-environment-id,
  mutually exclusive with --expected-config-id; --expected-from passes
  through whichever ID the instance returned.
- Results model environmentId next to connectionId/configId, the new
  folder/workflow/credential counts as optional, and promote review and
  warnings. Warnings go to stderr; JSON stays verbatim.
- Help no longer says apply/promote need connections on 2.46; provider
  help follows the spec's environment wording.
- Manifest: phase 36 implemented; deliveredThrough raised to 36.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@SomeoneWithOptions
SomeoneWithOptions merged commit 0267901 into main Nov 4, 2026
5 checks passed
@SomeoneWithOptions
SomeoneWithOptions deleted the feat/promotion-environment-apply branch November 4, 2026 04:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant