docs: revamp README with expanded setup, usage, and integration docs

- Rewrite and expand the README with a new structure, including a Table of Contents, Features, Prerequisites, Installation, Configuration, Usage, Development, License, and Contributing sections - Add detailed installation instructions for binary, source, and Docker image - Provide step-by-step Jenkins server setup and authentication guidance - Introduce a comprehensive parameters reference table for configuration - Clarify authentication requirements and usage scenarios for CLI, Docker, and Drone CI - Update environment variable names for consistency (use JENKINS_URL instead of JENKINS_BASE_URL) - Add multiple usage examples for single/multiple jobs and parameterized builds - Include instructions and examples for integrating with Drone CI pipelines - Add development instructions for building, testing, and test coverage - Add license and contributing information at the end of the README Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>
2026-06-04 10:15:02 +08:00 · 2025-12-01 17:28:52 +08:00
parent 3d7ffaed68
commit cc67514a1a
1 changed files with 238 additions and 57 deletions
@@ -8,14 +8,95 @@
 [![codecov](https://codecov.io/gh/appleboy/drone-jenkins/branch/master/graph/badge.svg)](https://codecov.io/gh/appleboy/drone-jenkins)
 [![Go Report Card](https://goreportcard.com/badge/github.com/appleboy/drone-jenkins)](https://goreportcard.com/report/github.com/appleboy/drone-jenkins)

-[Drone](https://github.com/drone/drone) plugin for trigger [Jenkins](https://jenkins.io/) jobs.
+A [Drone](https://github.com/drone/drone) plugin for triggering [Jenkins](https://jenkins.io/) jobs with flexible authentication and parameter support.

-## Setup the Jenkins Server
+## Table of Contents

-Setup the Jenkins server using the docker command:
+- [drone-jenkins](#drone-jenkins)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+    - [Download Binary](#download-binary)
+    - [Build from Source](#build-from-source)
+    - [Docker Image](#docker-image)
+  - [Configuration](#configuration)
+    - [Jenkins Server Setup](#jenkins-server-setup)
+    - [Authentication](#authentication)
+    - [Parameters Reference](#parameters-reference)
+  - [Usage](#usage)
+    - [Command Line](#command-line)
+    - [Docker](#docker)
+    - [Drone CI](#drone-ci)
+  - [Development](#development)
+    - [Building](#building)
+    - [Testing](#testing)
+  - [License](#license)
+  - [Contributing](#contributing)
+
+## 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](https://github.com/appleboy/drone-jenkins/releases) for:
+
+- **Linux**: amd64, 386
+- **macOS (Darwin)**: amd64, 386
+- **Windows**: amd64, 386
+
+With Go installed, you can also install directly:

 ```sh
-$ docker run \
+go install github.com/appleboy/drone-jenkins@latest
+```
+
+### Build from Source
+
+Clone the repository and build:
+
+```sh
+git clone https://github.com/appleboy/drone-jenkins.git
+cd drone-jenkins
+make build
+```
+
+### Docker Image
+
+Build the Docker image:
+
+```sh
+make docker
+```
+
+Or pull the pre-built image:
+
+```sh
+docker pull ghcr.io/appleboy/drone-jenkins
+```
+
+## Configuration
+
+### Jenkins Server Setup
+
+Set up a Jenkins server using Docker:
+
+```sh
+docker run \
  --name jenkins \
  -d --restart always \
  -p 8080:8080 -p 50000:50000 \
@@ -23,45 +104,45 @@ $ docker run \
  jenkins/jenkins:lts
 ```

-Please make sure that you create the `/data/jenkins` before starting the Jenkins. Create the new API token as below:
+**Note**: Create the `/data/jenkins` directory before starting Jenkins.
+
+### 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 "Configure"
+4. Under "API Token", click "Add new Token"
+5. Give it a name and click "Generate"
+6. Copy the generated token

 ![jenkins token](./images/jenkins-token.png)

-## Build or Download a binary
+Alternatively, you can use a remote trigger token configured in your Jenkins job settings.

-The pre-compiled binaries can be downloaded from [release page](https://github.com/appleboy/drone-jenkins/releases). Support the following OS type.
+### Parameters Reference

- Windows amd64/386
- Linux amd64/386
- Darwin amd64/386
+| 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)        |

-With `Go` installed
+**Authentication Requirements**: You must provide either:

-```sh
-go install github.com/appleboy/drone-jenkins
-```
-
-or build the binary with the following command:
-
-```sh
-make build
-```
-
-## Docker
-
-Build the docker image with the following commands:
-
-```sh
-make docker
-```
+- `user` + `token` (API token authentication), OR
+- `remote-token` (remote trigger token authentication)

 ## Usage

-There are three ways to trigger jenkins jobs.
+### Command Line

-### Usage from binary
-
-trigger single job.
+**Single job:**

 ```bash
 drone-jenkins \
@@ -71,7 +152,7 @@ drone-jenkins \
  --job drone-jenkins-plugin
 ```

-trigger multiple jobs.
+**Multiple jobs:**

 ```bash
 drone-jenkins \
@@ -82,51 +163,151 @@ drone-jenkins \
  --job drone-jenkins-plugin-2
 ```

-### Usage from docker
+**With build parameters:**

-trigger single job.
+```bash
+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:**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --remote-token REMOTE_TOKEN_HERE \
+  --job my-jenkins-job
+```
+
+### Docker
+
+**Single job:**

 ```bash
 docker run --rm \
-  -e JENKINS_BASE_URL=http://jenkins.example.com/
-  -e JENKINS_USER=appleboy
-  -e JENKINS_TOKEN=xxxxxxx
-  -e JENKINS_JOB=drone-jenkins-plugin
+  -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
 ```

-trigger multiple jobs.
+**Multiple jobs:**

 ```bash
 docker run --rm \
-  -e JENKINS_BASE_URL=http://jenkins.example.com/
-  -e JENKINS_USER=appleboy
-  -e JENKINS_TOKEN=xxxxxxx
-  -e JENKINS_JOB=drone-jenkins-plugin-1,drone-jenkins-plugin-2
+  -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
 ```

-### Usage from drone ci
+**With build parameters:**

-Execute from the working directory:
+```bash
+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`:
+
+```yaml
+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:**
+
+```yaml
+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:**
+
+```yaml
+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](DOCS.md).
+
+## Development
+
+### Building
+
+Build the binary:

 ```sh
-docker run --rm \
-  -e PLUGIN_URL=http://example.com \
-  -e PLUGIN_USER=xxxxxxx \
-  -e PLUGIN_TOKEN=xxxxxxx \
-  -e PLUGIN_JOB=xxxxxxx \
-  -v $(pwd):$(pwd) \
-  -w $(pwd) \
-  ghcr.io/appleboy/drone-jenkins
+make build
 ```

-You can get more [information](DOCS.md) about how to use scp plugin in drone.
+Build the Docker image:

-## Testing
+```sh
+make docker
+```

-Test the package with the following command:
+### Testing
+
+Run the test suite:

 ```sh
 make test
 ```
+
+Run tests with coverage:
+
+```sh
+make test-coverage
+```
+
+## License
+
+Copyright (c) 2019 Bo-Yi Wu
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.