Building a CI/CD Pipeline Trigger with n8n

Introduction

#

Triggering CI/CD pipelines from external events is a common DevOps requirement. Whether you need to deploy after a Slack command, trigger builds from a custom dashboard, or orchestrate multi-repo deployments, n8n provides a flexible solution.

This tutorial shows you how to build a workflow that triggers GitHub Actions or GitLab CI pipelines from any webhook source.

Prerequisites

#

Before starting, ensure you have:

• An n8n instance (self-hosted or n8n Cloud)
• GitHub Personal Access Token with repo and workflow permissions
• Or GitLab API token with api scope
• A repository with existing CI/CD workflows

Workflow Overview

#

The workflow accepts webhook requests and routes them to either GitHub Actions or GitLab CI based on the platform parameter:

1
2

Webhook → Route by Platform → GitHub Actions API
                            → GitLab CI API

Step-by-Step Setup

#

Step 1: Create the Webhook Trigger

#

1. Add a Webhook node to your canvas
2. Set HTTP Method to POST
3. Set the path to trigger-pipeline
4. Set Response Mode to Respond to Webhook

The webhook will accept JSON payloads like:

1
2
3
4
5
6

{
  "platform": "github",
  "owner": "your-username",
  "repo": "your-repo",
  "workflow": "deploy.yml"
}

Step 2: Add Platform Routing

#

1. Add a Switch node after the webhook
2. Create conditions based on {{ $json.platform }}:
   • Route 1: github → GitHub Actions node
   • Route 2: gitlab → GitLab CI node

Step 3: Configure GitHub Actions Trigger

#

For GitHub, use an HTTP Request node:

URL:

1

https://api.github.com/repos/{{ $json.owner }}/{{ $json.repo }}/actions/workflows/{{ $json.workflow }}/dispatches

Method: POST

Headers:

1
2

Authorization: Bearer YOUR_GITHUB_TOKEN
Accept: application/vnd.github.v3+json

Body:

1
2
3

{
  "ref": "main"
}

Step 4: Configure GitLab CI Trigger

#

For GitLab, use an HTTP Request node:

URL:

1

https://gitlab.com/api/v4/projects/{{ $json.project_id }}/trigger/pipeline

Method: POST

Body (form-data):

1
2

ref: main
token: YOUR_TRIGGER_TOKEN

Step 5: Add Response Handler

#

Add a Respond to Webhook node at the end:

1
2
3
4
5

{
  "status": "triggered",
  "platform": "{{ $json.platform }}",
  "timestamp": "{{ $now }}"
}

Testing the Workflow

#

Test with cURL

#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

# Trigger GitHub Actions
curl -X POST https://your-n8n-instance/webhook/trigger-pipeline \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "github",
    "owner": "your-username",
    "repo": "your-repo",
    "workflow": "deploy.yml"
  }'

# Trigger GitLab CI
curl -X POST https://your-n8n-instance/webhook/trigger-pipeline \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "gitlab",
    "project_id": "12345678",
    "trigger_token": "your-trigger-token"
  }'

Verify in CI/CD Platform

#

Check your GitHub Actions or GitLab CI dashboard to confirm the pipeline was triggered.

Customization Options

#

Add Authentication

#

Secure your webhook with a secret token:

1
2
3
4

// In a Code node after the webhook
if ($json.headers['x-webhook-secret'] !== 'your-secret') {
  throw new Error('Unauthorized');
}

Support Multiple Branches

#

Modify the payload to accept a branch parameter:

1
2
3
4
5
6
7

{
  "platform": "github",
  "owner": "your-username",
  "repo": "your-repo",
  "workflow": "deploy.yml",
  "branch": "develop"
}

Add Slack Notifications

#

Chain a Slack node to notify your team when pipelines are triggered:

1

Webhook → Route → Trigger API → Slack Notification → Respond

Troubleshooting

#

GitHub Returns 404

#

• Verify the workflow file exists in .github/workflows/
• Ensure your token has repo and workflow permissions
• Check that workflow_dispatch trigger is defined in the workflow

GitLab Returns 401

#

• Verify your trigger token is valid
• Check the project ID is correct
• Ensure the token has pipeline trigger permissions

Webhook Timeout

#

• Increase n8n’s webhook timeout in settings
• Use async execution for long-running triggers
• Return immediately and process in background

Security Best Practices

#

1. Use environment variables for tokens - never hardcode
2. Validate webhook payloads before processing
3. Implement rate limiting to prevent abuse
4. Log all trigger events for audit trails
5. Use HTTPS for all webhook endpoints

Conclusion

#

You now have a flexible CI/CD trigger that can be called from anywhere - Slack bots, custom dashboards, monitoring alerts, or other n8n workflows. This centralizes your deployment orchestration and makes it easy to add new triggers without modifying your CI/CD configurations.

Download the complete workflow from our n8n Workflow Gallery and customize it for your needs.