Skip to main content

n8n Workflow CI/CD

This runbook documents the CI/CD pipeline for n8n workflow management, enabling version control and automated deployment of workflows from development to production.

Architecture​

┌──────────────────┐     ┌─────────────────┐     ┌──────────────────┐
│   Dev n8n        │     │    GitLab       │     │   Prod n8n       │
│   (odin)         │────▶│    Repository   │────▶│   (AWS)          │
│                  │     │                 │     │                  │
│ • Build/test     │     │ • Version ctrl  │     │ • Production     │
│ • Export JSON    │     │ • CI validation │     │ • Auto-deploy    │
│ n8n.ravenhelm.dev│     │ • CD pipeline   │     │ • Auto-activate  │
└──────────────────┘     └─────────────────┘     └──────────────────┘

Environments​

EnvironmentLocationURLPurpose
DevelopmentOdinn8n.ravenhelm.devBuild and test workflows
ProductionAWSTBDProduction automation

Repository​

  • Location: https://gitlab.ravenhelm.dev/ravenmask/n8n-workflows
  • Structure:
    • workflows/active/ - Production-ready workflows (JSON)
    • workflows/staging/ - Work-in-progress
    • credentials/credential-map.json - Credential ID mapping
    • scripts/export.sh - Export from dev n8n
    • scripts/deploy-to-prod.sh - Deploy to production
    • .gitlab-ci.yml - CI/CD pipeline

GitLab Runner​

A dedicated GitLab runner is configured on odin:

  • Name: odin-runner
  • Executor: Docker
  • Network: ravenhelm_net (internal)
  • Config: /Users/ravenhelm/ravenhelm/data/gitlab-runner/config.toml

Development Workflow​

1. Develop Workflow​

Create or modify workflows in the dev n8n UI at https://n8n.ravenhelm.dev

2. Export Workflows​

cd /tmp/n8n-workflows
./scripts/export.sh

This exports all workflows to workflows/active/ as JSON files.

3. Commit and Push​

git add -A
git commit -m "Add/update workflow: <workflow-name>"
git push origin main

4. CI Pipeline​

The pipeline automatically:

  1. Validate stage: Checks JSON syntax and required fields
  2. Deploy stage: (Manual trigger) Deploys to production

5. Manual Deploy​

Go to GitLab > CI/CD > Pipelines and click "Play" on the deploy job.

Or via API:

GITLAB_TOKEN="$(op item get 'GitLab MCP PAT' --vault ravenmask --fields credential --reveal)"
curl -X POST -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
  "https://gitlab.ravenhelm.dev/api/v4/projects/9/jobs/<job_id>/play"

Credential Management​

Workflows contain credential IDs, not secrets. To deploy to a new environment:

  1. Create matching credentials in the target n8n instance
  2. Update credentials/credential-map.json with ID mappings
  3. If IDs differ, the deploy script can transform them

Rollback​

To rollback to a previous version:

git revert HEAD
git push origin main
# Pipeline redeploys the previous version

Troubleshooting​

Pipeline fails at "Getting source"​

The runner container can't reach GitLab. Verify:

  • clone_url = "http://gitlab:80" in runner config
  • Runner is on ravenhelm_net network

Workflow validation fails​

Check the job logs for JSON syntax errors or missing required fields.

Deploy fails to connect​

Verify N8N_PROD_URL and N8N_PROD_API_KEY are set in GitLab CI/CD variables.