Jenkinsfile Runner packages Jenkins pipeline execution engine as a command line tool or as a Docker image.
Target use cases include but not limited to:
-
Using Jenkins in a Function-as-a-Service context.
-
Assist editing and testing Jenkins Pipeline definitions and libraries locally.
-
Integration testing of Pipelines.
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.
See this directory for the source codes of the demo. There are more demos available in the project.
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 GitHub Releases.
-
There is also a standalone JAR option available there, but this is a preview-only feature (see issue #350).
-
Latest unreleased versions can be also built from source code. See the contributing guidelines if you want to build Jenkinsfile Runner on your own.
-
-
Prepare the execution environment
-
Run the Pipeline
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:
-
Use the Plugin Installation Manager Tool to install plugins into a new plugin directory.
-
Run the Jenkins setup wizard and install the desired set of plugins. After that, the plugins can be retrieved from
JENKINS_HOME/plugins.
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 <path to war> -p <path to plugins> -f <path to Jenkinsfile>
Sample Jenkinsfile:
pipeline {
agent any
stages {
stage('Print hello') {
steps {
echo 'Hello world!'
}
}
}
}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.
The Jenkinsfile Runner CLI provides multiple advanced options and commands. The CLI is powered by picocli and args4j. To execute a command:
jenkinsfile-runner <command>
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 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.
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 aplugins.txtfile 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 ifplugins.txtis specified.-
NOTE: This option will be reworked in the future once the Plugin Installation Manager tool is integrated
-
-
--withInitHooks FILE- Path to the Groovy init hooks directory Hooks can be also passed viaWEB-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 @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,--httpPortis 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.
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 thenode{}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 withcheckout scmin Scripted Pipelines. Note that an SCM cannot currently be used with Pipeline as YAML. See this doc for more details.
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/ \ # pipeline has two parameters param1 and param2 -a "param1=Hello" \ -a "param2=value2"
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.
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 jenkins/jenkinsfile-runner repository on DockerHub.
There is a 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 jenkins4eval/jenkinsfile-runner repository on DockerHub.
Jenkinsfile Runner images can be launched simply as…
docker run --rm -v $(pwd)/Jenkinsfile:/workspace/Jenkinsfile jenkins/jenkinsfile-runner
Advanced options:
-
JAVA_OPTSenvironment variable can be passed to pass extra JVM arguments to the image
docker run --rm -e JAVA_OPTS="-Xms 256m" -v $PWD/test:/workspace jenkins/jenkinsfile-runner-
In the Vanilla
Dockerfilethe 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/buildby default and it can be exposed as well. However it is possible to override that directory if both the-vdocker option and the--runWorkspaceJenkinsfile Runner option are specified. -
By default the JENKINS_HOME folder is randomly created and disposed afterwards. With the
--runHomeparameter in combination with the-vDocker 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. -
The
-nsand-aoptions 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. -
You may pass
--clito obtain an interactive Jenkins CLI session. To get an interactive Jenkins CLI shell in the container, pass-i -e FORCE_JENKINS_CLI=truetodocker runas extra parameters. -
If you want to change default parameters for plugins or workspace, you can get onto the container by overriding entrypoint - binary is placed in
/app/bin/jenkinsfile-runner.
$ docker run --rm -it -v $PWD/test:/workspace --entrypoint bash jenkinsfile-runner:my-production-jenkins
root@dec4c0f12478:/src# cp -r /app/jenkins /tmp/jenkins
root@dec4c0f12478:/src# /app/bin/jenkinsfile-runner -w /tmp/jenkins -p /usr/share/jenkins/ref/plugins -f /workspaceJenkinsfile 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:
-
Using low-level management tools, including the
--pluginscommand included in CLI. -
Docker
Please use GitHub Issues to report defects and improvement ideas. If you see a security issue in the component, please follow the vulnerability reporting guidelines.
-
Open issues in Jenkins JIRA (deprecated)
See the roadmap here.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent