GitHub - appleboy/drone-jenkins: Drone plugin for trigger Jenkins jobs. (original) (raw)
drone-jenkins
A Drone plugin for triggering Jenkins jobs with flexible authentication and parameter support.
Table of Contents
Features
- 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 binary, Docker image, or Drone plugin
Prerequisites
- 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
Installation
Download Binary
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
Build from Source
Clone the repository and build:
git clone https://github.com/appleboy/drone-jenkins.git cd drone-jenkins make build
Docker Image
Build the Docker image:
Or pull the pre-built image:
docker pull ghcr.io/appleboy/drone-jenkins
Configuration
Jenkins Server Setup
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
Authentication
Jenkins API tokens are recommended for authentication. To create an API token:
- Log into Jenkins
- Click on your username (top right)
- Select "Security"
- Under "API Token", click "Add new Token"
- Give it a name and click "Generate"
- Copy the generated token
Alternatively, you can use a remote trigger token configured in your Jenkins job settings.
Parameters Reference
| Parameter | CLI Flag | Environment Variable | Required | Description |
|---|---|---|---|---|
| Host | --host | PLUGIN_URL, JENKINS_URL | Yes | Jenkins base URL (e.g., http://jenkins.example.com/) |
| User | --user, -u | PLUGIN_USER, JENKINS_USER | Conditional* | Jenkins username |
| Token | --token, -t | PLUGIN_TOKEN, JENKINS_TOKEN | Conditional* | Jenkins API token |
| Remote Token | --remote-token | PLUGIN_REMOTE_TOKEN, JENKINS_REMOTE_TOKEN | Conditional* | Jenkins remote trigger token |
| Job | --job, -j | PLUGIN_JOB, JENKINS_JOB | Yes | Jenkins job name(s) - can specify multiple |
| Parameters | --parameters, -p | PLUGIN_PARAMETERS, JENKINS_PARAMETERS | No | Build parameters in multi-line key=value format (one per line) |
| Insecure | --insecure | PLUGIN_INSECURE, JENKINS_INSECURE | No | Allow insecure SSL connections (default: false) |
| CA Cert | --ca-cert | PLUGIN_CA_CERT, JENKINS_CA_CERT | No | Custom CA certificate (PEM content, file path, or HTTP URL) |
| Wait | --wait | PLUGIN_WAIT, JENKINS_WAIT | No | Wait for job completion (default: false) |
| Poll Interval | --poll-interval | PLUGIN_POLL_INTERVAL, JENKINS_POLL_INTERVAL | No | Interval between status checks (default: 10s) |
| Timeout | --timeout | PLUGIN_TIMEOUT, JENKINS_TIMEOUT | No | Maximum time to wait for job completion (default: 30m) |
| Debug | --debug | PLUGIN_DEBUG, JENKINS_DEBUG | No | Enable debug mode to show detailed parameter information (default: false) |
Authentication Requirements: You must provide either:
user+token(API token authentication), ORremote-token(remote trigger token authentication)
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)
Usage
Command Line
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 remote token authentication:
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
Docker
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
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
Drone CI
Add the plugin to your .drone.yml:
kind: pipeline name: default
steps:
- name: trigger-jenkins image: ghcr.io/appleboy/drone-jenkins settings: url: http://jenkins.example.com/ user: appleboy token: from_secret: jenkins_token job: drone-jenkins-plugin
Multiple jobs with parameters:
steps:
- name: trigger-jenkins image: ghcr.io/appleboy/drone-jenkins settings: url: http://jenkins.example.com/ user: appleboy token: from_secret: jenkins_token job: - deploy-frontend - deploy-backend parameters: | ENVIRONMENT=production VERSION=${DRONE_TAG} COMMIT_SHA=${DRONE_COMMIT_SHA} BRANCH=${DRONE_BRANCH}
Using remote token:
steps:
- name: trigger-jenkins image: ghcr.io/appleboy/drone-jenkins settings: url: http://jenkins.example.com/ remote_token: from_secret: jenkins_remote_token job: my-jenkins-job
Wait for job completion:
steps:
- name: trigger-jenkins image: ghcr.io/appleboy/drone-jenkins settings: url: http://jenkins.example.com/ user: appleboy token: from_secret: jenkins_token job: deploy-production wait: true poll_interval: 15s timeout: 1h
With debug mode:
steps:
- name: trigger-jenkins image: ghcr.io/appleboy/drone-jenkins settings: url: http://jenkins.example.com/ user: appleboy token: from_secret: jenkins_token job: my-jenkins-job debug: true
With custom CA certificate:
steps:
- name: trigger-jenkins image: ghcr.io/appleboy/drone-jenkins settings: url: https://jenkins.example.com/ user: appleboy token: from_secret: jenkins_token job: my-jenkins-job ca_cert: from_secret: jenkins_ca_cert
For more detailed examples and advanced configurations, see DOCS.md.
Development
Building
Build the binary:
Build the Docker image:
Testing
Run the test suite:
Run tests with coverage:
License
Copyright (c) 2019 Bo-Yi Wu
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.