gradle-release plugin

Gradle Plugin page

Introduction

The gradle-release plugin is designed to work similar to the Maven release plugin. The gradle release task defines the following as the default release process:

• The plugin checks for any un-committed files (Added, modified, removed, or un-versioned).
• Checks for any incoming or outgoing changes.
• Checkout to the release branch and merge from the working branch (optional, for GIT only, with pushReleaseVersionBranch)
• Removes the SNAPSHOT flag on your project's version (If used)
• Prompts you for the release version.
• Checks if your project is using any SNAPSHOT dependencies
• Will build your project.
• Commits the project if SNAPSHOT was being used.
• Creates a release tag with the current version.
• Checkout to the working branch (optional, for GIT only, with pushReleaseVersionBranch)
• Prompts you for the next version.
• Commits the project with the new version.

Current SCM support: Bazaar, Git (1.7.2 or newer), Mercurial, and Subversion

Installation

The gradle-release plugin will work with Gradle 6.0 and beyond

Legacy plugin application

buildscript {
  repositories {
    maven {
      url 'https://plugins.gradle.org/m2/'
    }
  }
  dependencies {
    classpath 'net.researchgate:gradle-release:3.0.2'
  }
}

apply plugin: 'net.researchgate.release'

Plugin DSL

plugins {
  id 'net.researchgate.release' version '3.0.2'
}

Please refer to the Gradle DSL PluginDependenciesSpec to understand the behavior and limitations when using the new syntax to declare plugin dependencies.

Usage

After you have your build.gradle file configured, simply run: gradle release and follow the on-screen instructions.

Configuration

As described above, the plugin will check for un-committed files and SNAPSHOT dependencies. By default the plugin will fail when any un-committed, or SNAPSHOT dependencies are found.

Below are some properties of the Release Plugin Convention that can be used to make your release process more lenient

Below are some properties of the Release Plugin Convention that can be used to customize the build

Below are some properties of the Release Plugin Convention that are specific to version control.

To set any of these properties to false, add a "release" configuration to your project's build.gradle file. Eg. To ignore un-versioned files, you would add the following to your build.gradle file:

release {
  failOnUnversionedFiles = false
}

Eg. To ignore upstream changes, change 'failOnUpdateNeeded' to false:

release {
  failOnUpdateNeeded = false
}

This are all possible configuration options and its default values:

release {
    failOnCommitNeeded = true
    failOnPublishNeeded = true
    failOnSnapshotDependencies = true
    failOnUnversionedFiles = true
    failOnUpdateNeeded = true
    revertOnFail = true
    preCommitText = ''
    preTagCommitMessage = '[Gradle Release Plugin] - pre tag commit: '
    tagCommitMessage = '[Gradle Release Plugin] - creating tag: '
    newVersionCommitMessage = '[Gradle Release Plugin] - new version commit: '
    tagTemplate = '${version}'
    versionPropertyFile = 'gradle.properties'
    versionProperties = []
    snapshotSuffix = '-SNAPSHOT'
    buildTasks = []
    ignoredSnapshotDependencies = []
    versionPatterns = [
        /(\d+)([^\d]*$)/: { Matcher m, Project p -> m.replaceAll("${(m[0][1] as int) + 1}${m[0][2]}") }
    ]
    pushReleaseVersionBranch = null
    scmAdapters = [
        net.researchgate.release.GitAdapter,
        net.researchgate.release.SvnAdapter,
        net.researchgate.release.HgAdapter,
        net.researchgate.release.BzrAdapter
    ]

    git {
        requireBranch.set('main')
        pushToRemote.set('origin')
        pushToBranchPrefix.set('')
        commitVersionFileOnly.set(false)
        signTag.set(false)
    }

    svn {
        username.set(null)
        password.set(null)
        pinExternals.set(false)   // allows to pin the externals when tagging, requires subversion client >= 1.9.0
    }
}

Kotlin DSL Example

import net.researchgate.release.ReleaseExtension
repositories {
    maven {
      url 'https://plugins.gradle.org/m2/'
    }
  }
  dependencies {
    classpath 'net.researchgate:gradle-release:3.0.2'
  }

apply(plugin = "base")
apply(plugin = "net.researchgate.release")

configure<ReleaseExtension> {
    ignoredSnapshotDependencies.set(listOf("net.researchgate:gradle-release"))
    with(git) {
        requireBranch.set("master")
        // to disable branch verification: requireBranch.set(null as String?)
    }
}

Custom release steps

To add a step to the release process is very easy. Gradle provides a very nice mechanism for manipulating existing tasks. There are two available hooks provided: beforeReleaseBuild which runs before build and afterReleaseBuild which runs afterwards.

For example, if we wanted to make sure uploadArchives is called and succeeds after the build with the release version has finished, we would just add the uploadArchives task as a dependency of the afterReleaseBuild task:

afterReleaseBuild.dependsOn uploadArchives

Multi-Project Builds

Support for multi-project builds isn't complete, but will work given some assumptions. The gradle-release plugin assumes and expects that only one version control system is used by both root and sub projects.

Apply the plugin separately to each subproject that you wish to release. Release using a qualified task name, e.g.:

./gradlew :sub:release # release a subproject named "sub"
./gradlew :release # release the root project

Working in Continuous Integration

In a continuous integration environment like Jenkins or Hudson, you don't want to have an interactive release process. To avoid having to enter any information manually during the process, you can tell the plugin to automatically set and update the version number.

You can do this by setting the release.useAutomaticVersion property on the command line, or in Jenkins when you execute gradle. The version to release and the next version can be optionally defined using the properties release.releaseVersion and release.newVersion.

gradle release -Prelease.useAutomaticVersion=true -Prelease.releaseVersion=1.0.0 -Prelease.newVersion=1.1.0-SNAPSHOT

Getting Help

To ask questions please use stackoverflow or github issues.

• GitHub Issues: https://github.com/researchgate/gradle-release/issues/new
• Stack Overflow: http://stackoverflow.com/questions/tagged/gradle-release-plugin

To report bugs, please use the GitHub project.

• Project Page: https://github.com/researchgate/gradle-release
• Reporting Bugs: https://github.com/researchgate/gradle-release/issues