CICD-Redeploy-Ritual

This workflow is a specialized CI/CD sub-workflow that safely redeploys n8n workflows by creating verified backups before updating live instances. It fetches the current live workflow, creates a backup clone, merges GitHub source code with existing credentials, and updates the production workflow while maintaining rollback capability.

Purpose

No business context provided yet — add a context.md to enrich this documentation.

This workflow serves as a critical component in automated deployment pipelines, ensuring that workflow updates can be safely applied to production environments with automatic backup creation and verification. It's designed to be called by other CI/CD workflows when deploying changes from version control to live n8n instances.

How It Works

1. Fetch Live Workflow: Retrieves the current production workflow JSON from the n8n API using the provided workflow ID
2. Merge Context: Combines the caller's context with the fetched live workflow data for processing
3. Create Backup Clone: Builds a backup payload by stripping API-incompatible fields and creates a timestamped backup with "UNVERIFIED" status
4. Post Backup: Creates the backup workflow in n8n and captures its ID for later reference
5. Credential Merge: Intelligently merges GitHub source code with existing credentials - keeping live credentials for existing nodes and looking up new credentials by name
6. Update Live Workflow: Applies the merged changes to the production workflow using a PUT request
7. Verify Deployment: Fetches the updated workflow to confirm the changes were applied correctly
8. Mark Backup as Verified: Updates the backup workflow name from "UNVERIFIED" to "ROLLBACK-OK" to indicate it's safe for rollback
9. Return Results: Provides deployment status, backup information, and verification details

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[GET Live Workflow]
    B --> C[Merge Live Into Context]
    C --> D[Build Backup Clone Payload]
    D --> E[POST Clone - Backup]
    E --> F[Capture Backup ID]
    F --> G[Credential Merge - Rule 2]
    G --> H[PUT to Canonical liveId]
    H --> I[GET-after-PUT Verify]
    I --> J[Build Rename Payload]
    J --> K[PUT Backup ROLLBACK-OK]
    K --> L[Return Result]

Trigger

• Execute Workflow Trigger: Called by other workflows (typically CICD-Sync-Deploy) with passthrough input containing deployment context and configuration

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives deployment context from calling workflow
HTTP Request	GET Live Workflow	Fetches current production workflow from n8n API
Code	Merge Live Into Context	Combines caller context with live workflow data
Code	Build Backup Clone Payload	Prepares backup workflow with stripped fields and timestamp
HTTP Request	POST Clone (Backup)	Creates backup workflow in n8n
Code	Capture Backup ID	Extracts and stores backup workflow ID
Code	Credential Merge (Rule 2)	Merges GitHub source with existing credentials
HTTP Request	PUT to Canonical liveId	Updates the live production workflow
HTTP Request	GET-after-PUT Verify	Verifies deployment was successful
Code	Build Rename Payload	Prepares backup rename from UNVERIFIED to ROLLBACK-OK
HTTP Request	PUT Backup ROLLBACK-OK	Updates backup status to verified
Code	Return Result	Formats final deployment results
Sticky Note	[CI/CD] Redeploy Ritual	Documentation and workflow notes

External Services & Credentials Required

n8n API Access

• X-N8N-API-KEY: API key for the target n8n instance with workflow read/write permissions

Required Permissions

• Read access to existing workflows
• Create new workflows (for backups)
• Update existing workflows
• Access to credential lookup data

Environment Variables

The workflow expects these variables in the input context:

• env_name: Environment identifier (e.g., "prod", "staging")
• env_url: Base URL of the target n8n instance
• api_key: n8n API key for authentication
• live_workflow_id: ID of the workflow to be updated
• github_workflow_json: Source workflow JSON from GitHub
• source_sha: Git commit SHA for tracking
• credential_lookup: Mapping of credential names to production IDs
• workflow_name: Human-readable workflow name

Data Flow

Input

{
  "env_name": "prod",
  "env_url": "https://n8n.example.com",
  "api_key": "n8n_api_key_here",
  "live_workflow_id": "workflow_id",
  "github_workflow_json": { /* workflow definition */ },
  "source_sha": "commit_sha",
  "credential_lookup": { /* credential mappings */ },
  "workflow_name": "Workflow Name"
}

Output

{
  "success": true,
  "workflow_id": "live_workflow_id",
  "workflow_name": "Workflow Name",
  "env_name": "prod",
  "backup_workflow_id": "backup_id",
  "backup_label": "[BACKUP timestamp · sha7 · ROLLBACK-OK · VERIFIED] Workflow Name",
  "rollback_ok": true,
  "source_sha": "commit_sha",
  "verified_node_count": 12
}

Error Handling

• Credential Lookup Failures: Throws descriptive errors when new nodes require credentials not found in the lookup table
• API Request Retries: HTTP requests include retry logic with exponential backoff
• Graceful Degradation: Backup rename failures don't block the main deployment
• Field Validation: Automatically strips API-incompatible fields to prevent 400 errors

Known Limitations

• Requires existing credential lookup data for new nodes
• Cannot create new credentials automatically
• Backup workflows are created as inactive by default
• Some n8n API fields are read-only and must be stripped during updates

Related Workflows

• CICD-Sync-Deploy: Primary caller that orchestrates the deployment process
• CICD-Cron-Backup: Scheduled backup workflow for regular maintenance

Setup Instructions

1. Import Workflow: Import the JSON into your n8n instance
2. Configure API Access: Ensure the calling workflow has valid n8n API credentials
3. Set Up Credential Lookup: Prepare a mapping of credential names to production IDs
4. Test Deployment: Run a test deployment with a non-critical workflow
5. Integrate with CI/CD: Connect to your main deployment workflow as a sub-workflow
6. Monitor Backups: Regularly review and clean up old backup workflows

Required Input Contract

Ensure calling workflows provide all required fields in the input context, particularly the credential lookup mapping for proper credential resolution during deployments.