mirror of https://github.com/appleboy/drone-jenkins.git synced 2026-06-04 18:23:57 +08:00

Files

T

appleboy d8cceb3839 docs: add multilingual README and enhance usage documentation

- Add links for English, Traditional Chinese, and Simplified Chinese translations at the top of the README
- Introduce a new "Why drone-jenkins?" section explaining the use cases and benefits for hybrid CI/CD environments
- Expand the table of contents with new sections reflecting the README structure
- Correct the formatting of the parameters table for clarity
- Add a Simplified Chinese README translation (README.zh-CN.md)
- Add a Traditional Chinese README translation (README.zh-TW.md)

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

2025-12-26 15:44:17 +08:00

14 KiB

Raw Blame History

drone-jenkins

English | 繁體中文 | 简体中文

一个用于触发 Jenkins 任务的 Drone 插件，支持灵活的认证方式与参数传递。

为什么选择 drone-jenkins？

在现代企业环境中，团队经常根据特定需求、项目要求或历史决策采用不同的 CI/CD 平台。常见的情况包括：

多个 CI 平台并存：有些团队因为 Jenkins 丰富的插件生态系统而使用它，而其他团队则偏好 Drone 的简洁性和容器原生方式。
遗留系统集成：拥有既有 Jenkins 流水线的组织需要与新的 CI/CD 工作流程集成，而不需要重写所有内容。
跨团队协作：不同部门可能标准化使用不同的工具，需要平台之间的无缝沟通。

drone-jenkins 弥补了这个差距，让 CI/CD 流水线能够将触发 Jenkins 任务作为工作流程的一部分。虽然最初是为 Drone CI 设计的，但它可以与 GitHub Actions、GitLab CI 以及任何支持 Docker 容器或 Shell 命令的 CI 平台无缝协作。

这使得以下场景成为可能：

统一的部署流水线：从任何 CI 平台触发现有的 Jenkins 部署任务，无需迁移
渐进式迁移：团队可以逐步迁移到现代 CI 平台，同时继续使用 Jenkins 任务
两全其美：使用 GitHub Actions 或 Drone 进行现代容器化构建，并使用 Jenkins 处理需要特定插件的专门任务
集中式编排：从单一流水线协调跨多个 CI 系统的构建
灵活使用：提供 CLI 可执行文件、Docker 镜像或原生插件——根据您的工作流程选择使用方式

无论您是在管理混合 CI/CD 环境还是编排复杂的多平台部署，drone-jenkins 都能提供您所需的连接能力。

功能特性

触发单个或多个 Jenkins 任务
支持 Jenkins 构建参数
多种认证方式（API 令牌或远程触发令牌）
等待任务完成，可配置轮询间隔和超时时间
调试模式，显示详细参数信息并安全遮蔽令牌
SSL/TLS 支持，可使用自定义 CA 证书（PEM 内容、文件路径或 URL）
跨平台支持（Linux、macOS、Windows）
提供可执行文件、Docker 镜像或 Drone 插件形式

前置条件

Jenkins 服务器（建议版本 2.0 或更新版本）
用于认证的 Jenkins API 令牌或远程触发令牌
对于 Jenkins 设置，建议使用 Docker，但非必需

安装

下载可执行文件

预编译的可执行文件可从发布页面下载，支持：

Linux: amd64, 386
macOS (Darwin): amd64, 386
Windows: amd64, 386

如果已安装 Go，也可以直接安装：

go install github.com/appleboy/drone-jenkins@latest

从源码构建

克隆仓库并构建：

git clone https://github.com/appleboy/drone-jenkins.git
cd drone-jenkins
make build

Docker 镜像

构建 Docker 镜像：

make docker

或拉取预构建的镜像：

docker pull ghcr.io/appleboy/drone-jenkins

配置

Jenkins 服务器设置

使用 Docker 设置 Jenkins 服务器：

docker run -d -v jenkins_home:/var/jenkins_home -p 8080:8080 -p 50000:50000 --restart=on-failure jenkins/jenkins:slim

认证

建议使用 Jenkins API 令牌进行认证。创建 API 令牌的步骤：

登录 Jenkins
点击右上角的用户名
选择"安全"
在"API 令牌"下，点击"添加新令牌"
输入名称并点击"生成"
复制生成的令牌

或者，您可以使用在 Jenkins 任务设置中配置的远程触发令牌。

参数参考

