gradle-plugin

gradle-plugin copied to clipboard

:imagesdir: images :thumbnail: width=80%,align="center"

= Jenkins Gradle Plugin

image:https://img.shields.io/jenkins/plugin/v/gradle.svg[Jenkins Plugin,link=https://plugins.jenkins.io/gradle] image:https://img.shields.io/github/release/jenkinsci/gradle-plugin.svg?label=changelog[link="https://github.com/jenkinsci/gradle-plugin/releases/latest"] image:https://img.shields.io/jenkins/plugin/i/gradle.svg?color=blue[Jenkins Plugin Installs,link=https://plugins.jenkins.io/gradle] image:https://ci.jenkins.io/buildStatus/icon?job=Plugins/gradle-plugin/master[Build Status,link=https://ci.jenkins.io/blue/organizations/jenkins/Plugins%2Fgradle-plugin/branches/]

== Description

This plugin adds http://www.gradle.org/[Gradle] Support to Jenkins. http://www.gradle.org/[Gradle] is managed as another tool inside Jenkins (the same way as Ant or Maven), including support for automatic installation and a new build step is provided to execute Gradle tasks.

It also allows detecting https://gradle.com/build-scans/[Build Scans] in arbitrary console logs, for Maven and Gradle builds and display them in the Jenkins UI.

The plugin also allows for injecting Build Scans into both Maven and Gradle builds by setting some environment variables, see link:#_injecting_build_scans[Injecting Build Scans].

In order to release this plugin have a look at link:RELEASING.md[here].

== Configuration

Gradle configuration is performed in the Configure System (before Jenkins 2.0) or Global Tool Configuration (starting in Jenkins 2.0). In both cases these options reside in the Manage Jenkins section.

In the Gradle section provided by this plugin, several installations can be configured:

image::gradle-tool-installation.png[Tool installations,{thumbnail}]

The system provides both automatic installation, which can be performed by directly downloading from the http://www.gradle.org/[Gradle web site], extracting a compressed final or executing some shell commands. Besides, for nodes which already has Gradle installed, the tool can by manually configured, by unchecking the Install automatically checkbox and providing the base path (GRADLE_HOME) of the installation.

== Usage

The Gradle plugin provides an Invoke Gradle script build step.

image::gradle-build-step.png[Build step,{thumbnail}]

The first configuration option is whether to use one of the installation configured in Jenkins (see previous section) of use the https://docs.gradle.org/current/userguide/gradle_wrapper.html[Gradle Wrapper] which is the Gradle-provided mechanism to "embed" the use of a specific Gradle version in a build, installing it if necessary.

Other configuration options include:

• A description to use for the build step.
• Switches (options) to provide to the Gradle execution.
• Tasks to execute (if blanck the defaults tasks of the build will be invoked).
• Path to the build script if different from the root directory of the build.
• Name of the build script if different from build.gradle.

If a https://scans.gradle.com/[Gradle Build Scan] is produced during a build, then a link to it is added to the build page.

image::jenkins-build-scan.png[Build Scan link,width=60%,align="center"]

== Capturing build scans from console log

If you are not using the provided build scan, you can still configure to detect published (Maven or Gradle) https://gradle.com/build-scans/[Build Scans] from the console log. For doing so, go to Build Environment and check Inspect build log for published Gradle build scans.

image::inspect-logs-for-build-scans.png[Inspect build log for Build Scan,{thumbnail}]

If build scans are detected in the console log of a build, a badge will be added to the build page. This works for https://gradle.com/build-scans/[Build Scans] produced by Gradle and Maven builds.

image::jenkins-build-scan.png[Build Scan link,width=60%,align="center"]

== Capturing build scans from Jenkins Pipeline

When using Jenkins pipeline, there is the build step wrapper withGradle which can be used to find the build scans emitted by Gradle builds and show them on the build page. In order to do so, wrap your sh or bat steps which invoke Gradle into withGradle.

For example: [source]

node { withGradle { sh './gradlew build' } }

This causes the shell output to be highlighted and build scan links, which are emitted, are captured. The captured build scan links are then shown on the build page and in the pipeline steps view.

image::pipeline-steps-scan.png[Build scan in pipeline view,{thumbnail}]

There is also the findBuildScans() step, which finds the build scans in the complete log of the pipeline job. The withGradle wrapper should be used instead, since it also deals well with parallel output.

image::find-build-scans.png[Find build scans,{thumbnail}]

== Injecting Build Scans

The plugin can be configured to inject Build Scans into any Gradle or Maven build that's running on the Jenkins server or any of its connected agents.

=== How it works

This feature works by installing scripts and Jars on each agent depending on the environment variable settings.

The feature can be enabled by setting the JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_INJECTION environment variable.

If the JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_PLUGIN_VERSION environment variable is present, injection is activated for Gradle builds. This causes an init script to be installed in the user home of each connected agent. The init script is removed when JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_PLUGIN_VERSION is unset, thus deactivating injection for Gradle builds.

