English | 繁體中文 | 简体中文

A CLI tool and CI/CD plugin for triggering Jenkins jobs. Works with GitHub Actions, GitLab CI, Gitea Action, and any platform that supports Docker containers or shell commands.

In modern enterprise environments, teams often adopt different CI/CD platforms based on their specific needs, project requirements, or historical decisions. It's common to find:

• Multiple CI platforms coexisting: Some teams use Jenkins for its extensive plugin ecosystem, while others prefer GitHub Actions or GitLab CI for their simplicity and container-native approach.
• Legacy systems integration: Organizations with established Jenkins pipelines need to integrate with newer CI/CD workflows without rewriting everything.
• Cross-team collaboration: Different departments may standardize on different tools, requiring seamless communication between platforms.

drone-jenkins bridges this gap by allowing CI/CD pipelines to trigger Jenkins jobs as part of their workflow. It works seamlessly with GitHub Actions, GitLab CI, Gitea Action, and any CI platform that supports Docker containers or shell commands.

This enables:

• Unified deployment pipelines: Trigger existing Jenkins deployment jobs from any CI platform without migration
• Gradual migration: Teams can incrementally move to modern CI platforms while still leveraging Jenkins jobs
• Best of both worlds: Use GitHub Actions or GitLab CI for modern containerized builds and Jenkins for specialized tasks with specific plugins
• Centralized orchestration: Coordinate builds across multiple CI systems from a single pipeline
• Flexibility: Available as a CLI binary or Docker image—use it however fits your workflow

Whether you're managing a hybrid CI/CD environment or orchestrating complex multi-platform deployments, drone-jenkins provides the connectivity you need.

• drone-jenkins
  • Why drone-jenkins?
  • Table of Contents
  • Features
  • Prerequisites
  • Installation
    • Download Binary
    • Build from Source
    • Docker Image
  • Configuration
    • Jenkins Server Setup
    • Authentication
      • Understanding Jenkins Authentication
      • CSRF Protection Notice
    • Parameters Reference
  • Usage
    • Command Line
    • Docker
  • Troubleshooting
    • Error: 403 No valid crumb was included in the request
    • Error: 401 Unauthorized
    • Remote Token Not Working
  • Development
    • Building
    • Testing
  • License
  • Contributing

• Trigger single or multiple Jenkins jobs
• Support for Jenkins build parameters
• Multiple authentication methods (API token or remote trigger token)
• Wait for job completion with configurable polling and timeout
• Debug mode with detailed parameter information and secure token masking
• SSL/TLS support with custom CA certificates (PEM content, file path, or URL)
• Cross-platform support (Linux, macOS, Windows)
• Available as CLI binary or Docker image

• Jenkins server (version 2.0 or later recommended)
• Jenkins API token or remote trigger token for authentication
• For Jenkins setup, Docker is recommended but not required

Pre-compiled binaries are available from the release page for:

• Linux: amd64, 386
• macOS (Darwin): amd64, 386
• Windows: amd64, 386

With Go installed, you can also install directly:

go install github.com/appleboy/drone-jenkins@latest

Clone the repository and build:

git clone https://github.com/appleboy/drone-jenkins.git
cd drone-jenkins
make build

Build the Docker image:

make docker

Or pull the pre-built image:

docker pull ghcr.io/appleboy/drone-jenkins

Set up a Jenkins server using Docker:

docker run -d -v jenkins_home:/var/jenkins_home -p 8080:8080 -p 50000:50000 --restart=on-failure jenkins/jenkins:slim

Jenkins supports multiple authentication methods for triggering builds. This tool supports two approaches:

1. API Token Authentication (Recommended)

Use Jenkins user credentials with an API token. This method:

• ✅ Works with all Jenkins configurations
• ✅ Supports CSRF protection (enabled by default in modern Jenkins)
• ✅ Supports wait mode to monitor build completion
• ✅ Provides full access to Jenkins API features

To create an API token:

1. Log into Jenkins
2. Click on your username (top right)
3. Select "Security"
4. Under "API Token", click "Add new Token"
5. Give it a name and click "Generate"
6. Copy the generated token

2. Remote Trigger Token Authentication

Use a remote trigger token configured in your Jenkins job. Important limitations:

• ⚠️ Does not work with Jenkins CSRF protection enabled (default in modern Jenkins)
• ⚠️ Requires anonymous users to have read access to the job, OR
• ⚠️ Must be combined with API token authentication (see Combined Authentication below)

3. Combined Authentication (Recommended for Remote Tokens)

Use both API token and remote trigger token together:

• ✅ Works with CSRF protection enabled
• ✅ Provides double authentication security
• ✅ Supports all features including wait mode

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user YOUR_USERNAME \
  --token YOUR_API_TOKEN \
  --remote-token YOUR_REMOTE_TOKEN \
  --job my-jenkins-job

Modern Jenkins installations have CSRF protection enabled by default. If you encounter errors like:

Error 403 No valid crumb was included in the request

This means your Jenkins has CSRF protection enabled. You must use API token authentication (option 1 or 3 above). Remote trigger token alone will not work.

For more information about Jenkins CSRF protection, see the official Jenkins documentation.

Authentication Requirements:

For Jenkins with CSRF protection enabled (default in modern Jenkins):

• Required: user + token (API token authentication)
• Optional: remote-token (for additional security)

For Jenkins with CSRF protection disabled (not recommended):

• Option 1: user + token (API token authentication)
• Option 2: remote-token only (requires anonymous read access to job)

