CICD-Redeploy-Ritual

A sub-workflow that safely redeploys n8n workflows by creating a backup clone, merging credentials intelligently, and updating the live workflow with new code from GitHub while preserving production credentials.

Purpose

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

This workflow serves as a critical safety mechanism in CI/CD deployments, ensuring that workflow updates don't break production systems by losing credential configurations. It's designed to be called by other CI/CD workflows when they detect that a workflow needs to be redeployed due to drift or updates.

How It Works

1. Backup Creation: Takes the current live workflow and creates a safety backup with a timestamped name including the source commit SHA
2. Credential Intelligence: Analyzes both the live workflow and incoming GitHub version to preserve existing credentials while properly mapping new ones
3. Safe Deployment: Updates the live workflow with the new code while maintaining all credential references
4. Verification: Confirms the deployment succeeded by retrieving and validating the updated workflow
5. Result Reporting: Returns deployment status and backup information to the calling workflow

The workflow implements a "credential merge rule" where existing nodes keep their live credentials unchanged, while new nodes get their credentials mapped from a provided lookup table. If any required credentials are missing from the lookup, the deployment is blocked to prevent broken workflows.

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Build Backup Clone Payload]
    B --> C[POST Clone - Backup]
    C --> D[Capture Backup ID]
    D --> E[Credential Merge - Rule 2]
    E --> F[PUT to Canonical liveId]
    F --> G[GET-after-PUT Verify]
    G --> H[Return Result]

Trigger

Execute Workflow Trigger: This workflow is designed to be called by other workflows (specifically CICD-Sync-Deploy) when sync_status == drift_redeploy. It accepts input data through the "passthrough" mode.

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input from calling workflow
Code	Build Backup Clone Payload	Creates backup workflow payload with timestamp and SHA
HTTP Request	POST Clone (Backup)	Creates the backup workflow in n8n
Code	Capture Backup ID	Extracts backup workflow ID from response
Code	Credential Merge (Rule 2)	Intelligently merges credentials between live and GitHub versions
HTTP Request	PUT to Canonical liveId	Updates the live workflow with merged content
HTTP Request	GET-after-PUT Verify	Verifies the deployment succeeded
Code	Return Result	Formats final response with deployment status
Sticky Note	[CI/CD] Redeploy Ritual	Documentation and workflow overview

External Services & Credentials Required

n8n API: Requires API access to the target n8n instance for workflow management operations.

Required Credentials

• n8n API Key: Must have permissions to create, read, and update workflows
• Credential Lookup Table: A mapping of credential names to production credential IDs

Environment Variables

The workflow expects these inputs from the calling workflow:

• env_name: Target environment name
• env_url: n8n instance URL
• api_key: n8n API key for authentication
• live_workflow_id: ID of the workflow to update
• live_workflow_json: Current live workflow definition
• github_workflow_json: New workflow definition 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: Workflow deployment context including live and GitHub workflow definitions, credentials mapping, and environment details.

Output: Deployment result object containing: - success: Boolean deployment status - workflow_id: ID of the updated workflow - workflow_name: Name of the workflow - env_name: Target environment - backup_workflow_id: ID of the created backup - backup_label: Full name of the backup workflow - source_sha: Git commit SHA - verified_node_count: Number of nodes in deployed workflow

Error Handling

• Credential Lookup Failures: If new nodes reference credentials not found in the lookup table, the workflow throws an error and blocks deployment
• HTTP Request Retries: POST and PUT operations have retry logic (2-3 attempts with delays)
• Verification Continuation: The GET-after-PUT verification continues on error to allow partial success reporting
• Workflow Stoppage: Critical failures in backup creation or deployment stop the entire workflow

Known Limitations

• Backup workflows are labeled as "UNVERIFIED" and require manual verification before being considered safe rollback points
• The workflow strips certain n8n metadata fields that may contain useful information
• Credential mapping relies on exact name matches and doesn't handle credential type changes
• No automatic rollback mechanism if deployment verification fails

Related Workflows

• CICD-Sync-Deploy: The parent workflow that calls this redeploy ritual
• Backup-Verifier: Future workflow for validating backup integrity (mentioned as deferred)

Setup Instructions

1. Import Workflow: Import this JSON into your n8n instance
2. Configure API Access: Ensure the calling workflow has valid n8n API credentials
3. Set Permissions: Configure the workflow with callerPolicy: "workflowsFromSameOwner" for security
4. Prepare Credential Mapping: Create a credential lookup table mapping credential names to production IDs
5. Test Integration: Verify the workflow works with your CI/CD pipeline by testing with a non-critical workflow first
6. Monitor Executions: Enable execution logging to track deployment history and troubleshoot issues

Important: This workflow should only be called by trusted CI/CD workflows as it has the power to modify production workflows and create backups.