Deploy Workflow

Push a local .workflow.ts to n8n via n8nac, verify remote state, run a live test.

Model-invocable, with a user gate on activation. The push itself is guarded fail-closed by the PreToolUse hooks (env-gate, push-gate for drift, push-lint-gate) and lands as a draft — the published version stays live. That is why Claude may run this skill when the user asks to deploy in plain words. Activation and the production test are the irreversible part: run step 8 only when the user explicitly asked for it (--activate / --prod or "aktivieren" / "activate" in their request). Otherwise stop after step 7 and ask once whether to activate. (Before 5.6.2 the skill carried disable-model-invocation: true; CLAUDE.md routed plain-language deploy requests to it anyway, so they were refused.)

Steps

1. Resolve workflow

• File path (e.g., workflows/create-lead.workflow.ts) — use directly
• Workflow name (e.g., create lead) — find matching .workflow.ts in workflows/

If $ARGUMENTS is provided, use it. Otherwise, ask the user.

2. Validate before push (mandatory)

npx n8nac skills validate workflows/<name>.workflow.ts --strict --json

If validation fails → stop and report. Do not push with validation errors. For interpreting the error (false-positives, expression vs schema errors, auto-sanitization, bulk fixes), consult the companion n8n-architect skill's Common Mistakes — n8nac's raw validator messages are often terse.

2b. Expect the push-lint gate (runs inside push, fail-closed)

npx n8nac push is wrapped by a PreToolUse hook that compiles the file and refuses the push when (1) a node type or typeVersion is missing on the running instance, (2) a top-level parameter does not exist for the node's typeVersion (n8n ignores it silently), or (3) the design lint fails — no error strategy on a top-level workflow with external calls, continueOnFail without a downstream error check, unwired error output, orphan node, unbalanced expression, availableInMCP not true. Read the BLOCK <rule> <node> <message> lines, fix the .workflow.ts, push again. Rules and fix paths: docs/rules/gates.md. The bypass (N8N_AUTOPILOT_SKIP_LINT=1) exists for the user, not for the agent.

3. Drift check (mandatory — enforced by push-gate hook)

# Extract workflow id from @workflow({ id: '...' }) in the file
WF_ID=$(grep -oE "id:[[:space:]]*['\"][A-Za-z0-9]{10,}['\"]" workflows/<name>.workflow.ts | head -1 | grep -oE "[A-Za-z0-9]{10,}")

# Refresh remote cache, then read sync status
npx n8nac fetch "$WF_ID"
npx n8nac list --search "$WF_ID" --json

Decision table:

If the user has confirmed they want to discard the remote change:

N8N_AUTOPILOT_ALLOW_LOCAL_WINS=1 npx n8nac push workflows/<name>.workflow.ts --verify

4. Push + verify in one call

mcpTrigger check: If the workflow contains mcpTrigger, the PreToolUse hook (ensure-mcp-trigger-setting.sh) auto-fixes availableInMCP: false → true on push and warns when the field is missing entirely — see the warning and patch the source file if needed.

@workflow description field (n8nac 1.7.0+): Set description for better discoverability in n8nac list + n8n UI:

@workflow({ name: "My Workflow", description: "What it does in one sentence", settings: { ... } })

npx n8nac push workflows/<name>.workflow.ts --verify

--verify fetches the workflow after push and validates it against the local schema in one call. If verify fails → re-push.

5. Check credential presence

npx n8nac workflow credential-required <workflowId>

• Exit 0: all present → proceed to test
• Exit 1: credentials missing → report which credentials are needed, skip live test

6. Trigger classification + payload inference

npx n8nac test-plan <workflowId> --json

Extract triggerType, testable, suggestedPayload.

7. Live test (test URL — no activation needed)

n8nac test calls the test URL (/webhook-test/) by default.

npx n8nac test <workflowId> --data '<suggestedPayload from step 6>'
# For GET/HEAD webhooks (workflow reads $json.query):
npx n8nac test <workflowId> --query '<suggestedPayload>'

• Class A error (exit 0): missing credentials / model → report to user, do not iterate.
• Class B error (exit 1): wiring error → fix → re-validate → re-push (--verify) → re-test (max 3 cycles).

8. Production test (optional, only with --activate)

Only if the user explicitly asked for activation (--activate, or said so in their request). If they did not, do not activate — ask once after step 7 whether they want it.

If the user passes --activate:

1. Activate the workflow:

   npx n8nac workflow activate <workflowId>

2. Production test:

   npx n8nac test <workflowId> --prod --data '<payload>'

3. On success → workflow stays active.
4. On failure → deactivate via npx n8nac workflow deactivate <workflowId>, report error.

9. mcpTrigger publish notice (manual)

After a successful push, check whether the workflow uses mcpTrigger:

grep -l "mcpTrigger\|n8n-nodes-langchain.mcpTrigger" workflows/<name>.workflow.ts

If yes, resolve the user-facing URL via the CLI (do not string-concat <host>/workflow/<id>):

npx n8nac workflow present <workflowId> --json

Surface a prominent notice using that URL:

⚠️  MANUAL PUBLISH REQUIRED — mcpTrigger detected

The MCP endpoint will return 404 until the workflow is published.

Open n8n UI:  <url from `n8nac workflow present`>
Click:        "Publish" button

n8nac push writes a new draft. The previously-published version stays live, but its MCP endpoint may diverge from the new draft. Each push to an mcpTrigger workflow requires a fresh UI publish — n8nac cannot publish on your behalf.

Safety

• Always validate before pushing.
• Workflows deploy as inactive by default. n8nac test uses the test URL, no activation needed.
• --activate + --prod tests against the production webhook URL — use with caution.
• Never activate or run the production test without an explicit user request — see the gate note at the top.