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>
2026-06-04 10:15:02 +08:00 · 2025-12-26 15:44:17 +08:00
parent 6a8250d7e6
commit d8cceb3839
3 changed files with 1038 additions and 13 deletions
@@ -1,5 +1,7 @@
 # drone-jenkins

+[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
 ![logo](./images/logo.png)

 [![Lint and Testing](https://github.com/appleboy/drone-jenkins/actions/workflows/lint.yml/badge.svg)](https://github.com/appleboy/drone-jenkins/actions/workflows/lint.yml)
@@ -10,9 +12,30 @@

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

+## Why drone-jenkins?
+
+In modern enterprise environments, teams often adopt different CI/CD platforms based on their specific needs, project requirements, or historical decisions. It's common to find:
+
+- **Multiple CI platforms coexisting**: Some teams use Jenkins for its extensive plugin ecosystem, while others prefer Drone for its simplicity and container-native approach.
+- **Legacy systems integration**: Organizations with established Jenkins pipelines need to integrate with newer CI/CD workflows without rewriting everything.
+- **Cross-team collaboration**: Different departments may standardize on different tools, requiring seamless communication between platforms.
+
+**drone-jenkins** bridges this gap by allowing CI/CD pipelines to trigger Jenkins jobs as part of their workflow. While originally designed for Drone CI, it works seamlessly with **GitHub Actions**, **GitLab CI**, and any CI platform that supports Docker containers or shell commands.
+
+This enables:
+
+- **Unified deployment pipelines**: Trigger existing Jenkins deployment jobs from any CI platform without migration
+- **Gradual migration**: Teams can incrementally move to modern CI platforms while still leveraging Jenkins jobs
+- **Best of both worlds**: Use GitHub Actions or Drone for modern containerized builds and Jenkins for specialized tasks with specific plugins
+- **Centralized orchestration**: Coordinate builds across multiple CI systems from a single pipeline
+- **Flexibility**: Available as a CLI binary, Docker image, or native plugin—use it however fits your workflow
+
+Whether you're managing a hybrid CI/CD environment or orchestrating complex multi-platform deployments, drone-jenkins provides the connectivity you need.
+
 ## Table of Contents

 - [drone-jenkins](#drone-jenkins)
+  - [Why drone-jenkins?](#why-drone-jenkins)
  - [Table of Contents](#table-of-contents)
  - [Features](#features)
  - [Prerequisites](#prerequisites)
@@ -118,19 +141,19 @@ Alternatively, you can use a remote trigger token configured in your Jenkins job

 ### 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 multi-line `key=value` format (one per line)  |
-| Insecure      | `--insecure`         | `PLUGIN_INSECURE`, `JENKINS_INSECURE`           | No            | Allow insecure SSL connections (default: false)                   |
-| CA Cert       | `--ca-cert`          | `PLUGIN_CA_CERT`, `JENKINS_CA_CERT`             | No            | Custom CA certificate (PEM content, file path, or HTTP URL)       |
-| Wait          | `--wait`             | `PLUGIN_WAIT`, `JENKINS_WAIT`                   | No            | Wait for job completion (default: false)                          |
-| Poll Interval | `--poll-interval`    | `PLUGIN_POLL_INTERVAL`, `JENKINS_POLL_INTERVAL` | No            | Interval between status checks (default: 10s)                     |
-| Timeout       | `--timeout`          | `PLUGIN_TIMEOUT`, `JENKINS_TIMEOUT`             | No            | Maximum time to wait for job completion (default: 30m)            |
+| 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 multi-line `key=value` format (one per line)          |
+| Insecure      | `--insecure`         | `PLUGIN_INSECURE`, `JENKINS_INSECURE`           | No            | Allow insecure SSL connections (default: false)                           |
+| CA Cert       | `--ca-cert`          | `PLUGIN_CA_CERT`, `JENKINS_CA_CERT`             | No            | Custom CA certificate (PEM content, file path, or HTTP URL)               |
+| Wait          | `--wait`             | `PLUGIN_WAIT`, `JENKINS_WAIT`                   | No            | Wait for job completion (default: false)                                  |
+| Poll Interval | `--poll-interval`    | `PLUGIN_POLL_INTERVAL`, `JENKINS_POLL_INTERVAL` | No            | Interval between status checks (default: 10s)                             |
+| Timeout       | `--timeout`          | `PLUGIN_TIMEOUT`, `JENKINS_TIMEOUT`             | No            | Maximum time to wait for job completion (default: 30m)                    |
 | Debug         | `--debug`            | `PLUGIN_DEBUG`, `JENKINS_DEBUG`                 | No            | Enable debug mode to show detailed parameter information (default: false) |

 **Authentication Requirements**: You must provide either:
@@ -0,0 +1,501 @@
+# drone-jenkins
+
+[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
+![logo](./images/logo.png)
+
+[![Lint and Testing](https://github.com/appleboy/drone-jenkins/actions/workflows/lint.yml/badge.svg)](https://github.com/appleboy/drone-jenkins/actions/workflows/lint.yml)
+[![Trivy Security Scan](https://github.com/appleboy/drone-jenkins/actions/workflows/trivy.yml/badge.svg)](https://github.com/appleboy/drone-jenkins/actions/workflows/trivy.yml)
+[![GoDoc](https://godoc.org/github.com/appleboy/drone-jenkins?status.svg)](https://godoc.org/github.com/appleboy/drone-jenkins)
+[![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)
+
+一个用于触发 [Jenkins](https://jenkins.io/) 任务的 [Drone](https://github.com/drone/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 都能提供您所需的连接能力。
+
+## 目录
+
+- [drone-jenkins](#drone-jenkins)
+  - [为什么选择 drone-jenkins？](#为什么选择-drone-jenkins)
+  - [目录](#目录)
+  - [功能特性](#功能特性)
+  - [前置条件](#前置条件)
+  - [安装](#安装)
+    - [下载可执行文件](#下载可执行文件)
+    - [从源码构建](#从源码构建)
+    - [Docker 镜像](#docker-镜像)
+  - [配置](#配置)
+    - [Jenkins 服务器设置](#jenkins-服务器设置)
+    - [认证](#认证)
+    - [参数参考](#参数参考)
+  - [使用方式](#使用方式)
+    - [命令行](#命令行)
+    - [Docker](#docker)
+    - [Drone CI](#drone-ci)
+  - [开发](#开发)
+    - [构建](#构建)
+    - [测试](#测试)
+  - [许可证](#许可证)
+  - [贡献](#贡献)
+
+## 功能特性
+
+- 触发单个或多个 Jenkins 任务
+- 支持 Jenkins 构建参数
+- 多种认证方式（API 令牌或远程触发令牌）
+- 等待任务完成，可配置轮询间隔和超时时间
+- 调试模式，显示详细参数信息并安全遮蔽令牌
+- SSL/TLS 支持，可使用自定义 CA 证书（PEM 内容、文件路径或 URL）
+- 跨平台支持（Linux、macOS、Windows）
+- 提供可执行文件、Docker 镜像或 Drone 插件形式
+
+## 前置条件
+
+- Jenkins 服务器（建议版本 2.0 或更新版本）
+- 用于认证的 Jenkins API 令牌或远程触发令牌
+- 对于 Jenkins 设置，建议使用 Docker，但非必需
+
+## 安装
+
+### 下载可执行文件
+
+预编译的可执行文件可从[发布页面](https://github.com/appleboy/drone-jenkins/releases)下载，支持：
+
+- **Linux**: amd64, 386
+- **macOS (Darwin)**: amd64, 386
+- **Windows**: amd64, 386
+
+如果已安装 Go，也可以直接安装：
+
+```sh
+go install github.com/appleboy/drone-jenkins@latest
+```
+
+### 从源码构建
+
+克隆仓库并构建：
+
+```sh
+git clone https://github.com/appleboy/drone-jenkins.git
+cd drone-jenkins
+make build
+```
+
+### Docker 镜像
+
+构建 Docker 镜像：
+
+```sh
+make docker
+```
+
+或拉取预构建的镜像：
+
+```sh
+docker pull ghcr.io/appleboy/drone-jenkins
+```
+
+## 配置
+
+### Jenkins 服务器设置
+
+使用 Docker 设置 Jenkins 服务器：
+
+```sh
+docker run -d -v jenkins_home:/var/jenkins_home -p 8080:8080 -p 50000:50000 --restart=on-failure jenkins/jenkins:slim
+```
+
+### 认证
+
+建议使用 Jenkins API 令牌进行认证。创建 API 令牌的步骤：
+
+1. 登录 Jenkins
+2. 点击右上角的用户名
+3. 选择"安全"
+4. 在"API 令牌"下，点击"添加新令牌"
+5. 输入名称并点击"生成"
+6. 复制生成的令牌
+
+![personal token](./images/personal-token.png)
+
+或者，您可以使用在 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`（每行一个）
+- 空行会自动忽略
+- 只有空白的行会被跳过
+- 键名会去除前后空白
+- 值会保留有意义的空格
+- 值可以包含 `=` 符号（第一个 `=` 之后的所有内容都视为值）
+
+## 使用方式
+
+### 命令行
+
+**单个任务：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job drone-jenkins-plugin
+```
+
+**多个任务：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job drone-jenkins-plugin-1 \
+  --job drone-jenkins-plugin-2
+```
+
+**带构建参数：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job my-jenkins-job \
+  --parameters $'ENVIRONMENT=production\nVERSION=1.0.0'
+```
+
+或使用环境变量：
+
+```bash
+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
+```
+
+**使用远程令牌认证：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --remote-token REMOTE_TOKEN_HERE \
+  --job my-jenkins-job
+```
+
+**等待任务完成：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job my-jenkins-job \
+  --wait \
+  --poll-interval 15s \
+  --timeout 1h
+```
+
+**使用调试模式：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job my-jenkins-job \
+  --debug
+```
+
+**使用自定义 CA 证书：**
+
+```bash
+# 使用文件路径
+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
+
+**单个任务：**
+
+```bash
+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
+```
+
+**多个任务：**
+
+```bash
+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
+```
+
+**带构建参数：**
+
+```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\nVERSION=1.0.0\nBRANCH=main' \
+  ghcr.io/appleboy/drone-jenkins
+```
+
+**等待任务完成：**
+
+```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_WAIT=true \
+  -e JENKINS_POLL_INTERVAL=15s \
+  -e JENKINS_TIMEOUT=1h \
+  ghcr.io/appleboy/drone-jenkins
+```
+
+**使用调试模式：**
+
+```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_DEBUG=true \
+  ghcr.io/appleboy/drone-jenkins
+```
+
+**使用自定义 CA 证书：**
+
+```bash
+# 使用挂载的证书文件
+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`：
+
+```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
+```
+
+**多个任务带参数：**
+
+```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}
+        BRANCH=${DRONE_BRANCH}
+```
+
+**使用远程令牌：**
+
+```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
+```
+
+**等待任务完成：**
+
+```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-production
+      wait: true
+      poll_interval: 15s
+      timeout: 1h
+```
+
+**使用调试模式：**
+
+```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: my-jenkins-job
+      debug: true
+```
+
+**使用自定义 CA 证书：**
+
+```yaml
+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](DOCS.md)。
+
+## 开发
+
+### 构建
+
+构建可执行文件：
+
+```sh
+make build
+```
+
+构建 Docker 镜像：
+
+```sh
+make docker
+```
+
+### 测试
+
+运行测试套件：
+
+```sh
+make test
+```
+
+运行测试并生成覆盖率报告：
+
+```sh
+make test-coverage
+```
+
+## 许可证
+
+Copyright (c) 2019 Bo-Yi Wu
+
+## 贡献
+
+欢迎贡献！请随时提交 Pull Request。
@@ -0,0 +1,501 @@
+# drone-jenkins
+
+[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
+
+![logo](./images/logo.png)
+
+[![Lint and Testing](https://github.com/appleboy/drone-jenkins/actions/workflows/lint.yml/badge.svg)](https://github.com/appleboy/drone-jenkins/actions/workflows/lint.yml)
+[![Trivy Security Scan](https://github.com/appleboy/drone-jenkins/actions/workflows/trivy.yml/badge.svg)](https://github.com/appleboy/drone-jenkins/actions/workflows/trivy.yml)
+[![GoDoc](https://godoc.org/github.com/appleboy/drone-jenkins?status.svg)](https://godoc.org/github.com/appleboy/drone-jenkins)
+[![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)
+
+一個用於觸發 [Jenkins](https://jenkins.io/) 任務的 [Drone](https://github.com/drone/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 都能提供您所需的連接能力。
+
+## 目錄
+
+- [drone-jenkins](#drone-jenkins)
+  - [為什麼選擇 drone-jenkins？](#為什麼選擇-drone-jenkins)
+  - [目錄](#目錄)
+  - [功能特色](#功能特色)
+  - [先決條件](#先決條件)
+  - [安裝](#安裝)
+    - [下載執行檔](#下載執行檔)
+    - [從原始碼建置](#從原始碼建置)
+    - [Docker 映像檔](#docker-映像檔)
+  - [設定](#設定)
+    - [Jenkins 伺服器設定](#jenkins-伺服器設定)
+    - [認證](#認證)
+    - [參數參考](#參數參考)
+  - [使用方式](#使用方式)
+    - [命令列](#命令列)
+    - [Docker](#docker)
+    - [Drone CI](#drone-ci)
+  - [開發](#開發)
+    - [建置](#建置)
+    - [測試](#測試)
+  - [授權條款](#授權條款)
+  - [貢獻](#貢獻)
+
+## 功能特色
+
+- 觸發單一或多個 Jenkins 任務
+- 支援 Jenkins 建置參數
+- 多種認證方式（API 令牌或遠端觸發令牌）
+- 等待任務完成，可設定輪詢間隔和逾時時間
+- 除錯模式，顯示詳細參數資訊並安全遮蔽令牌
+- SSL/TLS 支援，可使用自訂 CA 憑證（PEM 內容、檔案路徑或 URL）
+- 跨平台支援（Linux、macOS、Windows）
+- 提供執行檔、Docker 映像檔或 Drone 外掛形式
+
+## 先決條件
+
+- Jenkins 伺服器（建議版本 2.0 或更新版本）
+- 用於認證的 Jenkins API 令牌或遠端觸發令牌
+- 對於 Jenkins 設定，建議使用 Docker，但非必要
+
+## 安裝
+
+### 下載執行檔
+
+預先編譯的執行檔可從[發布頁面](https://github.com/appleboy/drone-jenkins/releases)下載，支援：
+
+- **Linux**: amd64, 386
+- **macOS (Darwin)**: amd64, 386
+- **Windows**: amd64, 386
+
+如果已安裝 Go，也可以直接安裝：
+
+```sh
+go install github.com/appleboy/drone-jenkins@latest
+```
+
+### 從原始碼建置
+
+複製儲存庫並建置：
+
+```sh
+git clone https://github.com/appleboy/drone-jenkins.git
+cd drone-jenkins
+make build
+```
+
+### Docker 映像檔
+
+建置 Docker 映像檔：
+
+```sh
+make docker
+```
+
+或拉取預先建置的映像檔：
+
+```sh
+docker pull ghcr.io/appleboy/drone-jenkins
+```
+
+## 設定
+
+### Jenkins 伺服器設定
+
+使用 Docker 設定 Jenkins 伺服器：
+
+```sh
+docker run -d -v jenkins_home:/var/jenkins_home -p 8080:8080 -p 50000:50000 --restart=on-failure jenkins/jenkins:slim
+```
+
+### 認證
+
+建議使用 Jenkins API 令牌進行認證。建立 API 令牌的步驟：
+
+1. 登入 Jenkins
+2. 點擊右上角的使用者名稱
+3. 選擇「安全性」
+4. 在「API 令牌」下，點擊「新增令牌」
+5. 輸入名稱並點擊「產生」
+6. 複製產生的令牌
+
+![personal token](./images/personal-token.png)
+
+或者，您可以使用在 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`（每行一個）
+- 空行會自動忽略
+- 只有空白的行會被跳過
+- 鍵名會去除前後空白
+- 值會保留有意義的空格
+- 值可以包含 `=` 符號（第一個 `=` 之後的所有內容都視為值）
+
+## 使用方式
+
+### 命令列
+
+**單一任務：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job drone-jenkins-plugin
+```
+
+**多個任務：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job drone-jenkins-plugin-1 \
+  --job drone-jenkins-plugin-2
+```
+
+**帶建置參數：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job my-jenkins-job \
+  --parameters $'ENVIRONMENT=production\nVERSION=1.0.0'
+```
+
+或使用環境變數：
+
+```bash
+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
+```
+
+**使用遠端令牌認證：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --remote-token REMOTE_TOKEN_HERE \
+  --job my-jenkins-job
+```
+
+**等待任務完成：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job my-jenkins-job \
+  --wait \
+  --poll-interval 15s \
+  --timeout 1h
+```
+
+**使用除錯模式：**
+
+```bash
+drone-jenkins \
+  --host http://jenkins.example.com/ \
+  --user appleboy \
+  --token XXXXXXXX \
+  --job my-jenkins-job \
+  --debug
+```
+
+**使用自訂 CA 憑證：**
+
+```bash
+# 使用檔案路徑
+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
+
+**單一任務：**
+
+```bash
+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
+```
+
+**多個任務：**
+
+```bash
+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
+```
+
+**帶建置參數：**
+
+```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\nVERSION=1.0.0\nBRANCH=main' \
+  ghcr.io/appleboy/drone-jenkins
+```
+
+**等待任務完成：**
+
+```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_WAIT=true \
+  -e JENKINS_POLL_INTERVAL=15s \
+  -e JENKINS_TIMEOUT=1h \
+  ghcr.io/appleboy/drone-jenkins
+```
+
+**使用除錯模式：**
+
+```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_DEBUG=true \
+  ghcr.io/appleboy/drone-jenkins
+```
+
+**使用自訂 CA 憑證：**
+
+```bash
+# 使用掛載的憑證檔案
+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`：
+
+```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
+```
+
+**多個任務帶參數：**
+
+```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}
+        BRANCH=${DRONE_BRANCH}
+```
+
+**使用遠端令牌：**
+
+```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
+```
+
+**等待任務完成：**
+
+```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-production
+      wait: true
+      poll_interval: 15s
+      timeout: 1h
+```
+
+**使用除錯模式：**
+
+```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: my-jenkins-job
+      debug: true
+```
+
+**使用自訂 CA 憑證：**
+
+```yaml
+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](DOCS.md)。
+
+## 開發
+
+### 建置
+
+建置執行檔：
+
+```sh
+make build
+```
+
+建置 Docker 映像檔：
+
+```sh
+make docker
+```
+
+### 測試
+
+執行測試套件：
+
+```sh
+make test
+```
+
+執行測試並產生覆蓋率報告：
+
+```sh
+make test-coverage
+```
+
+## 授權條款
+
+Copyright (c) 2019 Bo-Yi Wu
+
+## 貢獻
+
+歡迎貢獻！請隨時提交 Pull Request。