GitHub Release task

Article
10/27/2021
4 minutes to read

Azure Pipelines

Use this task in your pipeline to create, edit, or discard a GitHub release.

Prerequisites

GitHub service connection

This task requires a GitHub service connection with Write permission to the GitHub repository. You can create a GitHub service connection in your Azure Pipelines project. Once created, use the name of the service connection in this task's settings.

YAML snippet

# GitHub Release
# Create, edit, or delete a GitHub release
- task: GitHubRelease@0
  inputs:
    gitHubConnection: 
    #repositoryName: '$(Build.Repository.Name)' 
    #action: 'create' # Options: create, edit, delete
    #target: '$(Build.SourceVersion)' # Required when action == Create || Action == Edit
    #tagSource: 'auto' # Required when action == Create# Options: auto, manual
    #tagPattern: # Optional
    #tag: # Required when action == Edit || Action == Delete || TagSource == Manual
    #title: # Optional
    #releaseNotesSource: 'file' # Optional. Options: file, inline
    #releaseNotesInline: Use this option to manually enter release notes. Use with releaseNotesSource = inline
    #releaseNotesFilePath: # Optional. Use the contents of a file as release notes. 
    #releaseNotes: # Optional
    #assets: '$(Build.ArtifactStagingDirectory)/*' # Optional
    #assetUploadMode: 'delete' # Optional. Options: delete, replace
    #isDraft: false # Optional
    #isPreRelease: false # Optional
    #addChangeLog: true # Optional
    #compareWith: 'lastFullRelease' # Required when addChangeLog == True. Options: lastFullRelease, lastRelease, lastReleaseByTag
    #releaseTag: # Required when compareWith == LastReleaseByTag

Arguments

Argument	Description
`gitHubConnection` GitHub Connection	(Required) Enter the service connection name for your GitHub connection. Learn more about service connections here.
`repositoryName` Repository	(Required) Select the name of GitHub repository in which GitHub releases will be created.
`action` Action	(Required) Select the type of release operation you want perform. This task can create, edit, or discard a GitHub release.
`target` Target	(Required) This is the commit SHA for which the GitHub release will be created. E.g. `48b11d8d6e92a22e3e9563a3f643699c16fd6e27`. You can also use variables here.
`tagSource` Tag source	(Required) Configure the tag to be used for release creation. The 'Git tag' option automatically takes the tag which is associated with this commit. Use the 'User specified tag' option in case you want to manually provide a tag.
`tag` Tag	(Required) Specify the tag for which you want to create, edit, or discard a release. You can also use variables here. E.g. `$(tagName)`.
`title` Release title	(Optional) Specify the title of the GitHub release. If left empty, the tag will be used as the release title.
`releaseNotesSource` Release notes source	(Optional) Specify the description of the GitHub release. Use the 'Release notes file' option to use the contents of a file as release notes. Use the 'Inline release notes' option to manually enter the release notes.
`releaseNotesFilePath` Release notes file path	(Optional) Select the file which contains the release notes.
`releaseNotesInline` Release notes inline	(Optional) Type your release notes here. Markdown is supported.
`assets` Assets	(Optional) Specify the files to be uploaded as assets for the release. You can use wildcard characters to specify a set of files. E.g. `$(Build.ArtifactStagingDirectory)/*.zip`. You can also specify multiple patterns - one per line. By default, all files in the `$(Build.ArtifactStagingDirectory)` directory will be uploaded.
`assetUploadMode` Asset upload mode	(Optional) Use the 'Delete existing assets' option to first delete any existing assets in the release and then upload all assets. Use the 'Replace existing assets' option to replace any assets that have the same name.
`isDraft` Draft release	(Optional) Indicate whether the release should be saved as a draft (unpublished). If `false`, the release will be published.
`isPreRelease` Pre-release	(Optional) Indicate whether the release should be marked as a pre-release.
`addChangeLog` Add changelog	(Optional) If set to `true`, a list of changes (commits and issues) between this and the last published release will be generated and appended to release notes.

Examples

Create a GitHub release

The following YAML creates a GitHub release every time the task runs. The build number is used as the tag version for the release. All .exe files and README.txt files in the $(Build.ArtifactStagingDirectory) folder are uploaded as assets. By default, the task also generates a change log (a list of commits and issues that are part of this release) and publishes it as release notes.

- task: GithubRelease@1 
  displayName: 'Create GitHub Release'      
  inputs:
    gitHubConnection: zenithworks
    repositoryName: zenithworks/javaAppWithMaven
    tagSource: manual
    tag: $(Build.BuildNumber)      
    assets: |
      $(Build.ArtifactStagingDirectory)/*.exe
      $(Build.ArtifactStagingDirectory)/README.txt

You can also control the creation of the release based on repository tags. The following YAML creates a GitHub release only when the commit that triggers the pipeline has a Git tag associated with it. The GitHub release is created with the same tag version as the associated Git tag.

- task: GithubRelease@1 
  displayName: 'Create GitHub Release'      
  inputs:
    gitHubConnection: zenithworks
    repositoryName: zenithworks/javaAppWithMaven           
    assets: $(Build.ArtifactStagingDirectory)/*.exe

You may also want to use the task in conjunction with task conditions to get even finer control over when the task runs, thereby restricting the creation of releases. For example, in the following YAML the task runs only when the pipeline is triggered by a Git tag matching the pattern 'refs/tags/release-v*'.

- task: GithubRelease@1 
  displayName: 'Create GitHub Release'   
  condition: startsWith(variables['Build.SourceBranch'], 'refs/tags/release-v')   
  inputs:
    gitHubConnection: zenithworks
    repositoryName: zenithworks/javaAppWithMaven           
    assets: $(Build.ArtifactStagingDirectory)/*.exe

Edit a GitHub release

The following YAML updates the status of a GitHub release from 'draft' to 'published'. The release to be edited is determined by the specified tag.

- task: GithubRelease@1
  displayName: 'Edit GitHub Release'
  inputs:
    gitHubConnection: zenithworks
    repositoryName: zenithworks/javaAppWithMaven
    action: edit
    tag: $(myDraftReleaseVersion)
    isDraft: false

Delete a GitHub release

The following YAML deletes a GitHub release. The release to be deleted is determined by the specified tag.

- task: GithubRelease@1
  displayName: 'Delete GitHub Release'
  inputs:
    gitHubConnection: zenithworks
    repositoryName: zenithworks/javaAppWithMaven
    action: delete
    tag: $(myDraftReleaseVersion)

Inline release notes

The following YAML create a GitHub release and add inline release notes.

- task: GitHubRelease@1
  inputs:
    gitHubConnection: <GITHUB_SERVICE_CONNECTION>
    repositoryName: '$(Build.Repository.Name)'
    action: 'create'
    target: '$(Build.SourceVersion)'
    tagSource: 'userSpecifiedTag'
    tag: <YOUR_TAG>
    title: <YOUR_TITLE>
    releaseNotesSource: 'inline'
    releaseNotesInline: <YOUR_RELEASE_NOTES>

Open source

This task is open source on GitHub. Feedback and contributions are welcome.