参数	CLI 标志	环境变量	必需	说明
Host	`--host`	`PLUGIN_URL`, `JENKINS_URL`	是	Jenkins 基础 URL（例如 `http://jenkins.example.com/`）
User	`--user`, `-u`	`PLUGIN_USER`, `JENKINS_USER`	条件式*	Jenkins 用户名
Token	`--token`, `-t`	`PLUGIN_TOKEN`, `JENKINS_TOKEN`	条件式*	Jenkins API 令牌
Remote Token	`--remote-token`	`PLUGIN_REMOTE_TOKEN`, `JENKINS_REMOTE_TOKEN`	条件式*	Jenkins 远程触发令牌
Job	`--job`, `-j`	`PLUGIN_JOB`, `JENKINS_JOB`	是	Jenkins 任务名称 - 可指定多个
Parameters	`--parameters`, `-p`	`PLUGIN_PARAMETERS`, `JENKINS_PARAMETERS`	否	构建参数，多行 `key=value` 格式（每行一个）
Insecure	`--insecure`	`PLUGIN_INSECURE`, `JENKINS_INSECURE`	否	允许不安全的 SSL 连接（默认：false）
CA Cert	`--ca-cert`	`PLUGIN_CA_CERT`, `JENKINS_CA_CERT`	否	自定义 CA 证书（PEM 内容、文件路径或 HTTP URL）
Wait	`--wait`	`PLUGIN_WAIT`, `JENKINS_WAIT`	否	等待任务完成（默认：false）
Poll Interval	`--poll-interval`	`PLUGIN_POLL_INTERVAL`, `JENKINS_POLL_INTERVAL`	否	状态检查间隔（默认：10s）
Timeout	`--timeout`	`PLUGIN_TIMEOUT`, `JENKINS_TIMEOUT`	否	等待任务完成的最长时间（默认：30m）
Debug	`--debug`	`PLUGIN_DEBUG`, `JENKINS_DEBUG`	否	启用调试模式以显示详细参数信息（默认：false）

认证要求：您必须提供以下其中一种：

user + token（API 令牌认证），或
remote-token（远程触发令牌认证）

参数格式：parameters 字段接受多行字符串，每行包含一个 key=value 配对：

每个参数应该在单独一行
格式：KEY=VALUE（每行一个）
空行会自动忽略
只有空白的行会被跳过
键名会去除前后空白
值会保留有意义的空格
值可以包含 = 符号（第一个 = 之后的所有内容都视为值）

使用方式

命令行

单个任务：

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job drone-jenkins-plugin

多个任务：

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job drone-jenkins-plugin-1 \
  --job drone-jenkins-plugin-2

带构建参数：

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --parameters $'ENVIRONMENT=production\nVERSION=1.0.0'

或使用环境变量：

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

使用远程令牌认证：

drone-jenkins \
  --host http://jenkins.example.com/ \
  --remote-token REMOTE_TOKEN_HERE \
  --job my-jenkins-job

等待任务完成：

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --wait \
  --poll-interval 15s \
  --timeout 1h

使用调试模式：

drone-jenkins \
  --host http://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --debug

使用自定义 CA 证书：

# 使用文件路径
drone-jenkins \
  --host https://jenkins.example.com/ \
  --user appleboy \
  --token XXXXXXXX \
  --job my-jenkins-job \
  --ca-cert /path/to/ca.pem

# 使用 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

单个任务：

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

多个任务：

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

带构建参数：

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

等待任务完成：

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

使用调试模式：

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

使用自定义 CA 证书：

# 使用挂载的证书文件
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

# 使用 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

将插件添加到您的 .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

多个任务带参数：

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}

使用远程令牌：

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

等待任务完成：

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

使用调试模式：

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

使用自定义 CA 证书：

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

更多详细示例和高级配置，请参阅 DOCS.md。

开发

构建

构建可执行文件：

make build

构建 Docker 镜像：

make docker

测试

运行测试套件：

make test

运行测试并生成覆盖率报告：

make test-coverage

许可证

贡献

欢迎贡献！请随时提交 Pull Request。

14 KiB Raw Blame History Unescape Escape

drone-jenkins

为什么选择 drone-jenkins？

目录

功能特性

前置条件

安装

下载可执行文件

从源码构建

Docker 镜像

配置

Jenkins 服务器设置

认证

参数参考

使用方式

命令行

Docker

Drone CI

开发

构建

测试

许可证

贡献

14 KiB

Raw Blame History