jenkins/jenkinsfile-runner

Jenkinsfile Runner（孵化项目）

![Gitter]([***]

Jenkinsfile Runner 将 Jenkins 流水线执行引擎打包为命令行工具或 Docker 镜像。

使用场景

目标使用场景包括但不限于：

• 在函数即服务（Function-as-a-Service）环境中使用 Jenkins。
• 辅助本地编辑和测试 Jenkins 流水线定义及库。
• 流水线的集成测试。

快速演示

以下演示展示了使用 Jenkinsfile Runner 运行简单流水线的过程。基于“Vanilla”发行版，该版本包含运行流水线所需的最小插件集。

!https://github.com/jenkinsci/jenkinsfile-runner/raw/master/demo/cwp/recording.gif

演示源代码见 https://github.com/jenkinsci/jenkinsfile-runner/tree/master/demo/cwp%E3%80%82%E9%A1%B9%E7%9B%AE%E4%B8%AD%E8%BF%98%E6%8F%90%E4%BE%9B%E4%BA%86%E6%9B%B4%E5%A4%9A%E6%BC%94%E7%A4%BA%E3%80%82

命令行使用

Jenkinsfile Runner 可通过命令行或 Docker 运行。通过命令行运行步骤如下：

1. 从 https://github.com/jenkinsci/jenkinsfile-runner/releases 下载 Jenkinsfile Runner ZIP 归档包。
   • 也提供独立 JAR 选项，但此为预览功能（参见 https://github.com/jenkinsci/jenkinsfile-runner/issues/350%EF%BC%89%E3%80%82
   • 最新未发布版本可从源代码构建。如需自行构建，参见 https://github.com/jenkinsci/jenkinsfile-runner/blob/master/CONTRIBUTING.adoc%E3%80%82
2. 准备执行环境
3. 运行流水线

准备

Jenkinsfile Runner 包包含 Jenkins 核心及最小插件集。可按需安装更多插件，如无需则跳过此步骤。

添加插件需创建目录并组装所需插件，方法有二：

• 使用 https://github.com/jenkinsci/plugin-installation-manager-tool 将插件安装到新插件目录。
• 运行 Jenkins 安装向导并安装所需插件，之后从 JENKINS_HOME/plugins 获取插件。

执行

假设 Git 仓库已检出至 ~/foo，包含 Jenkinsfile 及源代码，运行命令如下：

bash
jenkinsfile-runner -w <war文件路径> -p <插件路径> -f <Jenkinsfile路径>

示例 Jenkinsfile：

groovy
pipeline {
    agent any
    stages {
        stage('打印问候') {
            steps {
                echo 'Hello world!'
            }
        }
    }
}

输出示例：

$ ./app/target/appassembler/bin/jenkinsfile-runner -w /tmp/jenkins -p /tmp/jenkins_home/plugins -f ~/foo/ -a "param1=Hello&param2=value2"
Started
Resume disabled by user, switching to high-performance, low-durability mode.
[Pipeline] node
[Pipeline] {
[Pipeline] // stage
[Pipeline] stage
[Pipeline] { (打印问候)
[Pipeline] echo
Hello world!
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

退出码反映构建结果。demo 目录包含多个简单 Jenkinsfile 示例。

命令行界面（CLI）

CLI 由 picocli 和 https://github.com/kohsuke/args4j 提供支持，命令格式：

bash
jenkinsfile-runner <命令>

支持的命令：

• run - 运行 Jenkinsfile，未指定子命令时默认执行。
• lint - 校验 Jenkinsfile（仅支持声明式流水线）。
• cli - 启动交互式 Jenkins CLI，可执行 list-plugins、groovy 等标准命令。
• generate-completion - 生成 bash/zsh 补全脚本。
• version - 显示版本信息。
• help - 显示命令帮助。

各命令参数可通过帮助方法查看。

Jenkins 实例参数

run 等命令需启动 Jenkins 控制器实例，通用参数：

• -w (--jenkins-war) FILE - Jenkins WAR 解压目录路径，可能包含完整 WAR 文件或资源（如 Groovy 钩子、额外库）。
• -jv (--jenkins-version) VAL - 未指定 WAR 时使用的 Jenkins 版本，默认最新 LTS。
• -p (--plugins) FILE - 运行所需插件，指向 plugins.txt 或插件安装目录，默认 plugins.txt。

高级参数：

• --jenkinsHome FILE - 本次运行使用的空 Jenkins 主目录路径，未指定则创建临时目录，运行后不自动清理。
• --mirror - 指定 plugins.txt 时下载插件的镜像站点（未来将整合插件安装管理工具）。
• --withInitHooks FILE - Groovy 初始化钩子 目录路径，也可通过 --jenkins-war 指定的 WAR 资源加载器中 WEB-INF/groovy.init.d/** 目录传递。
• --skipShutdown - 跳过 Jenkins 关闭逻辑以提升性能，可能导致资源未释放或数据丢失，基础包默认插件集下使用视为安全。
• --httpPort - 暴露 Web 服务器及 Jenkins Web UI 的端口，默认禁用。
• --agentPort - 入站 Jenkins 代理（JNLP 或 WebSocket）连接端口，默认禁用。

运行 Jenkinsfile（run 命令）

主命令，支持所有类型流水线定义，用法：

bash
jenkinsfile-runner run -w [war路径] -p [插件目录路径] -f [Jenkinsfile路径] [其他选项]

除实例参数外，支持：

• -f (--file) FILE - Jenkinsfile 路径（或含 Jenkinsfile 的目录），默认 ./Jenkinsfile。
• -a (--arg) - 传递给流水线的参数，多参数需多个 -a，均视为字符串类型。

高级选项：

• --runWorkspace FILE - node{} 上下文中使用的工作区路径，适用于控制器及代理。
• -u (--keep-undefined-parameters) - 保留未定义参数，默认 false。
• -ns (--no-sandbox) - 禁用沙箱环境及脚本安全检查，风险自负。
• -n (--job-name) VAL - 任务名称，默认 job。
• -b (--build-number) N - 构建编号，默认 1。
• -c (--cause) VAL - 构建原因描述，将附加到构建日志并供插件和流水线步骤使用。
• --scm FILE - 定义 SCM 及凭据的 YAML 文件，声明式流水线自动检出，脚本式流水线需 checkout scm，暂不支持 YAML 格式流水线，详见 https://github.com/jenkinsci/jenkinsfile-runner/blob/master/docs/using/SCM.adoc%E3%80%82

参数传递

通过 -a 或 --arg 传递 parameters 语句中定义的参数，格式 key=value：

bash
$ ./app/target/appassembler/bin/jenkinsfile-runner \
  -w /tmp/jenkins \
  -p /tmp/jenkins_home/plugins \
  -f ~/foo/ \
  -a "param1=Hello" \
  -a "param2=value2"

Docker 使用

容器化流水线执行是核心场景，项目提供官方 Docker 镜像，支持自定义扩展。

Vanilla 发行版

包含运行流水线的最小插件集，需扩展以运行实际流水线，镜像位于 DockerHub https://hub.docker.com/r/jenkins/jenkinsfile-runner%E3%80%82

镜像包

https://github.com/jenkinsci/jenkinsfile-runner-image-packs 提供常见场景镜像（如 Maven/Gradle 构建 Java 项目），包含插件、配置及流水线库，位于实验性 DockerHub 仓库 https://hub.docker.com/r/jenkins4eval/jenkinsfile-runner%E3%80%82

Docker 运行示例

基础运行命令：

bash
docker run --rm -v $(pwd)/Jenkinsfile:/workspace/Jenkinsfile jenkins/jenkinsfile-runner

高级选项：

• JAVA_OPTS：传递 JVM 参数

  bash
  

docker run --rm -e JAVA_OPTS="-Xms256m" -v $PWD/test:/workspace jenkins/jenkinsfile-runner

* **工作目录**：Vanilla 镜像默认映射 `/build` 为工作区，可通过 `-v` 暴露为卷，结合 `--runWorkspace` 覆盖路径。

* **Jenkins 主目录持久化**：默认临时创建并清理，通过 `--runHome` 及 `-v` 指定本地目录保留构建元数据：
  ```bash
docker run -v /local/Jenkinsfile:/workspace/Jenkinsfile -v /local/jenkinsHome:/jenkinsHome jenkins/jenkinsfile-runner --runHome /jenkinsHome

构建元数据（如 build.xml、日志）位于 <jenkinsHome>/jobs/job/builds/1。

• 非沙箱模式：通过 -ns 禁用沙箱，存在安全风险，需谨慎使用。

• 交互式 CLI：传递 --cli 及 -i -e FORCE_JENKINS_CLI=true 获取交互式会话：

  bash
  

docker run --rm -i -e FORCE_JENKINS_CLI=true -v $(pwd)/Jenkinsfile:/workspace/Jenkinsfile jenkins/jenkinsfile-runner --cli

* **自定义配置**：覆盖入口点进入容器，二进制路径 `/app/bin/jenkinsfile-runner`：
  ```bash
docker run --rm -it -v $PWD/test:/workspace --entrypoint bash jenkinsfile-runner:my-production-jenkins
root@dec4c0f12478:/src# /app/bin/jenkinsfile-runner -w /tmp/jenkins -p /usr/share/jenkins/ref/plugins -f /workspace

扩展方法

扩展方式有二：

1. 使用 https://github.com/jenkinsci/plugin-installation-manager-tool 通过 CLI --plugins 命令管理插件。
2. Docker 镜像：使用 Custom WAR/Docker Packager 自动化构建步骤，通过 YAML 文件管理配置。详见 https://github.com/jenkinsci/jenkinsfile-runner/blob/master/docs/using/EXTENDING_DOCKER.adoc%E3%80%82

问题报告

缺陷及改进建议通过 https://github.com/jenkinsci/jenkinsfile-runner/issues 提交。安全问题按 漏洞报告指南 处理。

• https://github.com/jenkinsci/jenkinsfile-runner/issues
• Jenkins JIRA 开放 issues%20AND%20component%20%3D%20jenkinsfile-runner)（已弃用）

进一步阅读

• https://github.com/jenkinsci/jenkinsfile-runner/blob/master/docs/using/TROUBLESHOOTING.adoc
• https://github.com/jenkinsci/jenkinsfile-runner/blob/master/CONTRIBUTING.adoc
• https://github.com/jenkinsci/jenkinsfile-runner/blob/master/docs/developer/README.adoc
• 幻灯片：无服务器 Jenkins 内幕：Jenkinsfile Runner