Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 9 additions & 6 deletions docs/n8n_promotion.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,15 @@ Manage the upstream-only Promotions generation of Git sync.
Start with 'provider list' to find a provider, then 'connection list'
to find a connection. Create a provider first, then a connection on
it, then a config per direction under 'config', clone each checkout
under 'checkout', link team projects under 'project', then 'promote'
local projects to the remote or 'apply' the remote into the instance.

'promote' commits and pushes every team project to the remote;
'apply' resets the apply checkout and imports with overwrite behavior,
creating, updating, or removing content to match. Both mutate versioned
under 'checkout', link team projects to a projects-scope connection
under 'project', then 'promote' the instance to the remote or 'apply'
the remote into the instance.

'promote' and 'apply' run on the instance connection. 'promote'
commits and pushes every team project to the remote; 'apply' checks the
package and imports with overwrite behavior, creating, updating, or
removing content to match, or reports why it is blocked and writes
nothing. Both mutate versioned
content and ask for confirmation. Config and connection removal can
remove local checkouts. This is the upstream Promotions generation: an
instance that serves GitConnections instead answers 404 or 503, which
Expand Down
31 changes: 22 additions & 9 deletions docs/n8n_promotion_apply.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,29 @@ Apply the Git remote into this instance

### Synopsis

Reset the apply checkout to the branch tip and import projects into
the instance, overwriting to match. The apply checkout must be cloned
first. Preview what is linked with 'n8n promotion project list'.

This rewrites instance content from the remote and cannot be undone:
workflows, folders, credentials, data tables, variables, and tags are
created, updated, or removed to match the branch, and credential gaps
become stubs. Interactive runs ask for confirmation and
Check the full package at the apply branch tip and import it into the
instance, overwriting to match. Runs on the instance connection; the
apply checkout must be cloned first.

The server answers one of three statuses, and only one writes:
applied content was imported; counts and warnings follow.
blocked preflight stopped before any write: missing projects,
missing credential or variable bindings, access
requirements, or conflicts (including project-deletion
and data-table destructive-change). Nothing was applied.
source-changed the branch moved since it was reviewed. Nothing was
applied.

An applied run rewrites instance content from the remote and cannot be
undone: workflows, folders, credentials, data tables, variables, and
tags are created, updated, or removed to match the branch, and
credential gaps become stubs. Interactive runs ask for confirmation and
non-interactive runs require --yes. Requires gitConnection:pull.

Exit codes: 0 applied, 3 blocked, 4 source-changed, 1 any other error
or an unknown status. --output json prints the full result on stdout
in every status; the next step goes to stderr.

```
n8n promotion apply <connection-id> [flags]
```
Expand All @@ -31,7 +44,7 @@ n8n promotion apply <connection-id> [flags]
```
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
-h, --help help for apply
--output string output format: text or json (JSON is the apply result with counts and commit) (default "text")
--output string output format: text or json (JSON is the full apply result: status, git, and counts or preflight) (default "text")
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--yes confirm overwriting instance content from the remote without prompting (required when stdin is not interactive)
```
Expand Down
4 changes: 4 additions & 0 deletions docs/n8n_promotion_connection_create.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ config {"settings":{"schemaVersion":1,"branchName":"main"}} and
the promote config {"settings":{"schemaVersion":1,
"baseBranchName":"main","createBranchOnPromotion":false}}.

On a gitlab provider the remote URL must belong to the provider: the
connection stores only the repository path (reported read-only as
target.repositoryPath, never sent) and derives remoteUrl from the
provider base URL. Only one instance-scope connection can exist.
Unknown fields and trailing JSON documents are refused before
transport. Requires gitConnection:create. Follow with
'n8n promotion config apply set' and 'n8n promotion config promote
Expand Down
4 changes: 3 additions & 1 deletion docs/n8n_promotion_project.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,9 @@ Manage projects linked to a promotion connection

### Synopsis

Manage which team projects one promotion connection syncs. Start with
Manage which team projects a projects-scope promotion connection
syncs; a project's own connection takes precedence over the instance
connection for project-level sync. Start with
'list' to see the linked project IDs, then 'add' a project or
'remove' one.

