Gradle JPI plugin

This is a Gradle plugin for building Jenkins plugins, written in Groovy or Java.

⚠️ New OSS Plugins Rejected

As of December 2022, new OSS plugins will be rejected by the Jenkins hosting team until hosting requirements are met.

Hosting requirements are well-defined and expected to be a small amount of work, but this is not prioritized. Contributions are welcome. Existing OSS plugins can continue to use this plugin. Plugins not hosted by the Jenkins infra team (internal-only plugins) are not impacted.

Compatibility with Gradle versions

The latest version of the JPI plugin requires Gradle 7.1 or later to make use of modern Gradle APIs.

For Gradle versions 6.3-6.9.x, please use version 0.50.0 of the JPI plugin.

For Gradle versions 6.0-6.2.1, please use version 0.46.0 of the JPI plugin.

For Gradle versions 4.x or 5.x, please use version 0.38.0 of the JPI plugin.

Configuration

Add the following to your build.gradle:

plugins {
  id 'org.jenkins-ci.jpi' version '0.50.0'
}

group = 'org.jenkins-ci.plugins'
version = '1.2.0-SNAPSHOT'
description = 'A description of your plugin'

jenkinsPlugin {
    // version of Jenkins core this plugin depends on, must be 1.420 or later
    jenkinsVersion = '1.420'

    // ID of the plugin, defaults to the project name without trailing '-plugin'
    shortName = 'hello-world'

    // human-readable name of plugin
    displayName = 'Hello World plugin built with Gradle'

    // URL for plugin on Jenkins wiki or elsewhere
    url = 'http://wiki.jenkins-ci.org/display/JENKINS/SomePluginPage'

    // plugin URL on GitHub, optional
    gitHubUrl = 'https://github.com/jenkinsci/some-plugin'
  
    // scm tag eventually set in the published pom, optional
    scmTag = 'v1.0.0'

    // use the plugin class loader before the core class loader, defaults to false
    pluginFirstClassLoader = true

    // optional list of package prefixes that your plugin doesn't want to see from core
    maskClasses = 'groovy.grape org.apache.commons.codec'

    // optional version number from which this plugin release is configuration-compatible
    compatibleSinceVersion = '1.1.0'

    // set the directory from which the development server will run, defaults to 'work'
    workDir = file('/tmp/jenkins')

    // URL used to deploy the plugin, defaults to the value shown
    // the system property 'jpi.repoUrl' can be used to override this option
    repoUrl = 'https://repo.jenkins-ci.org/releases'

    // URL used to deploy snapshots of the plugin, defaults to the value shown
    // the system property 'jpi.snapshotRepoUrl' can be used to override this option
    snapshotRepoUrl = 'https://repo.jenkins-ci.org/snapshots'

    // enable injection of additional tests for checking the syntax of Jelly and other things
    disabledTestInjection = false

    // the output directory for the localizer task relative to the project root, defaults to the value shown
    localizerOutputDir = "${project.buildDir}/generated-src/localizer"

    // disable configuration of Maven Central, the local Maven cache and the Jenkins Maven repository, defaults to true
    configureRepositories = false

    // skip configuration of publications and repositories for the Maven Publishing plugin, defaults to true
    configurePublishing = false

    // plugin file extension, either 'jpi' or 'hpi', defaults to 'hpi'
    fileExtension = 'hpi'

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

    // the licenses section is optional, and corresponds to the POM licenses section
    licenses {
        license {
            name 'Apache License, Version 2.0'
            url 'https://www.apache.org/licenses/LICENSE-2.0.txt'
            distribution 'repo'
            comments 'A business-friendly OSS license'
        }
    }

    // Git based version generation is optional
    gitVersion {
        // Don't fail if changes are not committed (default: false)
        allowDirty = true
        // Customize version format (default: %d.%s where %d is the commit depth, %s the abbreviated sha)
        versionFormat = 'rc-%d.%s'
        // Sanitize the hash according to Jenkins requirements (default: false)  
        sanitize = true 
        // Customize abbreviated sha length (default: 12)
        abbrevLength = 10
        // Customize git root (default: project directory)
        gitRoot = file('/some/external/git/repo')
    }

    // "Incrementals" custom repository (default: https://repo.jenkins-ci.org/incrementals)
    incrementalsRepoUrl = 'https://custom'

    // Enable quality check plugins
    enableSpotBugs()
    enableCheckstyle()
    enableJacoco()
}

