jenkins4eval/jenkinsfile-runner

Jenkinsfile Runner（孵化项目）

镜像概述和主要用途

Jenkinsfile Runner将Jenkins流水线执行引擎打包为命令行工具或Docker镜像，旨在提供灵活的Jenkins流水线执行方式，无需完整的Jenkins服务器环境。

核心功能和特性

• 多环境支持：可作为命令行工具或Docker镜像运行
• 丰富命令集：支持run（执行流水线）、lint（验证Declarative Pipeline语法）、cli（Jenkins交互命令行）等命令
• 插件管理：可通过插件目录或plugins.txt文件自定义插件集
• 参数传递：支持向流水线传递参数，满足动态执行需求
• 轻量级执行：默认使用临时Jenkins Home，可指定持久化目录
• 性能优化：支持跳过关闭逻辑以提升执行速度（--skipShutdown）

使用场景和适用范围

• FaaS环境：在函数即服务场景中运行Jenkins流水线
• 本地开发测试：辅助开发人员本地编辑和测试Jenkinsfile及流水线库
• 集成测试：对Jenkins Pipeline进行自动化集成测试
• CI/CD流程嵌入：作为现有CI/CD系统的组件执行特定流水线任务

使用方法和配置说明

命令行使用

准备工作

1. 从https://github.com/jenkinsci/jenkinsfile-runner/releases下载Jenkinsfile Runner ZIP归档（或构建源码）
2. （可选）准备插件：
   • 使用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('Print hello') {
            steps {
                echo 'Hello world!'
            }
        }
    }
}

执行输出：

$ ./app/target/appassembler/bin/jenkinsfile-runner -w /tmp/jenkins -p /tmp/jenkins_home/plugins -f ~/foo/
Started
Resume disabled by user, switching to high-performance, low-durability mode.
[Pipeline] node
[Pipeline] {
[Pipeline] stage
[Pipeline] { (Print hello)
[Pipeline] echo
Hello world!
[Pipeline] }
[Pipeline] // stage
[Pipeline] }
[Pipeline] // node
[Pipeline] End of Pipeline
Finished: SUCCESS

命令行接口（CLI）

支持以下命令：

• run：执行Jenkinsfile（默认命令）
• lint：验证Declarative Pipeline语法（不执行）
• cli：启动交互式Jenkins CLI，支持list-plugins、groovy等命令
• generate-completion：生成bash/zsh自动补全脚本
• version：显示版本信息
• help：显示命令帮助

通用参数

• -w (--jenkins-war) FILE：Jenkins WAR文件或解压目录路径
• -jv (--jenkins-version) VAL：Jenkins版本（未指定WAR时使用，默认最新LTS）
• -p (--plugins) FILE：插件目录或plugins.txt文件路径（默认plugins.txt）
• --jenkinsHome FILE：指定Jenkins Home目录（默认临时目录）
• --httpPort：Web服务器端口（默认禁用）
• --agentPort：代理连接端口（默认禁用）

执行命令（run）参数

• -f (--file) FILE：Jenkinsfile路径或包含Jenkinsfile的目录（默认./Jenkinsfile）
• -a (--arg)：传递给流水线的参数（key=value格式，可多次使用）
• --runWorkspace FILE：指定工作空间路径
• -ns (--no-sandbox)：禁用沙箱环境和脚本安全检查（谨慎使用）
• -n (--job-name) VAL：任务名称（默认'job'）
• -b (--build-number) N：构建编号（默认1）
• -c (--cause) VAL：构建原因描述

传递参数示例：

bash
jenkinsfile-runner -w /tmp/jenkins -p /tmp/plugins -f ~/foo/ -a "param1=Hello" -a "param2=value2"

Docker使用

镜像类型

• Vanilla发行版：包含运行流水线的最小插件集，DockerHub地址：jenkins/jenkinsfile-runner
• 镜像包：针对特定场景（如Java/Maven项目）的预配置镜像，位于jenkins4eval/jenkinsfile-runner（实验性）

基本运行

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

高级配置

• JVM参数：通过JAVA_OPTS环境变量设置

  bash
  docker run --rm -e JAVA_OPTS="-Xms256m -Xmx512m" -v $PWD:/workspace docker.xuanyuan.run/jenkins/jenkinsfile-runner
  

• 持久化Jenkins Home：

  bash
  docker run --rm -v $(pwd)/Jenkinsfile:/workspace/Jenkinsfile -v /local/jenkinsHome:/jenkinsHome docker.xuanyuan.run/jenkins/jenkinsfile-runner --runHome /jenkinsHome
  

• 交互式CLI：

  bash
  docker run --rm -it -v $PWD:/workspace -e FORCE_JENKINS_CLI=true docker.xuanyuan.run/jenkins/jenkinsfile-runner --cli
  

• 自定义命令：

  bash
  docker run --rm -it -v $PWD:/workspace --entrypoint bash docker.xuanyuan.run/jenkins/jenkinsfile-runner
  /app/bin/jenkinsfile-runner -w /tmp/jenkins -p /usr/share/jenkins/ref/plugins -f /workspace
  

扩展Jenkinsfile Runner

可通过以下方式扩展：

1. 命令行方式：使用--plugins参数指定自定义插件目录或plugins.txt
2. Docker方式：使用Custom WAR/Docker Packager通过YAML配置管理插件和工具，详见https://github.com/jenkinsci/jenkinsfile-runner/blob/master/docs/using/EXTENDING_DOCKER.adoc

问题报告

• 缺陷和改进建议：https://github.com/jenkinsci/jenkinsfile-runner/issues
• 安全漏洞：遵循https://jenkins.io/security/#reporting-vulnerabilities

进一步阅读

• 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
• 幻灯片：https://docs.google.com/presentation/d/1y7YnAdnh5WY59g8oIGTsj8sLQ5KXgoV7uUCBkxcTU88/edit?usp=sharing