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 target n8n instances when they don't already exist, handling credential mapping and API compatibility issues.

Purpose

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

This workflow serves as a critical component in CI/CD automation for n8n workflow deployment. It's specifically designed to handle "first deploy" scenarios where a workflow exists in GitHub source control but hasn't been created in the target n8n environment yet. The workflow ensures proper credential mapping and handles n8n API compatibility requirements during the creation process.

How It Works

1. Receives deployment request - Another workflow triggers this sub-workflow with deployment parameters including the GitHub workflow JSON and credential mappings
2. Processes credential references - Walks through all nodes in the workflow and maps credential names to production credential IDs using the provided lookup table
3. Sanitizes workflow data - Removes fields that aren't allowed in n8n's POST API (like active, description: null, and unsupported settings)
4. Creates new workflow - Makes a POST request to the target n8n instance's API to create the workflow (created as inactive by default)
5. Returns success response - Provides the new workflow ID and deployment details 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 other workflows (specifically CICD-Sync-Deploy) and receives data through passthrough mode.

Nodes Used

Node Type	Node Name	Purpose
Execute Workflow Trigger	When Executed by Another Workflow	Receives input from parent workflow
Code	Prepare First-Deploy Payload	Maps credentials and sanitizes workflow JSON for n8n API
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 overview

External Services & Credentials Required

n8n API Access

• Service: Target n8n instance API
• Authentication: API Key (X-N8N-API-KEY header)
• Endpoint: /api/v1/workflows (POST)
• Permissions: Workflow creation rights

Required Credentials

This workflow doesn't directly use stored credentials but processes credential mappings for the workflows being deployed. The calling workflow must provide a credential lookup table mapping credential names to production IDs.

Environment Variables

This workflow expects the following data 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 - The workflow JSON from GitHub
• credential_lookup - Object mapping 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": { /* full workflow object */ },
  "credential_lookup": {
    "credential_name": { "id": "prod_credential_id" }
  },
  "workflow_name": "My Workflow"
}

Output

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

Error Handling

The workflow includes several error handling mechanisms:

• Credential validation - Throws detailed error if any required credentials can't be mapped to production IDs
• HTTP retry logic - POST request retries up to 2 times with 3-second delays
• Workflow termination - Stops execution on HTTP errors to prevent partial deployments
• Input validation - Validates that all required input parameters are present

Common error scenarios: - Missing credential mappings result in detailed error messages listing which credentials need to be configured - API authentication failures stop the workflow immediately - Network timeouts trigger automatic retries

Known Limitations

• Workflows are created in inactive state by default - activation must be handled separately
• All credentials must be pre-mapped in the credential lookup table
• Some n8n settings fields are not supported and will be filtered out
• The workflow assumes the target n8n instance supports the v1 API format

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 API access - Ensure the calling workflow has valid n8n API credentials for target environments
3. Set up credential mapping - Create a system to map development credential names to production credential IDs
4. Test the integration - Verify the workflow works with your CICD-Sync-Deploy parent workflow
5. Monitor executions - Check that workflows are created successfully and credential mappings work correctly

Prerequisites

• n8n instance with API access enabled
• Valid API keys for target environments
• Credential management system for mapping dev/prod credentials
• Parent CI/CD workflow configured to call this sub-workflow

Configuration Notes

• The workflow uses Africa/Johannesburg timezone by default
• Execution data is saved for both successful and failed runs
• Only workflows from the same owner can call this sub-workflow (security setting)