{"id":13903050,"url":"https://github.com/jenkinsci/jenkinsfile-runner","last_synced_at":"2025-05-14T12:11:13.730Z","repository":{"id":39422671,"uuid":"122790633","full_name":"jenkinsci/jenkinsfile-runner","owner":"jenkinsci","description":"A command line tool to run Jenkinsfile as a function","archived":false,"fork":false,"pushed_at":"2025-04-02T22:41:28.000Z","size":1793,"stargazers_count":1165,"open_issues_count":93,"forks_count":303,"subscribers_count":32,"default_branch":"main","last_synced_at":"2025-04-13T04:56:16.565Z","etag":null,"topics":["cli","docker-image","faas","jenkins","jenkins-pipeline","jenkinsfile","jenkinsfile-runner"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jenkinsci.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":"CONTRIBUTING.adoc","funding":".github/FUNDING.yml","license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":"ROADMAP.adoc","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"community_bridge":"jenkins","custom":["https://jenkins.io/donate/#why-donate"]}},"created_at":"2018-02-24T23:56:01.000Z","updated_at":"2025-04-12T13:52:02.000Z","dependencies_parsed_at":"2024-09-19T01:04:57.098Z","dependency_job_id":"118a31eb-cf72-4154-b862-4853a0fed3f4","html_url":"https://github.com/jenkinsci/jenkinsfile-runner","commit_stats":{"total_commits":627,"total_committers":71,"mean_commits":8.830985915492958,"dds":0.5007974481658692,"last_synced_commit":"0d867583c0783d3e0e9abacb9e5c7548a555c0b3"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fjenkinsfile-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fjenkinsfile-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fjenkinsfile-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fjenkinsfile-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/jenkinsfile-runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140760,"owners_count":22021219,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docker-image","faas","jenkins","jenkins-pipeline","jenkinsfile","jenkinsfile-runner"],"created_at":"2024-08-06T22:01:35.324Z","updated_at":"2025-05-14T12:11:13.685Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":["https://funding.communitybridge.org/projects/jenkins","https://jenkins.io/donate/#why-donate"],"categories":["Java","cli"],"sub_categories":[],"readme":"= Jenkinsfile Runner (Incubating project)\n:toc:\n:toc-placement: preamble\n:toclevels: 3\n\nhttps://github.com/jenkinsci/jenkinsfile-runner/releases/latest[image:https://img.shields.io/github/v/release/jenkinsci/jenkinsfile-runner?include_prereleases\u0026label=changelog[GitHub release (latest by date including pre-releases)]]\nhttps://github.com/jenkinsci/jenkinsfile-runner/graphs/contributors[image:https://img.shields.io/github/contributors/jenkinsci/jenkinsfile-runner[GitHub contributors]]\nlink:https://github.com/orgs/jenkinsci/projects/22[image:https://img.shields.io/badge/JFR-roadmap-blue[Roadmap]]\nhttps://community.jenkins.io/c/contributing/jenkinsfile-runner/22[image:https://img.shields.io/badge/discourse-forum-brightgreen.svg?style=flat-square[Discourse]]\nhttps://gitter.im/jenkinsci/jenkinsfile-runner[image:https://badges.gitter.im/jenkinsci/jenkinsfile-runner.svg[Gitter]]\n\nJenkinsfile Runner packages Jenkins pipeline execution engine as a command line tool or as a Docker image.\n\n== Use-cases\n\nTarget use cases include but not limited to:\n\n* Using Jenkins in a Function-as-a-Service context.\n* Assist editing and testing Jenkins Pipeline definitions and libraries locally.\n* Integration testing of Pipelines.\n\n== Quick Demo\n\nThe demo below demonstrates running of a simple Pipeline with Jenkinsfile Runner.\nIt is based on the _Vanilla_ distribution which includes the minimum required set of plugins for running pipelines.\n\nimage:./demo/cwp/recording.gif[Jenkinsfile Runner Demo]\n\nSee link:./demo/cwp/[this directory] for the source codes of the demo.\nThere are more demos available in the project.\n\n== Usage in command-line\n\nJenkinsfile Runner can be run in the command line or in Docker.\nTo run it in the command line follow these steps:\n\n. Download the Jenkinsfile Runner ZIP archive available in https://github.com/jenkinsci/jenkinsfile-runner/releases[GitHub Releases].\n** There is also a standalone JAR option available there, but this is a preview-only feature\n   (see https://github.com/jenkinsci/jenkinsfile-runner/issues/350[issue #350]).\n** Latest unreleased versions can be also built from source code.\n   See the link:./CONTRIBUTING.adoc[contributing guidelines] if you want to build Jenkinsfile Runner on your own.\n. Prepare the execution environment\n. Run the Pipeline\n\n=== Preparation\n\nJenkinsfile Runner bundle includes the Jenkins core and a minimum set of plugins.\nMore plugins can be installed on-demand.\nIf it is not needed, just skip this step.\n\nTo add plugins, create a directory and assemble all the plugins that you’d like to use with the build.\nThere are two ways to do it:\n\n* Use the https://github.com/jenkinsci/plugin-installation-manager-tool[Plugin Installation Manager Tool]\n  to install plugins into a new plugin directory.\n* Run the Jenkins setup wizard and install the desired set of plugins.\n  After that, the plugins can be retrieved from `JENKINS_HOME/plugins`.\n\n=== Execution\n\nSay you have your Git repository checked out at `~/foo` that contains `Jenkinsfile` and your source code.\nYou can now run Jenkinsfile Runner like this:\n\n....\njenkinsfile-runner -w \u003cpath to war\u003e -p \u003cpath to plugins\u003e -f \u003cpath to Jenkinsfile\u003e\n....\n\nSample Jenkinsfile:\n\n[source,groovy]\n----\npipeline {\n    agent any\n    stages {\n        stage('Print hello') {\n            steps {\n                echo 'Hello world!'\n            }\n        }\n    }\n}\n----\n\nOutput:\n\n....\n$ ./app/target/appassembler/bin/jenkinsfile-runner -w /tmp/jenkins -p /tmp/jenkins_home/plugins -f ~/foo/ -a \"param1=Hello\u0026param2=value2\"\nStarted\nResume disabled by user, switching to high-performance, low-durability mode.\n[Pipeline] node\n[Pipeline] {\n[Pipeline] // stage\n[Pipeline] stage\n[Pipeline] { (Print hello)\n[Pipeline] echo\nHello world!\n[Pipeline] }\n[Pipeline] // stage\n[Pipeline] }\n[Pipeline] // node\n[Pipeline] End of Pipeline\nFinished: SUCCESS\n....\n\nThe exit code reflects the result of the build.\nThe `demo` directory includes a few simple examples of Jenkinsfiles you can try out.\n\n=== Command Line Interface (CLI)\n\nThe Jenkinsfile Runner CLI provides multiple advanced options and commands.\nThe CLI is powered by https://picocli.info/[picocli] and https://github.com/kohsuke/args4j[args4j].\nTo execute a command:\n\n....\n jenkinsfile-runner \u003ccommand\u003e\n....\n\nSupported commands:\n\n* `run` - Runs the Jenkinsfile.\n   This command also runs by default if no subcommands specified.\n* `lint` - Lints the Jenkinsfile without actually running it.\n   Only applicable to Declarative Pipeline.\n* `cli` - Runs interactive https://www.jenkins.io/doc/book/managing/cli/[Jenkins CLI] from where you can access all standard\n   Jenkins commands provided by the Jenkins core and installed plugins:\n   `list-plugins`, `groovy`, `groovysh`, etc.\n* `generate-completion` - Generate bash/zsh completion script for Jenkinsfile Runner.\n* `version` - Shows the Jenkinsfile Runner version.\n* `help` - Displays help information about the specified command.\n\nAll commands provide additional CLI arguments which can be accessed through help methods.\n\n==== Jenkins Instance Arguments\n\nSome CLI commands, including `run` require a startup of the Jenkins controller instance within Jenkinsfile Runner.\n\nCommon arguments:\n\n* `-w (--jenkins-war) FILE` -\n    Path to exploded Jenkins WAR directory.\n    Depending on packaging, it may contain the entire WAR file or just resources to be loaded\n    by the WAR file, for example Groovy hooks or extra libraries.\n* `-jv (--jenkins-version) VAL` : Jenkins version to use if the WAR file is not specified.\nDefaults to latest LTS.\n* `-p (--plugins) FILE` - Plugins required for the run.\n    Should point to either a `plugins.txt` file or to a /plugins installation directory\n    Defaults to plugins.txt.\n\nAdvanced arguments:\n\n* `--jenkinsHome FILE` -\n    Path to the empty Jenkins Home directory to use for this run.\n    If not specified a temporary directory will be created.\n    Note that the specified folder will not be disposed after the run.\n* `--mirror` - Mirror site to be used to download plugins if `plugins.txt` is specified.\n** NOTE: This option will be reworked in the future once the Plugin Installation Manager tool is integrated\n* `--withInitHooks FILE` - Path to the https://www.jenkins.io/doc/book/managing/groovy-hook-scripts/[Groovy init hooks] directory\n    Hooks can be also passed via `WEB-INF/groovy.init.d/**` directory within the Jenkins WAR resource loader defined in `--jenkins-war`.\n* `--skipShutdown` - Skips the Jenkins shutdown logic to improve performance.\n  Jenkinsfile Runner will abort the instance instead of gracefully releasing the resources.\n  For example, agent connections will not be terminated.\n  Also, plugin https://javadoc.jenkins.io/hudson/init/Terminator.html[@Terminator] extensions will not be invoked.\n  It may lead to undefined behavior in the system, including potential data loss.\n  This option is considered safe for the Vanilla package with the default plugin set.\n* `--httpPort` - Port for exposing the web server and Jenkins Web UI from Jenkinsfile Runner.\n  Disabled by default.\n* `--httpPath` - The root path/prefix for expositng the web server and Jenkins Web UI from Jenkinsfile Runner.\n* `--openWebUI` - Open Jenkins Web UI in the default browser, `--httpPort` is expected to be defined together with this option.\n* `--waitOnExit` - Keep Jenkinsfile Runner running upon job completion without various sleep() hacks in the Pipeline.\n* `--agentPort` - Port for connecting inbound Jenkins agents (over JNLP or WebSockets).\n  Disabled by default.\n\n\n==== Running Jenkinsfiles (`run` command)\n\nThis is the main command in Jenkinsfile Runner.\nIt executes all types of Pipeline definitions supported by Jenkinsfile Runner.\nUsage:\n\n....\n jenkinsfile-runner run -w [warPath] -p [pluginsDirPath] -f [jenkinsfilePath] [other options]\n....\n\nIn addition to Jenkins instance arguments defined above, it supports the following options:\n\n* `-f (--file) FILE` -\n   Path to Jenkinsfile (or directory containing a Jenkinsfile) to run, defaults to ./Jenkinsfile.\n* `-a (--arg)` -\n    Parameters to be passed to the Pipeline job.\n    Use multiple -a switches for multiple params.\n    All parameters will be recognized by Jenkins as String values.\n\nAdvanced options:\n\n* `--runWorkspace FILE` -\n  Path to the workspace of the run to be used within the `node{}` context.\n  It applies to both Jenkins controller and agents if any.\n* `-u (--keep-undefined-parameters)` -\n  Keep undefined parameters if set, defaults to false.\n* `-ns (--no-sandbox)`  -\n    Run Pipeline job execution without the sandbox environment and script security checks.\n    Use at your own risk.\n* `-n (--job-name) VAL` -\n    Name of the job the run belongs to, defaults to 'job'\n* `-b (--build-number) N`-\n    Build number of the run, defaults to 1.\n* `-c (--cause) VAL`-\n    A string describing the cause of the run.\n    It will be attached to the build so that it appears in the build log and\n    becomes available to plug-ins and pipeline steps.\n* `--scm FILE` -\n    A YAML file defining the SCM and optional credentials to use with the SCM.\n    If given, the SCM will be checked out into the workspace automatically in Declarative Pipelines,\n    and will be available for use with `checkout scm` in Scripted Pipelines.\n    Note that an SCM cannot currently be used with Pipeline as YAML.\n    See link:./docs/using/SCM.adoc[this doc for more details].\n\n==== Passing parameters\n\nAny parameter values, for parameters defined on workflow job within `parameters` statement,\ncan be passed to the Jenkinsfile Runner using `-a` or `--arg` switches in the key=value format.\n\n....\n$ ./app/target/appassembler/bin/jenkinsfile-runner \\\n  -w /tmp/jenkins \\\n  -p /tmp/jenkins_home/plugins \\\n  -f ~/foo/ \\\n  # pipeline has two parameters param1 and param2\n  -a \"param1=Hello\" \\\n  -a \"param2=value2\"\n....\n\n== Usage in Docker\n\nContainerized Pipeline execution is one of the main Jenkinsfile Runner use-cases.\nThe project provides official Docker images which can be used and extended for custom use-cases.\n\n=== Vanilla Distribution\n\nThis repository provides the _Vanilla_ distribution.\nThis package includes the minimum required set of plugins for running pipelines,\nbut it needs to be extended in order to run real-world pipelines.\nThe image is available in the https://hub.docker.com/r/jenkins/jenkinsfile-runner[jenkins/jenkinsfile-runner] repository on DockerHub.\n\n=== Image Packs\n\nThere is a https://github.com/jenkinsci/jenkinsfile-runner-image-packs[Jenkinsfile Runner Image Packs] repository.\nIt provides additional Docker images for common use-cases, e.g. for building Java projects with Maven or Gradle.\nEach image includes a set of Jenkins plugins, configurations and Pipeline libraries which are commonly used in the desired technology stack.\nImage packs are available in the experimental https://hub.docker.com/r/jenkins/jenkinsfile-runner[jenkins4eval/jenkinsfile-runner] repository on DockerHub.\n\n=== Running Jenkinsfile Runner in Docker\n\nJenkinsfile Runner images can be launched simply as…\n\n....\n    docker run --rm -v $(pwd)/Jenkinsfile:/workspace/Jenkinsfile jenkins/jenkinsfile-runner\n....\n\nAdvanced options:\n\n* `JAVA_OPTS` environment variable can be passed to pass extra JVM arguments to the image\n\n[source,bash]\n----\ndocker run --rm -e JAVA_OPTS=\"-Xms 256m\" -v $PWD/test:/workspace jenkins/jenkinsfile-runner\n----\n\n* In the Vanilla `Dockerfile` the master workspace is mapped to `/build`.\n  This directory can be exposed as a volume.\n  The Docker image generated with Custom War Packager maps the workspace to `/build` by default and\n  it can be exposed as well.\n  However it is possible to override that directory if both the `-v` docker option and the `--runWorkspace` Jenkinsfile Runner option are specified.\n* By default the JENKINS_HOME folder is randomly created and disposed afterwards.\n  With the `--runHome` parameter in combination with the `-v` Docker option it is possible to specify a folder.\n  e.g. `docker run -v /local/Jenkinsfile:/workspace/Jenkinsfile -v /local/jenkinsHome:/jenkinsHome ${JENKINSFILE_RUNNER_IMAGE} --runHome /jenkinsHome`.\n    This way you can access the build metadata in `\u003cjenkinsHome\u003e/jobs/job/builds/1`,\n    like the build.xml, logs, and workflow data, even after the container finished.\n* The `-ns` and `-a` options can be specified and passed to the image in the same way as the command line execution.\n Using a non-sandbox environment may pose potential security risks.\n We strongly encourage you not to use this mode unless it is strictly necessary and always with extreme care and at your own risk.\n* You may pass `--cli` to obtain an interactive Jenkins CLI session.\n  To get an interactive Jenkins CLI shell in the container, pass `-i -e FORCE_JENKINS_CLI=true` to `docker run` as extra parameters.\n* If you want to change default parameters for plugins or workspace,\n  you can get onto the container by overriding entrypoint - binary is placed in `/app/bin/jenkinsfile-runner`.\n\n[source,bash]\n----\n$ docker run --rm -it -v $PWD/test:/workspace --entrypoint bash jenkinsfile-runner:my-production-jenkins\nroot@dec4c0f12478:/src# cp -r /app/jenkins /tmp/jenkins\nroot@dec4c0f12478:/src# /app/bin/jenkinsfile-runner -w /tmp/jenkins -p /usr/share/jenkins/ref/plugins -f /workspace\n----\n\n== Extending Jenkinsfile Runner\n\nJenkinsfile Runner provides a vanilla image which includes some plugins and configurations.\nUsually, it is not enough to run a real Jenkins Pipelines.\nIt might be required to install extra plugins and tools,\nand then to configure Jenkins so that Pipelines can properly operate in the user environment.\n\nThere are 2 ways to extend Jenkinsfile Runner:\n\n* Using low-level management tools, including the `--plugins` command included in CLI.\n* Docker\n** A simple example that converts a Jenkins image into a JFR can be found link:./demo/docker-simple/[here].\n** A more advanced example using the Custom WAR/Docker Packager which automates some build steps and allows managing Jenkinsfile Runner configuration via a single YAML file can be found link:./docs/using/EXTENDING_DOCKER.adoc[here].\n\n== Reporting issues\n\nPlease use https://github.com/jenkinsci/jenkinsfile-runner/issues[GitHub Issues] to report defects and improvement ideas.\nIf you see a security issue in the component, please follow the\nhttps://jenkins.io/security/#reporting-vulnerabilities[vulnerability reporting guidelines].\n\n* https://github.com/jenkinsci/jenkinsfile-runner/issues[Open issues in GitHub]\n* https://issues.jenkins-ci.org/issues/?jql=project%20%3D%20JENKINS%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20component%20%3D%20jenkinsfile-runner[Open issues in Jenkins JIRA] (deprecated)\n\n== Project roadmap\n\nSee the roadmap link:https://github.com/orgs/jenkinsci/projects/22[here].\n\n== Further reading\n\n* link:docs/using/TROUBLESHOOTING.adoc[Troubleshooting Guide]\n* link:/CONTRIBUTING.adoc[Contributing to Jenkinsfile Runner]\n* link:/docs/developer/README.adoc[Developer Documentation]\n* Slides:\n  https://docs.google.com/presentation/d/1y7YnAdnh5WY59g8oIGTsj8sLQ5KXgoV7uUCBkxcTU88/edit?usp=sharing[Under the hood of serverless Jenkins. Jenkinsfile Runner]\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fjenkinsfile-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fjenkinsfile-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fjenkinsfile-runner/lists"}