Expand Down
5 changes: 3 additions & 2 deletions docs/n8n_promotion_project_add.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ Add a project to a promotion connection

### Synopsis

Add one team project to one promotion connection so promote and apply
include it. A project can belong to only one connection: adding a
Link one team project to one projects-scope promotion connection, so
project-level sync uses that connection instead of the instance
connection. A project can belong to only one connection: adding a
project that is already linked elsewhere answers 409. The checkout
must be cloned first. Requires gitConnection:manageProjects.

Expand Down
5 changes: 3 additions & 2 deletions docs/n8n_promotion_project_list.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ List projects linked to a promotion connection

### Synopsis

List the team projects added to one promotion connection. These are
the projects 'promote' exports and 'apply' overwrites. Find the
List the team projects linked to one projects-scope promotion
connection. Connection-level 'promote' and 'apply' run on the instance
connection and do not use these links. Find the
connection ID with 'n8n promotion connection list'. Requires
gitConnection:read.

Expand Down
3 changes: 2 additions & 1 deletion docs/n8n_promotion_project_remove.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ Remove a project from a promotion connection

Unlink one project from one promotion connection. The project itself
and its instance content are untouched; only the sync link goes away,
so later promotes and applies skip it. Re-add it later with 'n8n
so project-level sync falls back to the instance connection. Re-add it
later with 'n8n
promotion project add'.

Interactive runs ask for confirmation; non-interactive runs require
Expand Down
11 changes: 7 additions & 4 deletions docs/n8n_promotion_promote.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,13 @@ Promote team projects to the Git remote

### Synopsis

Export all team projects, commit them, and push to the promote
checkout's branch. The promote checkout must be cloned first: run 'n8n
promotion checkout clone CONNECTION_ID promote' and link projects
with 'n8n promotion project add'.
Export every team project, commit it, and push to the configured base
branch or a new timestamped branch (the result names it). Personal
projects are ignored. This runs on the instance connection only, so
project links from 'n8n promotion project add' do not select what is
promoted. The promote checkout must be cloned first: run 'n8n promotion
checkout clone CONNECTION_ID promote'. When workflows reference
variables, the API key also needs variable:list.

Pass --commit-message once (1 to 1000 characters). Without --force a
promote the remote would reject is refused with 409 and nothing is
Expand Down
52 changes: 35 additions & 17 deletions docs/n8n_promotion_provider_create.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,16 +4,27 @@ Create a promotion provider

### Synopsis

Create one promotion provider from strict JSON supplied by --input.
Required fields are name (at most 128 characters), type (git), and an
auth object: {"authType":"ssh-key"} with an optional keyType
(ed25519 or rsa, default ed25519), or {"authType":"token",
"username":"...", "password":"..."}.

Credentials travel only as --input because secrets are never flags:
process lists and shell history can expose argv. Unknown fields and
trailing JSON documents are refused before transport. Requires
gitConnection:create. Follow with 'n8n promotion connection create'.
Create one promotion provider from flags or from strict JSON supplied by
--input; the two ways are mutually exclusive and one is required.

Type git is a plain Git remote. Type gitlab is a Git host provider: the
server checks API access before saving and can list repositories. Pass
--base-url for self-managed GitLab; it becomes config {"schemaVersion":1,
"baseUrl":"..."} and applies to gitlab providers only.

Auth is ssh-key (the response carries the generated public key; add it
to the remote as a deploy key) or token. A token is never a flag: the
flag way asks for it without echo, or reads it from stdin with
--password-stdin. A git provider needs --username with a token; GitLab
ignores the username and uses n8n for Git transport.

The --input document has name (at most 128 characters), type (git or
gitlab), auth {"authType":"ssh-key"} with an optional keyType
(ed25519 or rsa, default ed25519) or {"authType":"token",
"password":"..."} plus username for git, and the optional config.
Unknown fields and trailing JSON documents are refused before
transport. Requires gitConnection:create. Follow with 'n8n promotion
connection create'.

