AOEpeople/gradle-jenkins-job-dsl-plugin

= Gradle Job DSL support plugin

This plugin provides some support tasks for maintaining a https://github.com/jenkinsci/job-dsl-plugin[Jenkins Job DSL Script] repository/project.

It it is inspired by the https://github.com/sheehan/job-dsl-gradle-example[Job DSL Gradle Example] and tries to create a plugin for automatically applying the functionality of it

== Features

Local tests of DSL scripts Ensures DSL scripts execute without error Ensures DSL script file names are valid Supports external Job DSL extensions from Jenkins plugins Supports the Generated DSL feature
Local generation of Jenkins config XML files for debugging
Support for external library dependencies for use in your DSL scripts

== Applying the plugin

Using the Plugin DSL:

[source,gradle] .build.gradle

plugins { id 'com.aoe.jenkins-job-dsl' version '2.9.0' }

or by defining a buildscript dependency:

[source,gradle] .build.gradle

buildscript { repositories { maven { url "https://plugins.gradle.org/m2/" } } dependencies { classpath "gradle.plugin.gradle-jenkins-job-dsl-plugin:jenkins-job-dsl-gradle-plugin:2.9.0" } }

apply plugin: "com.aoe.jenkins-job-dsl"

== Configuration

[source,gradle] .build.gradle

dependencies { // Example for using additional Jenkins plugins that provide their own // Job DSL support or to use them with the Generated DSL feature: jenkinsPlugin 'com.aoe.jenkins:scm-push-trigger:1.1.0'

// for special cases: declare a Jenkins plugin as file dependency:
jenkinsPlugin files('plugins/my-jenkins-plugin.jpi')

// Example for using external libraries in the DSL scripts themselves:
compile 'com.google.guava:guava:18.0'

}

jobDsl { // Base directory where the DSL scripts reside sourceDir 'src/jobs'

// Aditional non-DSL-script resources needed from the DSL scripts
resourceDir 'src/configs'

// Version of Job DSL you want to use
version = '1.76' // default

// By default jcenter and jenkins-public are added as repositories
// If you don't like this set it to false
addRepositories = true // default

}

== Supposed Project Structure

Put your DSL scripts into a directory under root like e.g. src/jobs.

If you have additional files that are not DSL scripts (like config) put them into their own base dir. A good choice is src/configs.

Then add these base dirs to the `jobDsl` section in the `build.gradle`: [source,gradle]

jobDsl { sourceDir 'src/jobs' resourceDir 'src/configs' }

It is possible to have multiple sourceDirs and resourceDirs.

== Additional libraries for use in scripts

You can use additional libraries by simply declaring them as a dependency in the build.gradle:

[source,gradle]

dependencies { compile 'com.aoe.groovy:groovy-guava:1.2.2' }

There is a task libs that copies all compile dependencies into the lib folder in the base dir (so put that into .gitignore).

This should be configured as an additional classpath in the seeder job in Jenkins (e.g. lib/*.jar) - see below.

== Usage / Tasks

gradlew build - Compile code in src/main/groovy, execute (job-dsl) tests and copy compile dependencies into lib folder (calls libs task)
gradlew jobDslTest - Executes all DSL scripts to ensure no error. If everything is fine Gradle will say BUILD SUCCESSFUL. Otherwise open the test report from build/reports/test/index.html. The generated config xml files are located in build/debug-xml/<jobs|views> for inspection
gradlew libs - will copy all compile dependencies into the lib folder at the project root

== Jenkins Seeder Job Configuration

This is the recommended configuration of the seeder job on Jenkins. Adapt where needed. For a general introduction refer to the https://github.com/jenkinsci/job-dsl-plugin/wiki/Tutorial---Using-the-Jenkins-Job-DSL[tutorial at the Job DSL site]

First configure a Invoke Gradle script step with the tasks clean build. This will build everything, run the tests and download additional libraries (if used) to the local lib directory.

Next add a step Process Job DSLs. Configure it for using the DSL scripts in your repo (Look on filesystem). If you store them like in the above example in src/jobs configure the step for using src/jobs/\**/*.groovy.

In the Advanced section you should set up an additional classpath to include your (optional) local support code and / or libraries: