NOTE The Job DSL Plugin is currently seeking co-maintainers. This does not mean that it's unmaintained right now, but that stepping up to help support this plugin would help long-term health of this project.
Jenkins is a wonderful system for managing builds, and people love using its UI to configure jobs. Unfortunately, as the number of jobs grows, maintaining them becomes tedious, and the paradigm of using a UI falls apart. Additionally, the common pattern in this situation is to copy jobs to create new ones, these "children" have a habit of diverging from their original "template" and consequently it becomes difficult to maintain consistency between these jobs.
The Job DSL plugin attempts to solve this problem by allowing jobs to be defined in a programmatic form in a human readable file. Writing such a file is feasible without being a Jenkins expert as the configuration from the web UI translates intuitively into code.
The job configuration above can be generated from the following code.
Job DSL was one of the first popular plugins for Jenkins which allows managing configuration as code and many other plugins dealing with this aspect have been created since then, most notably the Jenkins Pipeline and Configuration as Code plugins. It is important to understand the differences between these plugins and Job DSL for managing Jenkins configuration efficiently.
The Pipeline plugins support implementing and integrating continuous delivery pipelines via the Pipeline DSL. While it is possible to use Job DSL to create complex pipelines using freestyle jobs in combination with many plugins from the Jenkins ecosystem, creating and maintaining these pipeline, including generating jobs for individual SCM branches and possibly running steps in parallel to improve build performance, poses a significant challenge. Jenkins Pipeline is often the better choice for creating complex automated processes. Job DSL can be used to create Pipeline and Multibranch Pipeline jobs. Do not confuse Job DSL with Pipeline DSL, both have their own syntax and scope of application.
The Configuration as Code plugin can be used to manage the global system configuration of Jenkins. It comes with an integration for Job DSL to create an initial set of jobs.
First, start a Jenkins instance with the Job DSL plugin installed.
Then create a freestyle project named "seed".
Add a "Process Job DSLs" build step and paste the script below into the "DSL Script" field.
shell('echo Hello World!')
When running Jenkins on Windows, replace the
shell step by a
batchFile('echo Hello World!')
Save the configuration, start a build and inspect the console output.
Started by user admin
Running as SYSTEM
Building in workspace /var/jenkins_home/workspace/seed
Processing provided DSL script
The seed job has generated the "example" job. Verify the result on the job's configuration page.
The complete DSL API reference is available in your Jenkins installation at
https://your.jenkins.installation/plugin/job-dsl/api-viewer/index.html. You can find links to the API reference on the seed job page and the Job DSL build step.
A limited sub-set of the API reference is available online at https://jenkinsci.github.io/job-dsl-plugin/. But be aware that this does not show all API that is available in your Jenkins installation because a lot of the documentation is generated at runtime by introspecting the plugins that have been installed.
Jenkins saves the configuration of each job in a XML file. The Job DSL plugin is in principle a generator for these XML files, translating the DSL code into XML. If a configuration option is not available in the high-level DSL, it is possible to generate the XML directly using a Configure Block. Use the Job DSL Playground to create and test your configure blocks. Please note that the playground only supports the DSL API that is available in the online API Reference.
Find the complete documentation on the Wiki.
Use the Issue Tracker for reporting bugs and making feature requests. Select the
job-dsl-plugin component when searching or creating issues.
Please use the mailing list to provide feedback.