{"id":14008426,"url":"https://github.com/jenkinsci/custom-war-packager","last_synced_at":"2025-07-24T03:32:49.452Z","repository":{"id":39749147,"uuid":"126665656","full_name":"jenkinsci/custom-war-packager","owner":"jenkinsci","description":"Custom Jenkins WAR packager for Jenkins","archived":false,"fork":false,"pushed_at":"2023-11-20T20:59:47.000Z","size":539,"stargazers_count":86,"open_issues_count":46,"forks_count":68,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-08-25T00:42:08.793Z","etag":null,"topics":["docker-image","hacktoberfest","java","jenkins","jenkinsfile-runner","packaging","packaging-tool"],"latest_commit_sha":null,"homepage":"https://jenkins.io/blog/2018/10/16/custom-war-packager/","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.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"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}},"created_at":"2018-03-25T04:50:40.000Z","updated_at":"2024-05-15T22:53:58.000Z","dependencies_parsed_at":"2024-01-31T09:31:04.723Z","dependency_job_id":null,"html_url":"https://github.com/jenkinsci/custom-war-packager","commit_stats":{"total_commits":292,"total_committers":28,"mean_commits":"10.428571428571429","dds":0.3253424657534246,"last_synced_commit":"a7c94fa271ca7084acad725f4799944573a65dbf"},"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fcustom-war-packager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fcustom-war-packager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fcustom-war-packager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jenkinsci%2Fcustom-war-packager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jenkinsci","download_url":"https://codeload.github.com/jenkinsci/custom-war-packager/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227410642,"owners_count":17774779,"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":["docker-image","hacktoberfest","java","jenkins","jenkinsfile-runner","packaging","packaging-tool"],"created_at":"2024-08-10T11:01:39.866Z","updated_at":"2024-11-30T19:31:06.750Z","avatar_url":"https://github.com/jenkinsci.png","language":"Java","funding_links":[],"categories":["Java"],"sub_categories":[],"readme":"Jenkins Custom WAR Packager\n===\n\n![GitHub release](https://img.shields.io/github/release/jenkinsci/custom-war-packager?label=Stable%20release)\n![GitHub release](https://img.shields.io/github/release-pre/jenkinsci/custom-war-packager?label=2.0%20Alpha)\n\n| WARNING: This page documents the 2.x version which is in alpha state now. The new baseline includes incompatible changes in the YAML configuration file format. If you use Custom WAR Packager 1.x, see [the 1.x branch](https://github.com/jenkinsci/custom-war-packager/tree/1.x). |\n| --- |\n\nCustom WAR Packager (CWP) allows building ready-to-fly Jenkins packages using a YAML specification.\nThe tool can produce Docker images, WAR files, and [Jenkinsfile Runner](https://github.com/jenkinsci/jenkinsfile-runner) docker images (aka single-shot Jenkins masters).\nThese bundles may include Jenkins core, plugins, extra libraries, and self-configuration via [Groovy Hook Scripts](https://wiki.jenkins.io/display/JENKINS/Groovy+Hook+Script)\nor [Configuration-as-Code Plugin](https://github.com/jenkinsci/configuration-as-code-plugin) YAML files.\n\nSee [this blog post](https://jenkins.io/blog/2018/10/16/custom-war-packager/) for more information.\n\n### Demo\n\n* [Jenkins WAR - all latest](./demo/all-latest-core) - bundles master branches for core and some key libraries/modules\n* [Jenkins WAR - all latest with Maven](./demo/all-latest-core-maven) - same as a above, but with Maven\n* [External Task Logging to Elasticsearch](./demo/external-logging-elasticsearch) -\nruns External Logging demo and preconfigures it using System Groovy Hooks.\nThe demo is packaged with Docker, and it provides a ready-to-fly Docker Compose package.\n* [Configuration as Code](./demo/casc) - configuring WAR with \n[Configuration-as-Code Plugin](https://github.com/jenkinsci/configuration-as-code-plugin) via YAML\n* [Core components build](./demo/stapler) - demonstrates how to modify core components (libraries, modules)\n* [Custom WAR Packager CI Demo](https://github.com/oleg-nenashev/jenkins-custom-war-packager-ci-demo) - Standalone demo with an integrated CI flow\n* [Jenkinsfile Runner](./demo/jenkinsfile-runner) - Packaging of Docker image for Jenkinsfile Runner\n* [Custom Jenkins distribution formula for the Chinese users](https://github.com/jenkins-zh/docker-zh) - Build your own Jenkins automatically\n\n### Usage\n\nThe tool offers a CLI interface and a Maven Plugin wrapper.\n\n#### CLI\n\nYou can find the binary file from [here](https://repo.jenkins-ci.org/list/releases/io/jenkins/tools/custom-war-packager/custom-war-packager-cli/). \nFor the CLI use case, you should pick up a jar file with dependencies.\n\n```shell\njava -jar custom-war-packager-cli.jar -configPath=mywar.yml -version=1.0-SNAPSHOT -tmpDir=tmp\n```\n\nAfter the build the generated WAR file will be put to `tmp/output/target/${artifactId}.war`.\n\nTo run the tool in a demo mode with [this config](./custom-war-packager-cli/src/main/resources/io/jenkins/tools/warpackager/cli/config/sample.yml), use the following command:\n\n```shell\njava -jar war-packager-cli.jar -demo\n```\n\nInvoke the tool without options to get a full CLI options list.\n\n#### Maven\n\nMaven plugin runs the packager and generates the artifact.\nThe artifact will be put to \"target/custom-war-packager-maven-plugin/output/target/${bundle.artifactId}.war\"\nand added to the project artifacts.\n\n```xml\n  \u003cbuild\u003e\n    \u003cplugins\u003e\n      \u003cplugin\u003e\n        \u003cgroupId\u003eio.jenkins.tools.custom-war-packager\u003c/groupId\u003e\n        \u003cartifactId\u003ecustom-war-packager-maven-plugin\u003c/artifactId\u003e\n        \u003cversion\u003e@project.version@\u003c/version\u003e\n        \u003cexecutions\u003e\n          \u003cexecution\u003e\n            \u003cphase\u003epackage\u003c/phase\u003e\n            \u003cgoals\u003e\n              \u003cgoal\u003ecustom-war\u003c/goal\u003e\n            \u003c/goals\u003e\n            \u003cconfiguration\u003e\n              \u003cconfigFilePath\u003espotcheck.yml\u003c/configFilePath\u003e\n              \u003cwarVersion\u003e1.1-SNAPSHOT\u003c/warVersion\u003e\n            \u003c/configuration\u003e\n          \u003c/execution\u003e\n        \u003c/executions\u003e\n      \u003c/plugin\u003e\n    \u003c/plugins\u003e\n  \u003c/build\u003e\n\n```\n\nNote that this plugin invokes Maven-in-Maven, \nand that it won't pass build options to the plugin.\nConfiguration file can be used to configure the downstream builder.\n\n#### Prerequisites\n\n* Maven 3.5.0 or above\n* Java 8\n* Git (if any Git sources are defined)\n\nCustom WAR Packager offers a [Docker Image](./packaging/docker-builder/README.md) which bundles all the required tools.\n\n#### Configuration file\n\nExample:\n\n```yaml\nbundle:\n  groupId: \"io.github.oleg-nenashev\"\n  artifactId: \"mywar\"\n  description: \"Just a WAR auto-generation-sample\"\n  vendor: \"Jenkins project\"\nbuildSettings:\n  docker:\n    base: \"jenkins/jenkins:2.121.1\"\n    tag: \"jenkins/demo-external-task-logging-elk\"\n    build: true\nwar:\n  groupId: \"org.jenkins-ci.main\"\n  artifactId: \"jenkins-war\"\n  source:\n    version: 2.107\nplugins:\n  - groupId: \"org.jenkins-ci.plugins\"\n    artifactId: \"matrix-project\"\n    source:\n      version: 1.9\n  - groupId: \"org.jenkins-ci.plugins\"\n    artifactId: \"durable-task\"\n    source:\n      git: https://github.com/jglick/durable-task-plugin.git\n      branch: watch-JENKINS-38381\n  - groupId: \"org.jenkins-ci.plugins.workflow\"\n    artifactId: \"workflow-durable-task-step\"\n    source:\n      git: https://github.com/jglick/workflow-durable-task-step-plugin.git\n      commit: 6c424e059bba90fc94a9c1e87dc9c4a324bfef26\n  - groupId: \"io.jenkins\"\n    artifactId: \"configuration-as-code\"\n    source:\n      version: 0.11-alpha-rc373.933033f6b51e\nlibPatches:\n  - groupId: \"org.jenkins-ci.main\"\n    artifactId: \"remoting\"\n    source:\n      git: https://github.com/jenkinsci/remoting.git\nsystemProperties: {\n     jenkins.model.Jenkins.slaveAgentPort: \"50000\",\n     jenkins.model.Jenkins.slaveAgentPortEnforce: \"true\"}\ngroovyHooks:\n  - type: \"init\"\n    id: \"initScripts\"\n    source: \n      dir: scripts\ncasc:\n  - id: \"jcasc-config\"\n    source:\n      dir: jenkins.yml\n```\n\nThere are more options available.\nSee the linked demos and the automated tests for examples.\n\nPlease note that given to the build workspace being defaulted to \"/build\", the Jenkinsfile-runner version used must be at least 1.0-beta-7.\n\n#### Build multi-platform images\n[Docker Buildx](https://docs.docker.com/buildx/working-with-buildx/) provides the ability to build a multi-platform image.\n\nSimply you can follow three steps to build a multi-platform image:\n1. Enable CLI experimental features of you docker daemon.\n2. Create a appropriate driver via `docker buildx create --use`.\n3. Set it in the YAML config file. Basically, you need to add `buildx` and `platform`.\n\nExample:\n\n```\nbuildSettings:\n  docker:\n    base: \"jenkins/jenkins:2.121.1\"\n    tag: \"jenkins/demo-external-task-logging-elk\"\n    platform: linux/amd64,linux/arm64\n    output: push\n    buildx: true\n    build: true\n```\n\n#### BOM support\n\nThe plugin supports Bill of Materials (BOM), described in\n[JEP-309](https://github.com/jenkinsci/jep/tree/master/jep/309), as an input.\n\nIf BOM is defined, Custom WAR Packager will load plugin and component dependencies\nfrom there. In case we want BOM to specify the core version, the `bomIncludeWar` flag must be set to `true`.\nThe example below takes the input from BOM and produces custom WAR and Docker packages.\n\n```yaml\nbundle:\n  groupId: \"io.jenkins.tools.war-packager.demo\"\n  artifactId: \"bom-demo\"\nbuildSettings:\n  bom: bom.yml\n  bomIncludeWar: true\n  environment: aws\n  docker:\n    base: \"jenkins/jenkins:2.121.2\"\n    tag: \"jenkins/cwp-bom-demo\"\n    build: true\n```\n\nAn example of such configuration is available\n[here](https://github.com/jenkinsci/artifact-manager-s3-plugin/pull/20).\n\n#### Plugins from POM\n\nIn order to simplify packaging for development versions,\nit is possible to link Custom War Packager to the POM file\nso that it takes plugins to be bundled from there.\n\nIf the `pom` option is set, all dependencies will be added, including test ones.\nThe current parent will be also bundled unless the `pomIgnoreRoot` flag is set.\n\n```yaml\nbundle:\n  groupId: \"io.jenkins.tools.war-packager.demo\"\n  artifactId: \"pom-input-demo\"\nbuildSettings:\n  pom: pom.xml\n  pomIgnoreRoot: true\n  pomIncludeWar: true\nwar:\n  groupId: \"org.jenkins-ci.main\"\n  artifactId: \"jenkins-war\"\n  source:\n    version: 2.121.1\n```\n\nIn the same way as BOM does, we can specify the core version from the pom file.\nIf the global flag `pomIncludeWar` is `true` and the pom sets the `jenkins-war.version`, the `jenkins.version` property or it contains a dependency on\n`org.jenkins-ci.main:jenkins-core` or `org.jenkins-ci.main:jenkins-war` the war section in yml file \nwill be omitted. Consequently, if the flag is set to `true` and the pom file does not configure the core, then the build fails.\n\nExample is available [here](./demo/artifact-manager-s3-pom).\n\n### Plugin information providers\n\nCustom WAR packager uses plugin information caching for some cases,\ne.g. for deciding whether a dependency is a plugin in pom.xml inputs.\nRight now there are 2 supported information sources: a Jenkins Update Center and a Maven repo.\n\n#### Update Center Information provider\n\nThe mode was introduced in Custom WAR Packager `2.0.0`,\nand this is a default mode in the tool.\n\n  * Plugin information is retrieved from Jenkins update centers\n  * Default update center: http://updates.jenkins.io/update-center.json\n  * Custom update center URL can be set using the `updateCenterUrl` flag in `buildSettings`\n  * Advanced configurations (e.g. proxy configuration) are not available for this mode at the moment\n\n#### Maven Repo Information provider\n\nInformation is retrieved from Maven repositories,\nand hence it allows installing unreleased or blacklisted plugins which are not available through update centers.\n`pomUseMavenPluginInfoProvider: true` in `buildSettings` can be set to enable this mode.\n\n  * The mode caches information about plugins in the Maven repo\n  * The mode is not reliable when used outside clean build environments,\n    because false positive and false negative decisions may be cached\n    in the case of infrastructure issues\n  * This mode is not recommended for most of the cases.\n    Use at your own risk.\n\n```yaml\nbuildSettings:\n  pom: pom.xml\n  pomUseMavenPluginInfoProvider: true\n  pomIgnoreRoot: true\n```\n\nBefore Custom WAR Packager `2.0.0`, this provider was used by default.\nBuilds using this version may need an update if they rely on custom update centers or unreleased/blacklisted plugins.\n\n### Advanced features\n\nFeatures:\n\n* Rebuilding Jenkins core with custom dependencies (e.g., Remoting or Stapler)\n* Adding extra libraries to the Jenkins core so that they can be used in extensions\n\n### Limitations\n\nCurrently, the tool is in the alpha state.\nIt has some serious limitations:\n\n* All built artifacts with Git source are being installed to the local repository\n  * Versions are unique for every commit, so beware of local repo pollution\n* System properties work only for a custom `jenkins.util.SystemProperties` class defined in the core\n  * Use Groovy Hook Scripts if you need to set up other system properties\n* `libPatches` steps bundles only a specified JAR file, but not its dependencies\nDependencies need to be explicitly packaged as well if they change compared to the base WAR file\n  * `libExcludes` can be used to remove dependencies which are not required anymore\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fcustom-war-packager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjenkinsci%2Fcustom-war-packager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjenkinsci%2Fcustom-war-packager/lists"}