mirror of https://github.com/appleboy/drone-jenkins.git synced 2026-06-04 10:15:02 +08:00

Files

T

Bo-Yi Wu 747d7b23d1 docs: update Jenkins API token creation instructions and images

- Update instructions to select "Security" instead of "Configure" when creating a Jenkins API token
- Replace the token creation image with a new screenshot
- Remove the old jenkins-token.png image and add personal-token.png

Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>

2025-12-01 17:45:49 +08:00

8.1 KiB

Raw Blame History

drone-jenkins

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

drone-jenkins

Features

Trigger single or multiple Jenkins jobs
Support for Jenkins build parameters
Multiple authentication methods (API token or remote trigger token)
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 \
  --name jenkins \
  -d --restart always \
  -p 8080:8080 -p 50000:50000 \
  -v /data/jenkins:/var/jenkins_home \
  jenkins/jenkins:lts

Note: Create the /data/jenkins directory before starting Jenkins.

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 `key=value` format
Insecure	`--insecure`	`PLUGIN_INSECURE`, `JENKINS_INSECURE`	No	Allow insecure SSL connections (default: false)

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

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

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

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

Development

Building

Build the binary:

make build