If the JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_EXTENSION_VERSION environment variable is present, injection is activated for Maven builds. This causes the Gradle Enterprise Maven Extension to be installed on each connected agent, and the MAVEN_OPTS environment variable will be modified so that each Maven process will load the extension. The extension is deleted from all agents and the changes to MAVEN_OPTS are reverted when JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_EXTENSION_VERSION is unset.

=== Configuration options

The following table lists all available configuration options.

.General variables |=== |Environment variable|Build Tool|Description

|JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_INJECTION|Both|Enable the feature if set. |JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_URL|Both|The URL of the Gradle Enterprise server to publish Build Scans to. |JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_ALLOW_UNTRUSTED_SERVER|Both|Whether to allow publishing to a server with a self-signed certificate. Defaults to false. |JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_PLUGIN_VERSION|Gradle|Enables injection for Gradle builds and defines which version of the https://plugins.gradle.org/plugin/com.gradle.enterprise[Gradle Enterprise Gradle plugin] to use. |JENKINSGRADLEPLUGIN_CCUD_PLUGIN_VERSION|Gradle|Defines which version of the https://plugins.gradle.org/plugin/com.gradle.common-custom-user-data-gradle-plugin[Gradle Enterprise Gradle plugin] to use. |JENKINSGRADLEPLUGIN_GRADLE_ENTERPRISE_EXTENSION_VERSION|Maven|Enables injection for Maven builds. |JENKINSGRADLEPLUGIN_CCUD_EXTENSION_VERSION|Maven|Defines which version of the https://docs.gradle.com/enterprise/maven-extension[Gradle Enterprise Maven extension] to use. |===

In addition to the variables above you might want to set the GRADLE_ENTERPRISE_ACCESS_KEY variable if you're Gradle Enterprise server requires authentication for publishing Build Scans. Refer to the https://docs.gradle.com/enterprise/gradle-plugin/#via_environment_variable[Gradle Enterprise Gradle plugin manual] and the https://docs.gradle.com/enterprise/maven-extension/#via_environment_variable[Gradle Enterprise Maven Extension manual] for more information.

=== Limitations

• The configuration is based on global environment variables and applies to all builds on the server and all connected agents.
• Injecting Build Scans into Maven builds only works in MAVEN_OPTS is not set.

== Roadmap

• Using the Gradle API for accessing all the Gradle functionalities
• Providing a Maven-like or Ivy-like integration ** Multi-project detection ** Adding automatic tests result path detection ** Listing executed tasks with time execution for each task ** Providing a log for each module in a multi-project

== Release Notes

See the https://github.com/jenkinsci/gradle-plugin/releases[Github releases page].

Old release notes:

=== 1.33 (July 5th 2019)

