Cerberus Gradle Plugin

Konrad Biernacki, 2018

About

Cerberus is a gradle plugin for extracting Jira issues from commit messages and sharing information on its respective Jenkins job and HockeyApp upload.

Using all of Cerberus' features, you can use your commit history -

 * HEAD -> Develop
 | \ 
 *   \
 | \ |
 | | * [CER-12] Address PR Feedback
 | | * [CER-12] Fix bug
 | | | 
 | * | [CER-7] Add feature
 | / |

to generate release notes using data from Jira and your build -

### Changelog
- [CER-12] UI Bug
- [CER-7] Minor Feature

Built by [Jenkins](https://jenkins.url/build/451)

and comment on your Jira tickets with build and artefact information

Jenkins: [Build #451|https://jenkins.url/build/451]
HockeyApp: [Version 2.0-RC|https://hockey.url/app/d3adcaf3]

Installation

As a buildSrc Plugin

If you don't have one already, create a buildSrc folder in your target project's root directory
Copy this project into the buildSrc directory (so the plugin build.gradle file would be found in target_project/buildSrc/build.gradle)

As a JAR Plugin

Compile the plugin as a .jar file
Add the .jar to your target project (eg. target_project/libs/cerberus.jar)

Add the following to your target project's build.gradle file:

buildscript {
    dependencies {
        classpath files('libs/cerberus.jar')
    }
}

Usage

Add the plugin to your target project's build.gradle
```
apply plugin: 'au.com.outware.cerberus'
```

Specify any configuration parameters in the Gradle DSL plugin configuration block. A typical implementation could be as follows:

cerberus {
    shouldUpdateTicketAfter = ['pushToHockeyApp']
    
    jiraDomain = 'https://jira.mydomain.com'
    jiraUsername = 'cerberus'
    jiraPassword = 'password'
}

Use Cerberus' tasks in your target build flow

task runCi {
    configure {
        group = 'Continuous Integration'
        description = "Main CI Task"
    }

    dependsOn('assemble', 
              'cerberus_makeReleaseNotes', 
              'pushToHockeyApp', 
              'cerberus_updateTicket')
}

Gradle Tasks

Cerberus adds the following tasks to your project classpath:

cerberus_makeReleaseNotes

Generate release notes from all changes between the HEAD and a specified SHA-1 (cerberus.lastSuccessfulCommit)
Load those changes into the plugin extension at cerberus.releaseNotes as a markdown formatted string

cerberus_updateTicket

Comment on any identified Jira tickets with:
- Build information
  - cerberus.buildNumber
  - cerberus.buildUrl
- HockeyApp upload information
  - cerberus.hockeyAppUploadUrl
  - cerberus.hockeyAppShortVersion

Configuration

The plugin extension available through the Gradle DSL is documented at CerberusPluginExtension.kt

Environment Variables

Some configuration parameters are populated from environment variables

Parameter	Environment Variable	Description
jiraDomain	`CER_JIRA_URL`	URL to Jira instance
jiraUsername	`CER_JIRA_CREDENTIALS_USR`	Username for Jira instance
jiraPassword	`CER_JIRA_CREDENTIALS_PWD`	Password for Jira instance
lastSuccessfulCommit	`GIT_PREVIOUS_SUCCESSFUL_COMMIT`	The SHA-1 to use as the root commit when comparing to HEAD
buildUrl	`BUILD_URL`	The URL to the current build information
buildNumber	`BUILD_NUMBER`	The current build number

If additional (or alternate) environment variables need to be used, then configure them in the plugin DSL block like so:

cerberus {
    jiraDomain = System.env.OTHER_JIRA_DOMAIN
    ...
}

Default Values

Some configuration parameters have default values

Parameter	Default Value	Description
ticketExtractionPattern	`"[A-Z]+-\\d+"`	Regex pattern to match tickets against. Default matches `ABC-123`
gitLogPrettyFormat	`"%s"`	Commit information to match against, and include in release notes if it matches `commitPassthroughPattern`
disableJiraSSLVerify	`false`	Verify an SSL connection attempt is valid before connecting

aksvenk/gradle-plugin-cerberus