```
n8n promotion provider create [flags]
Expand All @@ -22,19 +33,26 @@ n8n promotion provider create [flags]
### Examples

```
n8n promotion provider create --input provider.json
printf '%s\n' '{"name":"github","type":"git","auth":{"authType":"ssh-key"}}' | n8n promotion provider create --input -
n8n promotion provider create --name github --type git --auth-type ssh-key
printf '%s\n' "$GITLAB_TOKEN" | n8n promotion provider create --name gitlab --type gitlab --base-url https://gitlab.example.com --auth-type token --password-stdin
n8n promotion provider create --input provider.json --output json
```

### Options

```
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
-h, --help help for create
--input string promotion provider JSON file path, or - for stdin (required; maximum 1 MiB)
--output string output format: text or json (JSON is the provider returned by the API) (default "text")
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--auth-type string auth type: ssh-key or token (default: ssh-key)
--base-url string GitLab base URL for self-managed GitLab, e.g. https://gitlab.example.com; gitlab only (default: none, no config is sent)
--context string saved context name to use (falls back to N8N_CONTEXT, then the saved current context; see 'n8n config context list')
-h, --help help for create
--input string promotion provider JSON file path, or - for stdin (maximum 1 MiB; default: build the document from --name and the other flags)
--key-type string SSH key type for ssh-key auth: ed25519 or rsa (default: the server's ed25519)
--name string provider name, 1 to 128 characters (required without --input)
--output string output format: text or json (JSON is the creation result: provider plus publicKey) (default "text")
--password-stdin read the token for token auth from stdin instead of prompting without echo (default false; required when stdin is not a terminal)
--type string provider type: git or gitlab (default: git)
--url string instance URL override, e.g. https://n8n.example.com (falls back to N8N_URL, then the selected context URL)
--username string Git username for token auth; required for git, ignored by gitlab (default: none)
```

### SEE ALSO
Expand Down
12 changes: 8 additions & 4 deletions docs/n8n_promotion_provider_update.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,18 @@ Update a promotion provider
### Synopsis

Update one promotion provider from strict JSON supplied by --input.
Only the fields present are changed; at least one of name or auth is
required. Auth follows the create shape: ssh-key with an optional key
type, or token with a username and password.
Only the fields present are changed; at least one of name, auth, or
config is required. Auth follows the create shape: ssh-key with an
optional key type, or token with a password (plus username for git
providers). The auth type cannot change. A gitlab provider can change
its base URL with config {"schemaVersion":1,"baseUrl":"..."}; a
different API destination needs auth in the same document.

Replacing the credential affects every connection attached to this
provider, so interactive runs ask for confirmation and non-interactive
runs require --yes. Credentials travel only as --input because secrets
are never flags. Requires gitConnection:update.
are never flags. A 409 means another request changed the provider
first: reload it and retry. Requires gitConnection:update.

```
n8n promotion provider update <provider-id> [flags]
Expand Down
15 changes: 14 additions & 1 deletion internal/cli/cli.go
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,13 @@ const (
ExitError = 1
// ExitDiffError distinguishes a failed comparison from detected differences.
ExitDiffError = 2
ExitCanceled = 130
// ExitPromotionBlocked is a promotion apply the server stopped at
// preflight: the result was printed and nothing was written.
ExitPromotionBlocked = 3
// ExitPromotionSourceChanged is a promotion apply whose branch moved since
// the review: the result was printed and nothing was written.
ExitPromotionSourceChanged = 4
ExitCanceled = 130
)

// Streams are the three standard streams a command tree reads and writes.
Expand Down Expand Up @@ -159,6 +165,13 @@ func Run(ctx context.Context, args []string, opts Options) int {
fmt.Fprintf(opts.Streams.Err, "n8n: %v\n", err)
return ExitError
}
var stoppedApply *promotionApplyStoppedError
if errors.As(err, &stoppedApply) {
// The result and the next step were printed; say why the exit code is
// not zero without the usage hint a real error gets.
fmt.Fprintf(opts.Streams.Err, "n8n: %v\n", err)
return stoppedApply.exitCode()
}
code := report(opts.Streams.Err, err)
if code == ExitError && cmd != nil && cmd.Annotations["diffExitCodes"] == "true" {
return ExitDiffError
Expand Down
Loading
Loading