Jenkins : Gradle JPI Plugin

Introduction

It has long been possible to build Jenkins plugins using Maven, but now you can build and release your Java and Groovy plugins using Gradle.

Requirements

• Gradle 2.8
• Your plugin must be built against a Jenkins core version of 1.420 or later, due to the Gradle plugin relying on changes which were made to the annotation handling around that time.

Setup

Once you've got Gradle installed, create your plugin project. The plugin project's directory should be named "foo-plugin" or "foo", where "foo" is the artifact name for the plugin. In the build.gradle for the plugin, place the following at the top:

plugins {
  id "org.jenkins-ci.jpi" version "0.16.0"
}

group = "org.jenkins-ci.plugins"
version = "0.0.1-SNAPSHOT"    // Or whatever your version is.
description = "A description of your plugin"

jenkinsPlugin {
    coreVersion = "1.420"                                               // Version of Jenkins core this plugin depends on.
    displayName = "Hello World plugin built with Gradle"                // Human-readable name of plugin.
    url = "http://wiki.jenkins-ci.org/display/JENKINS/SomePluginPage"   // URL for plugin on Jenkins wiki or elsewhere.
    gitHubUrl = "https://github.com/jenkinsci/some-plugin"              // Plugin URL on GitHub. Optional.
    shortName = "hello-world"                                           // Plugin ID, defaults to the project name without trailing '-plugin'

    // The developers section is optional, and corresponds to the POM developers section.
    developers {
        developer {
            id "abayer"
            name "Andrew Bayer"
            email "andrew.bayer@gmail.com"
        }
    }
}

Make sure any additional repositories you need are defined after the jenkinsPlugin section, or artifact resolution may take a long time.

Usage

Building

To build, run gradle jpi. This will create a .hpi file in the build/libs directory in your plugin project directory.

Testing

To run all unit tests, run gradle test. Unlike with Maven, the tests will not be automatically run when building the plugin via gradle jpi, or when releasing via gradle publish.

To spin up a Jenkins instance with this plugin installed for manual testing, run gradle server. The Jenkins instance will be available on port 8080 on your localhost. The HTTP port can be changed with the jenkins.httpPort project or system property, e.g. gradle server -Djenkins.httpPort=8082.

To deploy your plugin to your local Maven repository, run gradle publishToMavenLocal.

Debugging

It is possible to attach a remote debugger to the Jenkins instance started by gradle server. The GRADLE_OPTS environment variable must be used to configure the JVM debug options.

$ export GRADLE_OPTS=-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005
$ ./gradlew server

Releasing

The Gradle JPI plugin does not provide an automated release with Gradle, so you will need to make sure your version is not a SNAPSHOT version manually. It is recommended that you check in your build.gradle file with your release version, tag it with foo-plugin-0.0.1, where foo is your plugin's name, and 0.0.1 is your release version. You should then push that tag to GitHub.

Once you have updated the version and tagged the tree, you can release by running gradle clean publish. This will build the plugin and deploy it to the Jenkins Maven repository for inclusion in the update center. The Gradle JPI plugin will look for your Jenkins Maven repository credentials in the file ~/.jenkins-ci.org where it expects to find:

userName=yourusername
password=yourpassword

Dependencies on other Jenkins Plugins

If your plugin depends on other Jenkins plugins you can specify the dependencies in the following way:

dependencies {
    jenkinsPlugins 'org.jenkinsci.plugins:git:1.1.15@jar'
    optionalJenkinsPlugins 'org.jenkins-ci.plugins:ant:1.2@jar'
    jenkinsTest 'org.jenkins-ci.main:maven-plugin:1.480@jar'
}

Adding the dependency to the jenkinsPlugins configuration will make all classes available during compilation and also add the dependency to the manifest of your plugin. To define an optional dependency on a plugin then use the optionalJenkinsPlugins configuration and to use a plugin only for testing, add a dependency to the jenkinsTest configuration.

Note that you must use the artifact only notation (append @jar if you're using the semicolon notation as in the example or specify ext: 'jar' if you're using the map-style notation).

Examples

• The Job DSL plugin is built with Gradle.
• You can also clone the Hello World plugin and copy in the example build.gradle from the gradle-jpi-plugin's doc directory, and build it.
• simple-scm-plugin: A simple SCM skeleton plugin you can build with Gradle 2.9, very minimalistic, no real functionality.

Changelog

See CHANGELOG.md.

Source Control and Bug Reporting

The source for the gradle-jpi-plugin is in GitHub, at https://github.com/jenkinsci/gradle-jpi-plugin.

If you run into bugs or have improvements to suggest, you can open an issue at the Jenkins JIRA. Make sure to set the component to gradle-jpi-plugin. You can also review open issues.