Important: If you encounter "403 No valid crumb" errors, you must use API token authentication (user + token).

Parameters Format: The parameters field accepts a multi-line string where each line contains one key=value pair:

• Each parameter should be on a separate line
• Format: KEY=VALUE (one per line)
• Empty lines are automatically ignored
• Whitespace-only lines are skipped
• Keys are trimmed of surrounding whitespace
• Values preserve intentional spaces
• Values can contain = signs (everything after the first = is treated as the value)

Single job:

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job drone-jenkins-plugin

Multiple jobs:

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job drone-jenkins-plugin-1 \
  --job drone-jenkins-plugin-2

With build parameters:

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --parameters $'ENVIRONMENT=production\nVERSION=1.0.0'

Or using environment variable:

export JENKINS_PARAMETERS="ENVIRONMENT=production
VERSION=1.0.0
BRANCH=main"

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job

Using combined authentication (API token + remote token - Recommended):

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --remote-token REMOTE_TOKEN_HERE \
  --job my-jenkins-job

Using remote token only (only works without CSRF protection):

# Note: This will fail if Jenkins has CSRF protection enabled
# You will get "403 No valid crumb" error
drone-jenkins \
  --host http://jenkins.example.com/ \
  --remote-token REMOTE_TOKEN_HERE \
  --job my-jenkins-job

Wait for job completion:

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --wait \
  --poll-interval 15s \
  --timeout 1h

With debug mode:

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --debug

With custom CA certificate:

# Using a file path
drone-jenkins \
  --host https://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --ca-cert /path/to/ca.pem

# Using a URL
drone-jenkins \
  --host https://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --ca-cert https://example.com/ca-bundle.crt

Single job:

docker run --rm \
  -e JENKINS_URL=http://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_JOB=drone-jenkins-plugin \
  ghcr.io/appleboy/drone-jenkins

Multiple jobs:

docker run --rm \
  -e JENKINS_URL=http://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_JOB=drone-jenkins-plugin-1,drone-jenkins-plugin-2 \
  ghcr.io/appleboy/drone-jenkins

With build parameters:

docker run --rm \
  -e JENKINS_URL=http://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_JOB=my-jenkins-job \
  -e JENKINS_PARAMETERS=$'ENVIRONMENT=production\nVERSION=1.0.0\nBRANCH=main' \
  ghcr.io/appleboy/drone-jenkins

With combined authentication (API token + remote token):

docker run --rm \
  -e JENKINS_URL=http://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_REMOTE_TOKEN=your_remote_token \
  -e JENKINS_JOB=my-jenkins-job \
  ghcr.io/appleboy/drone-jenkins

Wait for job completion:

docker run --rm \
  -e JENKINS_URL=http://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_JOB=my-jenkins-job \
  -e JENKINS_WAIT=true \
  -e JENKINS_POLL_INTERVAL=15s \
  -e JENKINS_TIMEOUT=1h \
  ghcr.io/appleboy/drone-jenkins

With debug mode:

docker run --rm \
  -e JENKINS_URL=http://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_JOB=my-jenkins-job \
  -e JENKINS_DEBUG=true \
  ghcr.io/appleboy/drone-jenkins

With custom CA certificate:

# Using a mounted certificate file
docker run --rm \
  -v /path/to/ca.pem:/ca.pem:ro \
  -e JENKINS_URL=https://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_JOB=my-jenkins-job \
  -e JENKINS_CA_CERT=/ca.pem \
  ghcr.io/appleboy/drone-jenkins

# Using a URL
docker run --rm \
  -e JENKINS_URL=https://jenkins.example.com/ \
  -e JENKINS_USER=appleboy \
  -e JENKINS_TOKEN=xxxxxxx \
  -e JENKINS_JOB=my-jenkins-job \
  -e JENKINS_CA_CERT=https://example.com/ca-bundle.crt \
  ghcr.io/appleboy/drone-jenkins

For more detailed examples and advanced configurations, see DOCS.md.

Cause: Your Jenkins server has CSRF protection enabled (this is the default in modern Jenkins). Learn more at the Jenkins CSRF Protection documentation.

Solution: Use API token authentication instead of remote token only:

# ❌ This will fail with CSRF protection enabled
drone-jenkins \
  --host http://jenkins.example.com/ \
  --remote-token YOUR_REMOTE_TOKEN \
  --job my-jenkins-job

# ✅ Use this instead
drone-jenkins \
  --host http://jenkins.example.com/ \
  --user YOUR_USERNAME \
  --token YOUR_API_TOKEN \
  --job my-jenkins-job

# ✅ Or combine both for additional security
drone-jenkins \
  --host http://jenkins.example.com/ \
  --user YOUR_USERNAME \
  --token YOUR_API_TOKEN \
  --remote-token YOUR_REMOTE_TOKEN \
  --job my-jenkins-job

Cause: Invalid credentials or incorrect authentication method.

Solutions:

1. Verify your username and API token are correct
2. Ensure you're using an API token, not your Jenkins password
3. Check if you have permission to trigger the job
4. Make sure both --user and --token are provided together

Cause: Remote trigger tokens alone only work in specific scenarios:

• Jenkins has CSRF protection disabled (not recommended), AND
• Anonymous users have read access to the job

Solution: Use combined authentication (API token + remote token) as shown in the examples above.

Build the binary:

make build

Build the Docker image:

make docker

Run the test suite:

make test

Run tests with coverage:

make test-coverage

Copyright (c) 2019 Bo-Yi Wu

Contributions are welcome! Please feel free to submit a Pull Request.