CICD-First-Deploy

A specialized sub-workflow that handles the initial deployment of n8n workflows from GitHub to production environments. This workflow creates new workflows in the target n8n instance when they don't exist yet, performing credential mapping and payload preparation to ensure successful deployment.

Purpose

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

This workflow serves as a critical component in a CI/CD pipeline for n8n workflow deployment. It specifically handles the "first deploy" scenario where a workflow exists in GitHub but has never been deployed to the target n8n environment. The workflow ensures that all credentials are properly mapped from development names to production IDs before creating the new workflow.

How It Works

1. Receives deployment context - The workflow is triggered by another workflow (typically CICD-Sync-Deploy) with all necessary deployment information
2. Processes credential mappings - Examines every node in the GitHub workflow JSON and maps credential names to production credential IDs using a lookup table
3. Validates credential availability - Blocks deployment if any required credentials cannot be found in the production environment
4. Prepares deployment payload - Strips non-POSTable fields and ensures the workflow JSON is ready for API submission
5. Creates new workflow - Makes a POST request to the n8n API to create the workflow (inactive by default)
6. Returns deployment result - Provides the new workflow ID and deployment status back to the calling workflow

Workflow Diagram

graph TD
    A[When Executed by Another Workflow] --> B[Prepare First-Deploy Payload]
    B --> C[POST New Workflow]
    C --> D[Return Result]

Trigger

Execute Workflow Trigger - This workflow is designed to be called by another workflow (specifically CICD-Sync-Deploy) when a first deployment is needed. It uses passthrough input to receive all necessary deployment context.

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives deployment context from parent workflow
Code	Prepare First-Deploy Payload	Maps credentials and prepares workflow JSON for deployment
HTTP Request	POST New Workflow	Creates the new workflow in target n8n instance
Code	Return Result	Formats and returns deployment results
Sticky Note	[CI/CD] First Deploy	Documentation and workflow description

External Services & Credentials Required

n8n API Access

• API Key: Production n8n instance API key with workflow creation permissions
• Base URL: Target n8n instance URL for API calls

Required Permissions

• Workflow creation rights in the target n8n environment
• Access to credential information for mapping

Environment Variables

This workflow expects the following data to be passed from the calling workflow:

• env_name - Name of the target environment
• env_url - Base URL of the target n8n instance
• api_key - API key for the target n8n instance
• github_workflow_json - Complete workflow JSON from GitHub
• credential_lookup - Mapping table of credential names to production IDs
• workflow_name - Name of the workflow being deployed

Data Flow

Input

{
  "env_name": "production",
  "env_url": "https://n8n.example.com",
  "api_key": "n8n_api_key_...",
  "github_workflow_json": { /* complete workflow definition */ },
  "credential_lookup": {
    "credential_name": { "id": "prod_credential_id" }
  },
  "workflow_name": "My Workflow"
}

Output

{
  "success": true,
  "new_workflow_id": "abc123",
  "workflow_name": "My Workflow",
  "env_name": "production"
}

Error Handling

The workflow implements several error handling mechanisms:

• Credential Validation: Throws an error if any required credentials cannot be mapped to production IDs
• HTTP Request Retry: The POST request has retry logic (2 attempts, 3-second delay) for transient failures
• Workflow Termination: Set to stop the entire workflow on errors to prevent partial deployments

Common error scenarios: - Missing credentials in the production environment - Invalid API keys or insufficient permissions - Network connectivity issues to the target n8n instance - Malformed workflow JSON

Known Limitations

• All credentials are treated as new during first deploy, requiring complete credential mapping
• Workflows are created in inactive state by default
• No rollback mechanism if deployment partially succeeds
• Requires manual credential setup in target environment before deployment

Related Workflows

• CICD-Sync-Deploy: Parent workflow that calls this sub-workflow when sync_status == first_deploy

Setup Instructions

1. Import the workflow into your n8n instance
2. Configure caller policy to allow execution from same-owner workflows only
3. Ensure API access to target n8n environments with appropriate permissions
4. Set up credential mapping system in your CI/CD pipeline
5. Test with a simple workflow before deploying complex automations
6. Configure error notifications in the parent workflow to handle deployment failures

Prerequisites

• n8n instance with API access enabled
• Credential management system for mapping dev/prod credential names
• Parent CI/CD workflow (like CICD-Sync-Deploy) to orchestrate deployments

Security Considerations

• API keys should be stored securely and rotated regularly
• Credential lookup tables should not contain sensitive information
• Consider implementing approval workflows for production deployments