From cc67514a1ae96c83e788c3160a1e7753c2973f3d Mon Sep 17 00:00:00 2001 From: Bo-Yi Wu Date: Mon, 1 Dec 2025 17:28:52 +0800 Subject: [PATCH] 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 --- README.md | 295 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 238 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index f0ee807..00d2334 100644 --- a/README.md +++ b/README.md @@ -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.