This is a Gradle plugin for building Jenkins plugins, written in Groovy or Java.
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.
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.
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.
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'
}
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.
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:
apiimplementationruntimeOnlyjenkinsServer
Jenkins starts up with these system properties set to true:
stapler.tracestapler.jelly.noCachedebug.YUIhudson.Main.development
Each can be overridden as described in the Customizing Further section below.
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)
}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'
}
}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
Any additional dependencies for the server task's classpath can be added to the jenkinsServerRuntimeOnly
configuration. This can be useful for alternative logging implementations.
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.
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)
}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.
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.
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.
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.
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.
Here are some real world examples of Jenkins plugins using the Gradle JPI plugin: