README.adoc

Gradle Job DSL support plugin

This plugin provides some support tasks for maintaining a Jenkins Job DSL Script repository/project.

It it is inspired by the 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:

build.gradle

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

or by defining a buildscript dependency:

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

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:

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:

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 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:

build/classes/main
lib/*.jar