Skip to content

Home

Jump to bottom Edit New page
Alex Hatzenbuhler edited this page Jun 17, 2022 · 31 revisions

Configuration

Fields

Examples

For every field, it may be set using any of the following methods

githubRelease {
  // standard method call
  field 'value'
  field('value')  
  setField 'value'
  setField('value')
  field = 'value'
  
  // using a closure for deferred computations
  field { getValue() }
  setField { getValue() }
}

owner

githubRelease {
  owner 'breadmoirai'
  owner { 'breadmoirai' }
  owner = 'breadmoirai'
  setOwner('breadmoirai')
}

This field specifies the user or organization that the github repo belongs to.
By default, if this property is not set, it is inferred using the last part of the project.group value. If

group = 'com.github.breadmoirai'

then

githubRelease {
  owner = 'breadmoirai'
}

repo

githubRelease {
  repo 'github-release-gradle-plugin'
  repo { 'github-release-gradle-plugin' }
  repo = 'github-release-gradle-plugin'
  setRepo('github-release-gradle-plugin')
}

This field specifies the name of the github repo. If this field is not set, it attempts to use the project.name or the rootProject.name

name = 'github-release-gradle-plugin'

then

githubRelease {
  repo = 'github-release-gradle-plugin'
}

authorization

For authorization, either a token or username and password is required. A token can be acquired from user settings > developer settings on Github which must contain repo permissions. In lieu of a token, the username and password can be used as shown below.

githubRelease {
  token 'TOKEN'
  token { 'TOKEN' }
  token = 'TOKEN'
  setToken('TOKEN')

  authorization 'Token TOKEN'
  ...

  authorization 'Basic ' + Base64.encoder.encodeToString('username:password'.bytes)
  
}

tagName

This field specifies the name of the git tag to use or create for this release.
By default this is set to "v$project.version"

githubRelease {
  tagName 'v1.0.0'
  tagName { 'v1.0.0' }
  tagName = 'v1.0.0'
  setTagName('v1.0.0')
}

targetCommitish

This field specifies the target commit hash that this release should point to. Be default, this is set to 'master'

githubRelease {
  targetCommitish 'master'
  targetCommitish { 'master' }
  targetCommitish = 'master'
  setTargetCommitish('master')
}

releaseName

The name of the release.
By default, this is set to whatever the tagName is set to.

githubRelease {
  releaseName 'v1.0.0'
  releaseName { 'v1.0.0' }
  releaseName = 'v1.0.0'
  releaseName('v1.0.0')
}

generateReleaseNotes

Use the GitHub generated release notes for the given release. This can be customized with a .github/release.yml file in your repo. More information can be found on the GitHub Docs.

generateReleaseNotes: true will use other properties in the following ways:

  • If a releaseName is not provided one will be generated based on the tag.
  • If a body is provided it will be pre-pended to the auto generated notes.

By default, this value is false.

githubRelease {
  generateReleaseNotes false
  generateReleaseNotes true
}

body

The body of the release. By default, this is empty. However, we provide a changelog() that attempts to retrieve the list of commits ranging from the most current to the release prior to this one.

githubRelease {
  body 'Hello world!'
  body { 'Hello world!' }
  body = 'Hello world!'
  setBody('Hello world!')

  body changelog()
  body changelog {
    ...
  }
}

changelog

A method changelog() is provided that returns a Provider<String> which extends Callable<String>
This will make a commandline call to git rev-list to get a list of commits.
A block can be passed to changelog to configure the git call. The parameters are as follows

  • executable is set to 'git' by default. If the git executable is not available in the Path, a path to an executable must be set.
  • currentCommit identifies the most recent commit tied to this release. By default, it is set to 'Head'.
  • lastCommit identifies the oldest commit that should be included. By default, this will make a call to the Github API and look for the most recent release before the current one and uses the commit from that release's tag.
  • options is a list of strings that is passed to the git rev-list command. By default, this is set as ["--format=oneline", "--abbrev-commit", "--max-count=50"]

Some examples are shown as follows.

githubRelease {
  body changelog {
    executable 'git' //path to git executable
    currentCommit 'HEAD' //optional
    lastCommit 'HEAD~10' //optional
    options(["--format=oneline", "--abbrev-commit", "--max-count=50", "graph"]) //optional
  }
  
  body {
    changelog().call()
      .readLines()
      .stream()
      .map{ "- $it" }
      .collect(Collectors.joining('\n', '## Changelog\n', ''))
  }

  body { """\
# Release $version

blah blah blah  

## Change Log
${changelog().call().replace('\n','\n - ')}
""" }

}

draft

A boolean to mark this release as a draft or not. By default, this value is set to true. If this value is set to false, the task will perform all other actions applicable (create release, upload assets) and then attempt to publish the release by setting draft to false

githubRelease {
  draft true
}

prerelease

A boolean to mark this release as a prerelease or not. By default, this value is set to false.

githubRelease {
  prerelease false
}

releaseAssets

This is a FileCollection of the files that you would like to upload with your release.

githubRelease {
  releaseAssets.from('build/libs')

  
  FilenameFilter filter = { dir, filename -> filename.contains(project.version) }
  releaseAssets = jar.destinationDir.listFiles filter 
}

overwrite

This field is used to determine if any existing releases should be overwritten or not.

githubRelease {
  overwrite true
}

allowUploadToExisting

This field is mutually exclusive to overwrite. If a release already exists, this option will only upload releaseAssets assets to that release. If overwrite is set to true, then overwrite takes precedence and this field is ignored. By default, this value is set to false.

githubRelease {
  allowUploadToExisting true
}

dryRun

You can set this field to true to show what would happen when the task is run. This will show extra information for debugging and will show what your release will look like as well as what files will be uploaded. This option will still make api calls to read information about your repo but will not modify the repo.

githubRelease {
  dryRun true
}

apiEndpoint

This field sets the api endpoint for github http requests. This is for github enterprise users.

githubRelease {
  apiEndpoint "http(s)://$hostname/api/v3"
}

client

This field allows you to modify the client used for HTTP requests. If your file takes too long to upload, you may consider increasing the time allotted.

githubRelease {
  client new OkHttpClient.Builder()
	.writeTimeout(5, TimeUnit.Minutes)
	.build()
}
Add a custom footer
Add a custom sidebar
Clone this wiki locally