Jenkinsfile Runner: executing a Jenkinsfile outside a Jenkins controller

It embeds a Jenkins controller inside a CLI process

The core idea in one line from the README: Jenkinsfile Runner packages the Jenkins pipeline execution engine as a command line tool or as a Docker image. The bundle includes the Jenkins core and a minimum set of plugins, and more plugins can be installed on demand. That is the whole design, and it explains both the strengths and the awkward parts. Because it is a real Jenkins under the hood, a pipeline that runs here behaves like the same pipeline on a controller, which is what makes the tool credible for integration testing. It also means the tool carries a controller's weight, plugins and all, in a process you might have expected to be a small script. The project labels itself an incubating project in its own title, which is an honest signal about where it sits in its lifecycle.

The three use cases the project names are all about feedback speed

The README lists target use cases. Using Jenkins in a Function-as-a-Service context. Assisting with editing and testing Jenkins Pipeline definitions and libraries locally. And integration testing of pipelines. All three share a premise, that the feedback loop matters more than the fidelity of the surrounding infrastructure. Editing a pipeline in a shared library and then waiting for a controller to pick it up is a slow loop, and a linter or a local run shortens it. The Function-as-a-Service case is the same argument from the other direction, where you want to execute a pipeline in response to an event without provisioning a controller. What is absent from that list is production execution, which is the clearest signal about where the project intends to sit.

The invocation takes a war path, a plugins path and a Jenkinsfile

The documented command-line form is short.

jenkinsfile-runner -w <path to war> -p <path to plugins> -f <path to Jenkinsfile>

The README frames it around a Git repository checked out at ~/foo containing a Jenkinsfile and the source code. The three arguments are the exploded Jenkins WAR directory, the plugin set, and the Jenkinsfile itself. The sample run shows a longer invocation with parameters attached through an -a argument, and the output is the familiar Pipeline console log ending in a result line.

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

The README notes that the exit code reflects the result of the build, which is the feature that makes the tool usable from a script or a CI step rather than only from a terminal.

Plugins come from a plugins.txt or an installation directory

The preparation step is about plugins, and the README offers two routes. You can use the Plugin Installation Manager Tool to install plugins into a new plugin directory, or you can run the Jenkins setup wizard, install the set you want, and then retrieve the plugins from JENKINS_HOME/plugins. The -p argument accepts either a plugins.txt file or a plugins installation directory, and it defaults to plugins.txt. A related option, --mirror, sets the mirror site used to download plugins when a plugins.txt is given, and the README flags that this option will be reworked once the Plugin Installation Manager tool is integrated properly. The Vanilla distribution is the baseline, described in the demo section as including the minimum required set of plugins for running pipelines.

Five subcommands, and only one of them actually runs the pipeline

The CLI is powered by picocli and args4j, and it exposes a set of subcommands. run executes the Jenkinsfile and is also the default when no subcommand is given. lint checks the Jenkinsfile without running it, and the README is explicit that this is only applicable to Declarative Pipeline, which is a real limit for anyone with a large body of scripted pipeline code. cli starts the interactive Jenkins CLI from where you can reach the standard Jenkins commands such as list-plugins, groovy and groovysh. generate-completion produces a bash or zsh completion script. version prints the tool version. Some commands, run among them, require a startup of the Jenkins controller instance within the runner, and a set of instance arguments controls that startup.

The advanced arguments include a deliberately unsafe performance flag

Beyond the common arguments there is a set of advanced ones, and one of them is worth reading carefully. --skipShutdown skips the Jenkins shutdown logic to improve performance, in which case the runner aborts the instance instead of gracefully releasing resources, so agent connections are not terminated and @Terminator plugin extensions are not invoked. The README says this may lead to undefined behavior including potential data loss, and that the option is considered safe for the Vanilla package with the default plugin set. Other advanced options include --jenkinsHome to point at an empty Jenkins Home directory for the run, noting that a specified folder will not be disposed after the run, --withInitHooks for a directory of Groovy init hooks, and --httpPort for exposing the web server and Jenkins Web. The -jv option picks the Jenkins version to use when no WAR is specified, defaulting to the latest LTS.

Twelve demo directories show what a pipeline bundle looks like

The repository's demo/ directory is the most concrete part of the project, with subdirectories named casc, cwp, declarative-pipeline, docker-simple, git-maven, jenkins-templating-engine, job-folders, pipeline-as-yaml, pipeline-library, pipeline-utility-steps and troubleshooting. The names describe the shapes a pipeline can take, from a plain declarative pipeline to one defined in YAML, one that uses shared libraries, one that runs inside Docker, and a troubleshooting example. The README points at demo/cwp for the source of the animated demo it shows, and says more demos are available in the project. Reading a directory of these is a faster way to understand what a Jenkinsfile Runner bundle needs to contain than the prose documentation is.

An incubating project with a beta that has not moved in years

The project is MIT licensed, with LICENSE.md at the repository root, and it is structured as a Maven multi-module build with an app/ directory for the assembly, a bootstrap/ directory, packaging directories for the parent POMs and resources, a payload/ directory and payload-dependencies/, a setup/ directory, a vanilla-package/ directory, a demo/ directory, tests/ and docs/. There is a Formula/ directory for a Homebrew formula and a Jenkinsfile for the project's own build, plus ROADMAP.adoc and CONTRIBUTING.adoc. The release history is the part to note: the tags are 1.0-beta-30, 1.0-beta-31 and 1.0-beta-32, with beta-32 dated 2023-11-12, and the last push to the repository was on 2026-07-13. A tool still labelled beta after that long is not an abandoned project, but it is not a settled one either, and the beta-31 note about Java 11 and Jenkins updates shows the compatibility surface moves with the platform it embeds.

Editorial conclusion

Jenkinsfile Runner fits a pipeline author who wants to run or lint a Jenkinsfile on a laptop or in a container, without standing up a controller, because the lint command for declarative pipelines and the exit code reflecting the build result turn pipeline editing into a normal command-line loop. It is a poor fit for a production CI deployment, where the controller is what supplies the agent model, the plugin set and the queue, and it is a poor fit for scripted pipelines since lint is only applicable to Declarative Pipeline. Verify first which packaging you need, since the standalone JAR is described as preview-only and the ZIP archive is the supported route, and check the version you pin against the release history, since the most recent tag is 1.0-beta-32 from 2023-11-12.

Frequently asked questions

Official sources

1. Issues
2. jenkinsci/jenkinsfile-runner on GitHub
3. License: MIT
4. README
5. Releases