drone-jenkins

A Drone plugin for triggering Jenkins jobs with flexible authentication and parameter support.

Table of Contents

• drone-jenkins
  • Table of Contents
  • Features
  • Prerequisites
  • Installation
    • Download Binary
    • Build from Source
    • Docker Image
  • Configuration
    • Jenkins Server Setup
    • Authentication
    • Parameters Reference
  • Usage
    • Command Line
    • Docker
    • Drone CI
  • Development
    • Building
    • Testing
  • License
  • Contributing

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:

make docker

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:

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

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), OR
• remote-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:

make build

Build the Docker image:

make docker

Testing

Run the test suite:

make test

Run tests with coverage:

make test-coverage

License

Copyright (c) 2019 Bo-Yi Wu

Contributing

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