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
• SSL/TLS support with optional insecure mode
• 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 key=value format
Insecure	--insecure	PLUGIN_INSECURE, JENKINS_INSECURE	No	Allow insecure SSL connections (default: false)
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)

Authentication Requirements: You must provide either:

• user + token (API token authentication), OR
• remote-token (remote trigger token authentication)

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" \
  --parameters "VERSION=1.0.0"

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

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,VERSION=1.0.0" \
  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

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}

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

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.