= Jenkinsfile Runner (Incubating project) :toc: :toc-placement: preamble :toclevels: 3
https://github.com/jenkinsci/jenkinsfile-runner/releases/latest[image:https://img.shields.io/github/v/release/jenkinsci/jenkinsfile-runner?include_prereleases&label=changelog[GitHub release (latest by date including pre-releases)]] https://github.com/jenkinsci/jenkinsfile-runner/graphs/contributors[image:https://img.shields.io/github/contributors/jenkinsci/jenkinsfile-runner[GitHub contributors]] link:https://github.com/orgs/jenkinsci/projects/22[image:https://img.shields.io/badge/JFR-roadmap-blue[Roadmap]] https://community.jenkins.io/c/contributing/jenkinsfile-runner/22[image:https://img.shields.io/badge/discourse-forum-brightgreen.svg?style=flat-square[Discourse]] https://gitter.im/jenkinsci/jenkinsfile-runner[image:https://badges.gitter.im/jenkinsci/jenkinsfile-runner.svg[Gitter]]
Jenkinsfile Runner packages Jenkins pipeline execution engine as a command line tool or as a Docker image.
== Use-cases
Target use cases include but not limited to:
== Quick Demo
The demo below demonstrates running of a simple Pipeline with Jenkinsfile Runner. It is based on the Vanilla distribution which includes the minimum required set of plugins for running pipelines.
image:./demo/cwp/recording.gif[Jenkinsfile Runner Demo]
See link:./demo/cwp/[this directory] for the source codes of the demo. There are more demos available in the project.
== Usage in command-line
Jenkinsfile Runner can be run in the command line or in Docker. To run it in the command line follow these steps:
. Download the Jenkinsfile Runner ZIP archive available in https://github.com/jenkinsci/jenkinsfile-runner/releases[GitHub Releases]. There is also a standalone JAR option available there, but this is a preview-only feature (see https://github.com/jenkinsci/jenkinsfile-runner/issues/350[issue #350]). Latest unreleased versions can be also built from source code. See the link:./CONTRIBUTING.adoc[contributing guidelines] if you want to build Jenkinsfile Runner on your own. . Prepare the execution environment . Run the Pipeline
=== Preparation
Jenkinsfile Runner bundle includes the Jenkins core and a minimum set of plugins. More plugins can be installed on-demand. If it is not needed, just skip this step.
To add plugins, create a directory and assemble all the plugins that you’d like to use with the build. There are two ways to do it:
JENKINS_HOME/plugins.=== Execution
Say you have your Git repository checked out at ~/foo that contains Jenkinsfile and your source code.
You can now run Jenkinsfile Runner like this:
....
jenkinsfile-runner -w
Sample Jenkinsfile:
Output:
.... $ ./app/target/appassembler/bin/jenkinsfile-runner -w /tmp/jenkins -p /tmp/jenkins_home/plugins -f ~/foo/ -a "param1=Hello¶m2=value2" Started Resume disabled by user, switching to high-performance, low-durability mode. [Pipeline] node [Pipeline] { [Pipeline] // stage [Pipeline] stage [Pipeline] { (Print hello) [Pipeline] echo Hello world! [Pipeline] } [Pipeline] // stage [Pipeline] } [Pipeline] // node [Pipeline] End of Pipeline Finished: SUCCESS ....
The exit code reflects the result of the build.
The demo directory includes a few simple examples of Jenkinsfiles you can try out.
=== Command Line Interface (CLI)
The Jenkinsfile Runner CLI provides multiple advanced options and commands. The CLI is powered by https://picocli.info/[picocli] and https://github.com/kohsuke/args4j[args4j]. To execute a command:
....
jenkinsfile-runner
Supported commands:
run - Runs the Jenkinsfile.
This command also runs by default if no subcommands specified.lint - Lints the Jenkinsfile without actually running it.
Only applicable to Declarative Pipeline.cli - Runs interactive https://www.jenkins.io/doc/book/managing/cli/[Jenkins CLI] from where you can access all standard
Jenkins commands provided by the Jenkins core and installed plugins:
list-plugins, groovy, groovysh, etc.generate-completion - Generate bash/zsh completion script for Jenkinsfile Runner.version - Shows the Jenkinsfile Runner version.help - Displays help information about the specified command.All commands provide additional CLI arguments which can be accessed through help methods.
==== Jenkins Instance Arguments
Some CLI commands, including run require a startup of the Jenkins controller instance within Jenkinsfile Runner.
Common arguments:
-w (--jenkins-war) FILE -
Path to exploded Jenkins WAR directory.
Depending on packaging, it may contain the entire WAR file or just resources to be loaded
by the WAR file, for example Groovy hooks or extra libraries.-jv (--jenkins-version) VAL : Jenkins version to use if the WAR file is not specified.
Defaults to latest LTS.-p (--plugins) FILE - Plugins required for the run.
Should point to either a plugins.txt file or to a /plugins installation directory
Defaults to plugins.txt.Advanced arguments:
--jenkinsHome FILE -
Path to the empty Jenkins Home directory to use for this run.
If not specified a temporary directory will be created.
Note that the specified folder will not be disposed after the run.--mirror - Mirror site to be used to download plugins if plugins.txt is specified.
** NOTE: This option will be reworked in the future once the Plugin Installation Manager tool is integrated--withInitHooks FILE - Path to the https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/[Groovy init hooks] directory
Hooks can be also passed via WEB-INF/groovy.init.d/** directory within the Jenkins WAR resource loader defined in --jenkins-war.--skipShutdown - Skips the Jenkins shutdown logic to improve performance.
Jenkinsfile Runner will abort the instance instead of gracefully releasing the resources.
For example, agent connections will not be terminated.
Also, plugin https://javadoc.jenkins.io/hudson/init/Terminator.html[@Terminator] extensions will not be invoked.
It may lead to undefined behavior in the system, including potential data loss.
This option is considered safe for the Vanilla package with the default plugin set.--httpPort - Port for exposing the web server and Jenkins Web UI from Jenkinsfile Runner.
Disabled by default.--httpPath - The root path/prefix for expositng the web server and Jenkins Web UI from Jenkinsfile Runner.--openWebUI - Open Jenkins Web UI in the default browser, --httpPort is expected to be defined together with this option.--waitOnExit - Keep Jenkinsfile Runner running upon job completion without various sleep() hacks in the Pipeline.--agentPort - Port for connecting inbound Jenkins agents (over JNLP or WebSockets).
Disabled by default.==== Running Jenkinsfiles (run command)
This is the main command in Jenkinsfile Runner. It executes all types of Pipeline definitions supported by Jenkinsfile Runner. Usage:
.... jenkinsfile-runner run -w [warPath] -p [pluginsDirPath] -f [jenkinsfilePath] [other options] ....
In addition to Jenkins instance arguments defined above, it supports the following options:
-f (--file) FILE -
Path to Jenkinsfile (or directory containing a Jenkinsfile) to run, defaults to ./Jenkinsfile.-a (--arg) -
Parameters to be passed to the Pipeline job.
Use multiple -a switches for multiple params.
All parameters will be recognized by Jenkins as String values.Advanced options:
--runWorkspace FILE -
Path to the workspace of the run to be used within the node{} context.
It applies to both Jenkins controller and agents if any.-u (--keep-undefined-parameters) -
Keep undefined parameters if set, defaults to false.-ns (--no-sandbox) -
Run Pipeline job execution without the sandbox environment and script security checks.
Use at your own risk.-n (--job-name) VAL -
Name of the job the run belongs to, defaults to 'job'-b (--build-number) N-
Build number of the run, defaults to 1.-c (--cause) VAL-
A string describing the cause of the run.
It will be attached to the build so that it appears in the build log and
becomes available to plug-ins and pipeline steps.--scm FILE -
A YAML file defining the SCM and optional credentials to use with the SCM.
If given, the SCM will be checked out into the workspace automatically in Declarative Pipelines,
and will be available for use with checkout scm in Scripted Pipelines.
Note that an SCM cannot currently be used with Pipeline as YAML.
See link:./docs/using/SCM.adoc[this doc for more details].==== Passing parameters
Any parameter values, for parameters defined on workflow job within parameters statement,
can be passed to the Jenkinsfile Runner using -a or --arg switches in the key=value format.
.... $ ./app/target/appassembler/bin/jenkinsfile-runner \ -w /tmp/jenkins \ -p /tmp/jenkins_home/plugins \ -f ~/foo/ \
-a "param1=Hello" \ -a "param2=value2" ....
== Usage in Docker
Containerized Pipeline execution is one of the main Jenkinsfile Runner use-cases. The project provides official Docker images which can be used and extended for custom use-cases.
=== Vanilla Distribution
This repository provides the Vanilla distribution. This package includes the minimum required set of plugins for running pipelines, but it needs to be extended in order to run real-world pipelines. The image is available in the https://hub.docker.com/r/jenkins/jenkinsfile-runner[jenkins/jenkinsfile-runner] repository on DockerHub.
=== Image Packs
There is a https://github.com/jenkinsci/jenkinsfile-runner-image-packs[Jenkinsfile Runner Image Packs] repository. It provides additional Docker images for common use-cases, e.g. for building Java projects with Maven or Gradle. Each image includes a set of Jenkins plugins, configurations and Pipeline libraries which are commonly used in the desired technology stack. Image packs are available in the experimental https://hub.docker.com/r/jenkins/jenkinsfile-runner[jenkins4eval/jenkinsfile-runner] repository on DockerHub.
=== Running Jenkinsfile Runner in Docker
Jenkinsfile Runner images can be launched simply as…
.... docker run --rm -v $(pwd)/Jenkinsfile:/workspace/Jenkinsfile jenkins/jenkinsfile-runner ....
Advanced options:
JAVA_OPTS environment variable can be passed to pass extra JVM arguments to the imageDockerfile the master workspace is mapped to /build.
This directory can be exposed as a volume.
The Docker image generated with Custom War Packager maps the workspace to /build by default and
it can be exposed as well.
However it is possible to override that directory if both the -v docker option and the --runWorkspace Jenkinsfile Runner option are specified.--runHome parameter in combination with the -v Docker option it is possible to specify a folder.
e.g. docker run -v /local/Jenkinsfile:/workspace/Jenkinsfile -v /local/jenkinsHome:/jenkinsHome ${JENKINSFILE_RUNNER_IMAGE} --runHome /jenkinsHome.
This way you can access the build metadata in <jenkinsHome>/jobs/job/builds/1,
like the build.xml, logs, and workflow data, even after the container finished.-ns and -a options can be specified and passed to the image in the same way as the command line execution.
Using a non-sandbox environment may pose potential security risks.
We strongly encourage you not to use this mode unless it is strictly necessary and always with extreme care and at your own risk.--cli to obtain an interactive Jenkins CLI session.
To get an interactive Jenkins CLI shell in the container, pass -i -e FORCE_JENKINS_CLI=true to docker run as extra parameters./app/bin/jenkinsfile-runner.== Extending Jenkinsfile Runner
Jenkinsfile Runner provides a vanilla image which includes some plugins and configurations. Usually, it is not enough to run a real Jenkins Pipelines. It might be required to install extra plugins and tools, and then to configure Jenkins so that Pipelines can properly operate in the user environment.
There are 2 ways to extend Jenkinsfile Runner:
--plugins command included in CLI.== Reporting issues
Please use https://github.com/jenkinsci/jenkinsfile-runner/issues[GitHub Issues] to report defects and improvement ideas. If you see a security issue in the component, please follow the https://jenkins.io/security/#reporting-vulnerabilities[vulnerability reporting guidelines].
== Project roadmap
See the roadmap link:https://github.com/orgs/jenkinsci/projects/22[here].
== Further reading