Be sure to add the jenkinsPlugin { ... } section before any additional repositories are defined in your build.gradle.

Dependencies on other Jenkins Plugins

If your plugin depends on other Jenkins plugins, you can use the same configurations as in Gradle's java-libary plugin. See the documentation for details on the difference of api and implementation dependencies. For optional dependencies, you can use Gradle's feature variants.

You can define both dependencies to Jenkins plugins and plain Java libraries. The JPI plugin will figure out what you are depending on and process it accordingly (Java libraries will be packaged in the your Jenkins plugin's hpi/jpi file).

The additional jenkinsServer configuration can be used to install extra plugins for the server task (see below).

Examples:

java {
    // define features for 'optional dependencies'
    registerFeature('ant') {
        usingSourceSet(sourceSets.main)
    }
}

dependencies {
    implementation 'org.jenkinsci.plugins:git:1.1.15'
    api 'org.jenkins-ci.plugins:credentials:1.9.4'

    // dependency of the (optional) ant feature
    antImplementation 'org.jenkins-ci.plugins:ant:1.2'

    // dependency for testing only
    testImplementation 'org.jenkins-ci.main:maven-plugin:1.480'

    // addition dependencies for manual tests on the server started with `gradle server`
    jenkinsServer 'org.jenkins-ci.plugins:ant:1.2'
}

Usage

• gradle jpi - Build the Jenkins plugin file, which can then be found in the build directory. The file will currently end in ".hpi".
• gradle publishToMavenLocal - Build the Jenkins plugin and install it into your local Maven repository.
• gradle publish - Deploy your plugin to the Jenkins Maven repository to be included in the Update Center.
• gradle server - Start a local instance of Jenkins with the plugin pre-installed for testing and debugging.

Running Jenkins Locally

The server task creates a hpl, installs plugins, and starts up Jenkins on port 8080. The server runs in the foreground.

Plugins added to any of these configurations will be installed to ${jenkinsPlugin.workDir}/plugins:

• api
• implementation
• runtimeOnly
• jenkinsServer

Default System Properties

Jenkins starts up with these system properties set to true:

• stapler.trace
• stapler.jelly.noCache
• debug.YUI
• hudson.Main.development

Each can be overridden as described in the Customizing Further section below.

Customizing Port

Jenkins starts by default on port 8080. This can be changed with the --port flag or port property.

For example to run on port 7000:

$ ./gradlew server --port=7000

or in build.gradle:

tasks.named('server').configure {
    it.port.set(7000)
}

Customizing Further

The server task accepts a JavaExecSpec that allows extensive customization.

Here's an example with common options:

tasks.named('server').configure {
    execSpec {
        systemProperty 'some.property', 'true'
        environment 'SOME_ENV_VAR', 'HelloWorld'
        maxHeapSize = '2g'
    }
}

Debugging

To start Jenkins in a suspended state with a debug port of 5005, add the --debug-jvm flag:

$ ./gradlew server --debug-jvm

> Task :server
Listening for transport dt_socket at address: 5005

Debug options can be customized by the server task's execSpec action:

tasks.named('server').configure {
    execSpec {
        debugOptions {
            port.set(6000)
            suspend.set(false)
        }
    }
}

$ ./gradlew server --debug-jvm

> Task :server
Listening for transport dt_socket at address: 6000

Additional Server Dependencies

Any additional dependencies for the server task's classpath can be added to the jenkinsServerRuntimeOnly configuration. This can be useful for alternative logging implementations.

Checking for Restricted APIs

Starting with v0.41.0, we now check for using @Restricted types, methods, and fields.

Initially this functionality will warn by default (see #176), but will eventually fail the build. To opt-into failing the build now, add this configuration to build.gradle:

tasks.named('checkAccessModifier').configure {
    ignoreFailures.set(false)
}

checkAccessModifier will only be cached on success if ignoreFailures is false.

Disabling appending timestamp to the SNAPSHOT plugin version

By default, generateJenkinsManifest task appends the current timestamp and the current username to the -SNAPSHOT plugin version. It leads to a non-repeatable outputs that affect the task cacheability.

To opt-out from modifying the -SNAPSHOT plugin version, add this configuration to build.gradle:

tasks.named('generateJenkinsManifest').configure {
    dynamicSnapshotVersion.set(false)
}

Using Git based version

JEP-229 outlines requirements for creating sensible version numbers automatically. The plugin registers a generateGitVersion task that generates a Git based version in a text file (1st line an abbreviated hash, 2nd line the full hash). This version scheme is typically used on ci.jenkins.io by first generating the version and then setting it when building with -Pversion=${versionFile.readLines()[0]}. This works fine as long as no version is set in build.gradle.

See Configuration to customize the generation.

Using Jenkins "incrementals" repository

JEP-305 specifies how to deploy incremental versions. This applies mainly for the ci.jenkins.io infrastructure, for Gradle the logic is defined in https://github.com/jenkins-infra/pipeline-library/blob/master/vars/buildPluginWithGradle.groovy.

For local builds, the plugin defines the https://repo.jenkins-ci.org/incrementals/ repository. The publish task will not publish to this one by default, instead one should call the publish*PublicationToJenkinsIncrementalsRepository task(s) separately (so publishMavenJpiPublicationToJenkinsIncrementalsRepository for the default publication) It's also possible to specify a different repository, see Configuration.

Enabling quality checks

To eventually publish reports to ci.jenkins.io, one can enable SpotBugs, Checkstyle or JaCoCo plugins:

jenkinsPlugin {
    enableSpotBugs()
    enableCheckstyle()
    enableJacoco()
}

When enabled, plugins are configured with sensitive defaults: only xml reports, checkstyle rules default to sun-checks.xml... still the plugins can be configured as usual, see their corresponding docs.

Disabling SHA256 and SHA512 checksums when releasing a plugin

This section applies to the warning:

Cannot upload checksum for module-maven-metadata.xml. Remote repository doesn't support sha-256. Error: Could not PUT 'https://repo.jenkins-ci.org/releases/org/jenkins-ci/plugins/<shortname>/maven-metadata.xml.sha256'. Received status code 403 from server: Forbidden
Cannot upload checksum for module-maven-metadata.xml. Remote repository doesn't support sha-512. Error: Could not PUT 'https://repo.jenkins-ci.org/releases/org/jenkins-ci/plugins/<shortname>/maven-metadata.xml.sha512'. Received status code 403 from server: Forbidden

When performing a release via gradle publish, gradle will automatically try to upload artifacts with SHA 256 and 512 checksums. This is not currently supported in the public artifact repository for Jenkins. To disable this, you can pass a command line argument gradle publish -Dorg.gradle.internal.publish.checksums.insecure or include a gradle.properties file with the line org.gradle.internal.publish.checksums.insecure=true.

Gradle 4+

Note that Gradle 4.0 changed the default layout of the classes folders. Where Gradle 3.x put all classes of groovy and java code into a single directory, Gradle 4 by default creates separate directories for all languages. Unfortunately, this breaks the way SezPoz (the library indexing the Extension annotations) works, meaning that all annotations from java code are effectively ignored.

If you combine java and groovy code and both provide extensions you need to either:

• Use joint compilation, i.e. put your java source files into the groovy source path (src/main/groovy)
• or force Gradle to use the old layout by including something like sourceSets.main.output.classesDir = new File(buildDir, "classes/main") in your build.gradle as a workaround.

Examples

Here are some real world examples of Jenkins plugins using the Gradle JPI plugin:

• Job DSL Plugin
• Selenium Axis Plugin
• Doktor Plugin