{"id":18542173,"url":"https://github.com/heremaps/gradle-jenkins-jobdsl-plugin","last_synced_at":"2025-07-11T00:08:46.601Z","repository":{"id":71903398,"uuid":"93070513","full_name":"heremaps/gradle-jenkins-jobdsl-plugin","owner":"heremaps","description":"A plugin for Gradle to manage Jenkins Job DSL projects.","archived":false,"fork":false,"pushed_at":"2019-09-18T15:47:02.000Z","size":582,"stargazers_count":53,"open_issues_count":17,"forks_count":8,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-10T11:50:34.479Z","etag":null,"topics":["gradle","jenkins","jenkins-job-dsl"],"latest_commit_sha":null,"homepage":"https://plugins.gradle.org/plugin/com.here.jobdsl","language":"Groovy","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/heremaps.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-01T15:12:24.000Z","updated_at":"2024-08-01T14:25:45.000Z","dependencies_parsed_at":"2023-07-07T18:04:30.995Z","dependency_job_id":null,"html_url":"https://github.com/heremaps/gradle-jenkins-jobdsl-plugin","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/heremaps/gradle-jenkins-jobdsl-plugin","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fgradle-jenkins-jobdsl-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fgradle-jenkins-jobdsl-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fgradle-jenkins-jobdsl-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fgradle-jenkins-jobdsl-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/heremaps","download_url":"https://codeload.github.com/heremaps/gradle-jenkins-jobdsl-plugin/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/heremaps%2Fgradle-jenkins-jobdsl-plugin/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264696427,"owners_count":23650936,"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":["gradle","jenkins","jenkins-job-dsl"],"created_at":"2024-11-06T20:07:38.226Z","updated_at":"2025-07-11T00:08:46.588Z","avatar_url":"https://github.com/heremaps.png","language":"Groovy","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gradle Jenkins Job DSL Plugin\n\n| Linux | Windows |\n| :---- | :------ |\n[ ![Linux build status][1]][2] | [![Windows build status][3]][4] |\n\n[1]: https://travis-ci.com/heremaps/gradle-jenkins-jobdsl-plugin.svg?branch=master\n[2]: https://travis-ci.com/heremaps/gradle-jenkins-jobdsl-plugin\n[3]: https://ci.appveyor.com/api/projects/status/37g184qui7ityfw2/branch/master?svg=true\n[4]: https://ci.appveyor.com/project/heremaps/gradle-jenkins-jobdsl-plugin/branch/master\n\nThis is a plugin to manage Jenkins [Job DSL](https://wiki.jenkins-ci.org/display/JENKINS/Job+DSL+Plugin) projects in a\nGradle project.\n\n## Contents\n\n- [Usage](#usage)\n    - [Apply Plugin](#apply-plugin)\n    - [How does it work](#how-does-it-work)\n    - [Writing Job DSL Scripts](#writing-job-dsl-scripts)\n        - [Helper Classes](#helper-classes)\n        - [Job Builders](#job-builders)\n        - [Thirdparty Libraries](#thirdparty-libraries)\n    - [Generate XML](#generate-xml)\n    - [Upload Jobs to Jenkins](#upload-jobs-to-jenkins)\n    - [Configure Servers](#configure-servers)\n    - [Seed Job](#seed-job)\n    - [Custom Configuration](#custom-configuration)\n    - [Filter Jobs](#filter-jobs)\n    - [Generated DSL and Job DSL extensions](#generated-dsl-and-job-dsl-extensions)\n- [Development](#development)\n    - [Build the Plugin](#build-the-plugin)\n    - [Test the Plugin](#test-the-plugin)\n    - [Debugging the DSL tasks](#debugging-the-dsl-tasks)\n    - [Contributing](#contributing)\n- [Examples](#examples)\n- [Hints](#hints)\n- [Credits](#credits)\n- [License](#license)\n\n## Usage\n\nThe plugin can be used to locally generate XML files for the jobs and to upload the generated jobs to a Jenkins\ninstance.\n\n### Apply Plugin\n\nTo apply the plugin you need to add the necessary Maven repositories to the build script. The minimal build script looks\nlike this:\n\n```groovy\nbuildscript {\n    ext.jenkinsJobdslPluginVersion = '3.7.0'\n\n    repositories {\n        maven {\n            url 'https://plugins.gradle.org/m2'\n        }\n\n        maven {\n            url 'https://repo.jenkins-ci.org/releases/'\n        }\n    }\n\n    dependencies {\n        classpath(\"com.here.gradle.plugins:gradle-jenkins-jobdsl-plugin:${jenkinsJobdslPluginVersion}\") {\n            // Exclude unneeded transitive dependencies that can cause dependency resolution issues.\n            exclude(module: 'bootstrap')\n            exclude(module: 'groovy-all')\n            exclude(module: 'org-netbeans-insane')\n\n            // Exclude unneeded transitive dependencies on XML libraries that can break the generation of config files.\n            // See: https://issues.jenkins-ci.org/browse/JENKINS-35638\n            exclude(module: 'xalan')\n            exclude(module: 'xercesImpl')\n        }\n    }\n}\n\napply plugin: 'com.here.jobdsl'\n\nrepositories {\n    maven {\n        url 'https://plugins.gradle.org/m2'\n    }\n}\n\ndependencies {\n    compile 'org.codehaus.groovy:groovy-all:2.4.15'\n\n    compile(\"com.here.gradle.plugins:gradle-jenkins-jobdsl-plugin:${jenkinsJobdslPluginVersion}\") {\n        exclude(module: 'org-netbeans-insane')\n        exclude(module: 'xalan')\n        exclude(module: 'xercesImpl')\n    }\n}\n```\n\n### How does it work\n\nTo come as close as possible to the behaviour of a normal Job DSL\n[seed job](https://github.com/jenkinsci/job-dsl-plugin/wiki/Tutorial---Using-the-Jenkins-Job-DSL#1-creating-the-seed-job)\nthe plugin launches a Jenkins instance in the background and executes the Job DSL scripts inside of this Jenkins. This\nimplementation enables support for the generated DSL and Job DSL extensions as described below.\n\nTo load plugins in this Jenkins instance they have to be added as dependencies to the `jenkinsPlugins` configuration:\n\n```groovy\ndependencies {\n    // Some Job DSL features only work when plugins are installed, for example cloudbees-folder is required\n    // to be able to create folders (https://jenkinsci.github.io/job-dsl-plugin/#path/folder).\n    jenkinsPlugins 'org.jenkins-ci.plugins:cloudbees-folder:6.2.1'\n}\n```\n\nKnown issues with plugins:\n\n* The `org.jenkins-ci.plugins:ws-cleanup` plugin has a dependency on an old version of `jenkins-core`. This adds some\n  XML parser libraries to the classpath which conflict with the XML parser expected by newer Jenkins versions. As\n  `jenkins-core` is provided anyway it should be excluded:\n\n```groovy\njenkinsPlugins('org.jenkins-ci.plugins:ws-cleanup:0.34') {\n    exclude module: 'jenkins-core'\n}\n```\n\n### Writing Job DSL Scripts\n\nBy default all \\*.groovy files from src/jobdsl and its subdirectories are evaluated as Job DSL scripts. You can change\nthe location by configuring the source set:\n\n```groovy\nsourceSets {\n    jobdsl {\n        groovy {\n            srcDirs 'myCustomSrcFolder'\n        }\n    }\n}\n```\n\n#### Helper Classes\n\nYou can add Groovy or Java classes to the respective source directories `src/main/groovy` and `src/main/java` and use\nthose classes in your Job DSL scripts, because they are automatically added to the classpath.\n\n#### Job Builders\n\nThe recommended way to implement job templates are job builder classes. The plugin provides a basic `JobBuilder` class\nthat can be extended to create templates. Below you can find an example of how to create a template that automatically\nenables the timestamp plugin for all jobs that use the template:\n\n```groovy\nimport com.here.gradle.plugins.jobdsl.util.JobBuilder\nimport javaposse.jobdsl.dsl.Job\n\nclass CustomJobBuilder extends JobBuilder {\n\n    CustomJobBuilder(DslFactory dslFactory) {\n        super(dslFactory)\n\n        addDsl {\n            wrappers {\n                timestamps()\n            }\n        }\n    }\n\n}\n```\n\nTo use the template you have to create an instance of your custom job builder class. You can add additional DSL code by\npassing it to the `addDsl` method. The builder will concatenate all closures and execute them in the order they were\nadded when `build` is called. The `JobBuilder` provides convenience methods like `addFreeStyleDsl` or `addMatrixdsl` for\neach job type that optimize IDE support compared to using the generic `addDsl` method. You also have to set the job type\nby calling any of `freestyleJob`, `matrixJob` and so on. These methods optionally take a DSL closure argument for\nconvenience.\n\n```groovy\ndef job = new CustomJobBuilder(\n        dslFactory: this,\n        name: 'MyExampleJob'\n).freeStyleJob {\n\n    description 'My example job'\n\n    steps {\n        shell('Hello World!')\n    }\n}\n\njob.build()\n```\n\n#### Thirdparty Libraries\n\nTo use thirdparty libraries in your Job DSL scripts add them to the dependencies closure of the build script. For\nexample the Job DSL plugin itself is added there to be able to use the `JobBuilder` class. This example shows how to add\nthe Google Guava library:\n\n```groovy\ndependencies {\n    compile localGroovy()\n    compile \"com.here.gradle.plugins:gradle-jenkins-jobdsl-plugin:${jobDslPluginVersion}\"\n    compile 'com.google.guava:guava:19.0'\n}\n```\n\n### Generate XML\n\n```bash\n./gradlew dslGenerateXml\n```\n\nThe XML files will be generated in build/jobdsl/.\n\n### Upload Jobs to Jenkins\n\n```bash\n# Upload jobs to a server without authorization\n./gradlew dslUpdateJenkins --jenkinsUrl=http://localhost:8080/\n\n# Upload jobs to a server with authorization\n./gradlew dslUpdateJenkins --jenkinsUrl=http://localhost:8080/ --jenkinsUser=yourUsername --jenkinsApiToken=yourApiToken\n\n# Do a dry run without changing any jobs\n./gradlew dslUpdateJenkins --jenkinsUrl=http://localhost:8080/ --dryRun\n```\n\n### Configure Servers\n\nYou can configure the different server you use in the build script instead of providing the configuration on the command\nline:\n\n```groovy\njobdsl {\n    servers {\n        localhost {\n            jenkinsUrl = 'http://localhost:8080/'\n        }\n\n        staging {\n            jenkinsUrl = 'http://your.jenkins.url:8080/'\n            jenkinsUser = 'yourUsername'\n            jenkinsApiToken = 'yourApiToken'\n        }\n    }\n}\n```\n\nTo use this configuration you have to select the server on the command line. You can override the configuration on the\ncommand line, e.g. when you don't want to put your credentials in the build script:\n\n```bash\n# Use the localhost configuration\n./gradlew dslUpdateJenkins --server=localhost\n\n# Override the user and API token from the configuration\n./gradlew dslUpdateJenkins --server=staging --jenkinsUser=yourOtherUsername --jenkinsApiToken=yourOtherApiToken\n```\n\nIf you want each team member to use their own credentials the\n [gradle-credentials-plugin](https://github.com/etiennestuder/gradle-credentials-plugin) provides a nice way to let the\nteam members store their credentials encrypted without having to put them in the build script or on the command line\nevery time.\n\n### Seed Job\n\nTo create a seed job similar to the Job DSL seed jobs (see\n[Using Job DSL](https://github.com/jenkinsci/job-dsl-plugin/wiki/Tutorial---Using-the-Jenkins-Job-DSL)) just create a\nfreestyle job and run the Gradle command in a shell build step. Note that this will still use the REST API instead of\nthe internal Jenkins API to create the jobs.\n\nSince version 1.0.28 you can use the `GroovySeedJobBuilder` to create a seed job that runs in a System Groovy build step\ninstead of using the REST API. This provides much better performance.\n\n### Custom Configuration\n\nThere are use cases where you want to change a part of your job configuration on the command line. For example you might\nwant to create all jobs disabled on your localhost, and only enable them by default on your production Jenkins instance.\nFor this the plugin supports a configuration map that is forwarded to the Job DSL scripts. The example below shows how\nto add a parameter to enable or disable all jobs:\n\n```groovy\njobdsl {\n    configuration = [\n        disableJobs: project.properties['disableJobs']?.toBoolean() ?: false\n    ]\n}\n```\n\nThe values from the configuration map can be accessed from the Job DSL scripts by calling `DslConfig.get('key')`. The\nadapted build method of the `CustomJobBuilder` class looks like this:\n\n```groovy\n@Override\nJob build(Class\u003c? extends Job\u003e jobClass, @DelegatesTo(Job.class) Closure closure) {\n    def job = super.build(jobClass, closure)\n    job.with {\n        disabled(DslConfig.get('disableJobs'))\n    }\n    return job\n}\n```\n\nThe configuration map is forwarded to the DSL scripts by serializing it to JSON, so only put values in it that can\nproperly be serialized and deserialized by the `JsonBuilder` and `JsonSlurper` Groovy classes.\n\nNow you can provide a value for the property on the command line to enable or disable your jobs. You can also provide a\ndefault value for the property in your `gradle.properties` file.\n\n```bash\n./gradlew -PdisableJobs=true dslGenerateXml\n```\n\nYou can also have server specific configuration in the `build.gradle` file which can be accessed by calling\n`DslConfig.get('key')`:\n\n```groovy\njobdsl {\n    servers {\n        localhost {\n            configuration: [ key: 'value' ]\n        }\n    }\n}\n```\n\n### Filter Jobs\n\nTo update only a part of the configured jobs the filter option can be used. It takes a regular expression as argument\nand only job names that match this expression are evaluated:\n\n```bash\n# Generate XML only for job names that contain \"build\"\n./gradlew dslGenerateXml --filter=\".*build.*\"\n\n# Only upload jobs from the folder \"MyFolder\"\n# Note that /.* is put in brackets and made optional with a question mark, this makes sure that also the folder itself\n# is uploaded. You could also use \"^MyFolder.*\", but in this case any item in the folder \"MyFolder2\" would also be\n# uploaded.\n./gradlew dslUpdateJenkins --filter=\"^MyFolder(/.*)?\"\n```\n\n### Generated DSL and Job DSL extensions\n\nJob DSL has built-in support for many Jenkins plugins. Additionally there are two mechanisms that add support for\nplugins which are not directly supported:\n\n1. [Generated DSL](https://github.com/jenkinsci/job-dsl-plugin/wiki/Automatically-Generated-DSL):\n   This method uses annotations to discover configuration endpoints of plugins automatically and generates a DSL for\n   them. This works for many plugins when they use the correct annotations.\n1. [Job DSL Extensions](https://github.com/jenkinsci/job-dsl-plugin/wiki/Extending-the-DSL):\n   Plugins can also define their own DSL which is then available when the plugin is loaded by Jenkins.\n\nBoth mechanisms are supported by the gradle-jenkins-jobdsl-plugin. To use them the plugins have to be added to the\n`jenkinsPlugins` configuration:\n\n```groovy\ndependencies {\n    // This plugin defines a Job DSL extension.\n    jenkinsPlugins 'org.jenkins-ci.plugins:jgiven:0.15.1'\n\n    // This plugin is supported by the generated DSL.\n    jenkinsPlugins 'org.jenkins-ci.plugins:cvs:2.13'\n}\n```\n\n## Development\n\n### Build the Plugin\n\nTo build the plugin execute:\n\n```bash\n# Only build\n./gradlew plugin:assemble\n\n# Publish to local maven repository (version will be 1.0)\n./gradlew plugin:publishToMavenLocal\n```\n\n### Test the Plugin\n\nTo run the tests of the plugin execute:\n\n```bash\n./gradlew plugin:check\n```\n\n### Debugging the DSL tasks\n\nTo debug the tasks `DslGenerateXml` and `DslUpdateJenkins` using IntelliJ follow these steps:\n\n1. Uncomment these two lines in [`AbstractDslTask`](https://github.com/heremaps/gradle-jenkins-jobdsl-plugin/blob/master/plugin/src/main/groovy/com/here/gradle/plugins/jobdsl/tasks/AbstractDslTask.groovy):\n   ```groovy\n   //'-Xdebug',\n   //'-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005'\n   ```\n2. Create a test in `GenerateXmlTest.groovy` or `UpdateJenkinsTest.groovy` with the scenario you want to test (e.g.\n   usage of specific plugins).\n3. Set a breakpoint in the `run` method of `AbstractTaskRunner.groovy`.\n4. Create a remote debug configuration in IntelliJ: `Run` -\u003e `Edit Configurations...` -\u003e `+ Remote`\n5. Run the test on the command line:\n   `./gradlew plugin:functionalTest --tests \"com.here.gradle.plugins.jobdsl.tasks.GenerateXmlTest.name of your test\"`\n6. Start the remote debug configuration in IntelliJ.\n\n### Contributing\n\nContributions to the project are very welcome! Please be aware that you need to sign the\n[HERE CLA](https://cla-assistant.io/heremaps/gradle-jenkins-jobdsl-plugin) if you want to contribute to the project.\n\n## Examples\n\nThe repository contains an example project that demonstrates most features of the plugin. To run it you have to deploy\na build of the plugin to your local Maven repository first, as documented in \"Build the Plugin\" above.\n\n## Hints\n\n### Job DSL Plugin is not required\n\nBecause the gradle-jenkins-jobdsl-plugin can use the\n[Jenkins REST API](https://wiki.jenkins.io/display/JENKINS/Remote+access+API) to upload jobs to Jenkins the\n[Job DSL Plugin](https://wiki.jenkins.io/display/JENKINS/Job+DSL+Plugin) does not have to be installed on the Jenkins\ninstance. This can be useful when you do not have permission to install Jenkins plugins or the plugin cannot be\ninstalled for another reason.\n \n### JobConfigHistory Plugin and seed jobs\n\nIf you use the [JobConfigHistory Plugin](https://wiki.jenkins.io/display/JENKINS/JobConfigHistory+Plugin) in combination\nwith a seed job you should configure retention for history entries in \"Manage Jenkins\" -\u003e \"Configure System\". Otherwise\nyou can quickly get a huge number of history entries which has a very negative impact on seed job performance and\nJenkins performance in general.\n\n## Credits\n\nThe plugin was inspired by the following two projects, many thanks to their creators!\n\n- [gradle-jenkins-plugin](https://github.com/ghale/gradle-jenkins-plugin)\n- [job-dsl-gradle-example](https://github.com/sheehan/job-dsl-gradle-example)\n\n## License\n\nCopyright (c) 2016-2017 HERE Europe B.V.\n\nSee the [LICENSE](LICENSE) file in the root of this project for license details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheremaps%2Fgradle-jenkins-jobdsl-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheremaps%2Fgradle-jenkins-jobdsl-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheremaps%2Fgradle-jenkins-jobdsl-plugin/lists"}