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

Files

T

appleboy f2a83d3d6c docs: document Jenkins authentication and CSRF protection methods

- Clarify and expand Jenkins authentication documentation, outlining API token, remote trigger token, and combined authentication options
- Add detailed explanations and requirements for working with CSRF protection in Jenkins, including error guidance
- Modify authentication requirements and usage examples to emphasize API token over remote trigger token, especially for secure Jenkins setups
- Introduce a Troubleshooting section with solutions for common Jenkins authentication errors (403, 401, remote token issues)
- Add corresponding CSRF protection notices and troubleshooting guidance to Chinese (Simplified and Traditional) documentation

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

2025-12-27 11:56:15 +08:00

13 KiB

Raw Permalink Blame History

drone-jenkins

English | 繁體中文 | 简体中文

一个用于触发 Jenkins 任务的 CLI 工具与 CI/CD 插件。支持 GitHub Actions、GitLab CI、Gitea Action 以及任何支持 Docker 容器或 Shell 命令的平台。

为什么选择 drone-jenkins？

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

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

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

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

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

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

功能特性

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

前置条件

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 任务设置中配置的远程触发令牌。

CSRF 保护注意事项

现代 Jenkins 安装默认启用 CSRF 保护。如果您遇到以下错误：

Error 403 No valid crumb was included in the request

这表示您的 Jenkins 已启用 CSRF 保护。您必须使用 API 令牌认证（user + token）。单独使用远程触发令牌将无法工作。

如需更多关于 Jenkins CSRF 保护的信息，请参阅 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