• Remove support for dry-run plugin https://github.com/jenkinsci/gradle-plugin/pull/72[#72]
• Support detecting build scans in pipeline jobs (https://github.com/jenkinsci/gradle-plugin/pull/71[#71])
• Increase required core version to 2.60.3 https://github.com/jenkinsci/gradle-plugin/pull/73[#73]
• Use consistent file formatting for sources https://github.com/jenkinsci/gradle-plugin/pull/74[#74]. Thanks @darxriggs.

=== 1.32 (May 24th 2019)

• Expose build scan action via Jenkins API (https://github.com/jenkinsci/gradle-plugin/pull/70[#70])

=== 1.31 (Mar 16th 2019)

• Support detecting build scans for non-Gradle build steps #66
• Support for detecting Maven build scans #68

=== 1.30 (Jan 11th 2019)

• Fix configuration as code compatibility (https://issues.jenkins-ci.org/browse/JENKINS-53575[JENKINS-53575])

=== 1.29 (Jul 3rd 2018)

• Update licensing information in pom.xml.
• Support console annotations for Gradle 4.7 and later.

=== 1.28 (Oct 2 2017)

• Empty job parameters are passed as empty (https://issues.jenkins-ci.org/browse/JENKINS-45300[JENKINS-45300])
• Console annotator endless loop in combination with using the Ant plugin fixed (https://issues.jenkins-ci.org/browse/JENKINS-46051[JENKINS-46051])

=== 1.27.1 (Jul 1 2017)

• Increase required core version to 1.642.1
• Make finding wrapper location more robust on Windows
• Job parameters are now correctly quoted when passed as system properties (https://issues.jenkins-ci.org/browse/JENKINS-42573[JENKINS-42573] and https://issues.jenkins-ci.org/browse/JENKINS-20505[JENKINS-20505])
• Do not pass all job parameters as (system) properties to Gradle by default
• Include automated test for CLI command https://issues.jenkins-ci.org/browse/JENKINS-42847[JENKINS-42847]
• Ensure that Gradle's bin directory is on the path for Pipeline tool steps https://issues.jenkins-ci.org/browse/JENKINS-42381[JENKINS-42381]
• Add option to pass only selected system properties to Gradle
• Add option to pass only selected project properties to Gradle
• Progress status FROM-CACHE and NO-SOURCE are highlighted in the console, too.
• Support build scan plugin 1.8

=== 1.27 (Jun 23 2017)

• DO NOT USE - PROBLEMS WITH RELEASING https://issues.jenkins-ci.org/browse/JENKINS-45126[JENKINS-45126]

=== 1.26 (Feb 13 2016)

• Use @DataBoundSetter instead of a (too) large @DataBoundConstructor
• Add @Symbol annotations for step and tool https://issues.jenkins-ci.org/browse/JENKINS-37394[JENKINS-37394]
• Make it possible to configure the wrapper location https://issues.jenkins-ci.org/browse/JENKINS-35029[JENKINS-35029]
• Update icon for build scan integration
• Remove description from build step

=== Release 1.25

• Update core dependency to 1.580.1 JENKINS-34790
• Fix for Gradle wrapper not working when Gradle version was previously selected (JENKINS-24682)
• Long task names in console outline should not overlap console output (JENKINS-26287)
• It is now possible to pass Gradle build parameters as project properties (JENKINS-17523)
• If a https://scans.gradle.com[Gradle Build Scan] is produced during the build then a link is added to the build page.

=== Release 1.24

• Fix JENKINS-18629 - Jenkins fails to save configuration when using Invoke Gradle script in Conditional Step (single).

=== Release 1.23

• Fix https://issues.jenkins-ci.org/browse/JENKINS-17386[issue #17386] * Gradle.properties ignored after 1.22 upgrade. GRADLE_USER_HOME is now no longer set to the workspace of the job by default. If you wish to have the workspace job as the GRADLE_USER_HOME, you will need to change the config to reflect this.

=== Release 1.22

• Fix JENKINS-17294 - mask sensitive variables (Password parameters)
• Fix JENKINS-13412 - use hudson.util.ArgumentListBuilder#toWindowsCommand
• Set GRADLE_USER_HOME all the time

=== Release 1.21

• Add the ability to allow gradlew to still be run from workspace top, but to also configure it so that gradlew is found in the root build script directory.
• Fix JENKINS-12769 - Cannot specify location of gradle wrapper
• Fix JENKINS-15406 - When using gradlew, root build script field is not used to locate gradlew

=== Release 1.20

• Fix JENKINS-15166 - Gradle plugin fails to save selected Gradle Version in Project configuration

=== Release 1.19

• Fix broken file permission introduced by JENKINS-14780

=== Release 1.18

• Fix JENKINS-14780 - make gradlew script executable

=== Release 1.17

• Merge pull request - Change Gradle Wrapper logic to use the launcher's OS type rather than master's OS type when determining Gradle Wrapper script name

=== Release 1.16

• Fix reopened JENKINS-9538 - hudson.model.FreeStyleBuild & GradleInstallation not serializable => Gradle build not working anymore

=== Release 1.15

• Fix reopened JENKINS-13412 - Gradle plugin fails to quote parameters without whitespace when containing input/output redirection symbols, e.g. in XML strings

=== Release 1.14

• Fix JENKINS-13412 - Gradle plugin fails to quote parameters without whitespace when containing input/output redirection symbols, e.g. in XML strings

=== Release 1.13

• Fix JENKINS-9538 - hudson.model.FreeStyleBuild & GradleInstallation not serializable => Gradle build not working anymore

=== Release 1.12 (October 30, 2011)

• Fix JENKINS-9553 - Gradle wrapper command fails on Windows

=== Release 1.11 (October 02, 2011)

• Coloring output log and Navigation executed tasks (from pull request of ikikko)

=== Release 1.10 (September 07, 2011)

• Provide dry-run option for the

=== Release 1.9 (June 24, 2011)

• Integrate pull request - Enable JAVA_OPTS

=== Release 1.8 (April 01, 2011)

• Add pull request 'Let users use the Gradle wrapper'

=== Release 1.7.1 (March 24, 2011)

• Fix 1.7 to properly set required Jenkins version.

=== Release 1.7 (March 23, 2011)

• Add automatic tool installer

=== Release 1.6 (February 27, 2011)

• Fix 1.5 to properly set required Jenkins version.

=== Release 1.5 (February 19, 2011)

• Update to Jenkins 1.397 API and metadata
• Change UI labels from Hudson to Jenkins

=== Release 1.4 (June, 09, 2010)

• Fix help messages
• Add technical internal behavior for a suitable Artifactory/Gradle integration (with the buildinfo)

=== Release 1.3 (February 23, 2010)

• Add a description message in the build step
• The plugin makes it possible to extract a Gradle distribution from a shared location or from a command line, and uses this distribution for running the build.

=== Release 1.2 (February 07, 2009)

• Add a distinction between switches and tasks
• The plugin makes its possible to specify the location of the build script if the workspace has a top-level build.gradle in somewhere other than the module root directory
• Improve user help messages

=== Release 1.1 (November 07, 2008)

• Add the support of Gradle 0.5. Before the version 0.5, the gradle windows executable file was "gradle.exe" and you lost the ERRORLEVEL value. From Gradle 0.5, the window launcher is a .bat file that conserves the correct ERRORLEVEL value.

=== Release 1.0 (October 04, 2008)

• Initial release