GitHubRelease Task

Overview

The GitHubRelease task creates a release in GitHub and optionally uploads files to the release. You must set the repository's owner and name as a URI Path with the RepositoryName parameter (e.g. OWNER/NAME). You must set the tag name used to identify the release with the Tag property. You must set the API key ID of the GitHub access token to use with the ApiKeyID property. You add the access token to your build with the Add-WhiskeyApiKey function. The ApiKeyID property and the value of the Add-WhiskeyApiKey function's ID property must be the same.

The release is created on the head (i.e. most recent commit) on the master branch. Use the Commitish property to change the release's commit. We recommend using the $(WHISKEY_SCM_COMMIT_ID) variable, which is the commit ID currently building, but any valid Git revision should be acceptable.

GitHub uses the commit message of the release's commit as the release name. Use the Name property to set your own name.

Use the Description property to describe the release. This is a good place for release notes.

You can upload assets/files, too. These files are visible on the release's page in GitHub and are downloadable by users. Use the Assets property to upload files. Assets should be a list of mappings. Each mapping must have a Path property (which is a path, relative to the whiskey.yml file), to a file and a ContentType property, which is the media type of the file (e.g. application/json). By default, the file's name is used as its name in GitHub. To customize the file's name, use the asset's Name property.

If your repository in GitHub doesn't already have the release's tag, a new release is created. If the tag already exists, the release's name and description are updated. If a file already exists, its name is updated.

This task enables TLS 1.2 in the PowerShell process running the build.

Properties

• RepositoryName (mandatory): the owner and name of the repository, as a URI path, e.g. OWNER/NAME.
• Tag (mandatory): the tag name to create for the release. An actual Git tag will be created in your repository.
• ApiKeyID (mandatory): The ID of the API key to use when making GitHub API calls. Add API keys to your build with the Add-WhiskeyApiKey function. You can generate an access token on your GitHub tokens settings page.
• Commitish: the commitish that identifies the commit you're releasing. By default, the GitHub API uses the head (i.e. most recent commit) of the master branch. We recommend using the $(WHISKEY_SCM_COMMIT_ID) variable, which is the commit ID currently building.
• Name: the name of the release. By default, the GitHub API uses the commit message of the commit you're releasing.
• Description: a description of the release. This is a good place to put release notes.
• Assets: a list of files to upload. These files will show on the release's page in GitHub and users will be able to download them. This is a good place to upload a ZIP file of your application. Each asset is a mapping with these properties:
  • Path (mandatory): the path to the file to upload. The path must exist. The path must be under the build root (the directory of the build's whiskey.yml file).
  • ContentType (mandatory): the file's media type (e.g. application/json).
  • Name: the file's name when viewing in GitHub and downloading. The default is the file's actual name.

Examples

Example 1

Publish:
- GitHubRelease:
    RepositoryName: webmd-health-services/Whiskey
    ApiKeyID: github.com
    Tag: $(WHISKEY_SEMVER2_NO_BUILD_METADATA)
    Commitish: $(WHISKEY_SCM_COMMIT_ID)
    Name: $(WHISKEY_SEMVER2_NO_BUILD_METADATA)
    Assets:
    - Path: .output\Whiskey.zip
        ContentType: application/zip
            Name: Whiskey-$(WHISKEY_SEMVER2_NO_BUILD_METADATA).zip

Demonstrates how Whiskey uses the GitHubRelease task to publish itself to GitHub. In this example, this release is:

• created in the https://github.com/webmd-health-services/Whiskey repository.
• tagged as $(WHISKEY_SEMVER2_NO_BUILD_METADATA), which is the version of the current build.
• tagged on commit $(WHISKEY_SCM_COMMIT_ID), which is the commit of the current build.
• named $(WHISKEY_SEMVER2_NO_BUILD_METADATA), which is the version of the current build.

One asset is uploaded, .output\Whiskey.zip, as an application/zip file. We change the file name to Whiskey-$(WHISKEY_SEMVER2_NO_BUILD_METADATA).zip so the version number is in the name.

The GitHub access token is stored as an environment variable on the build server and is added to the build like this:

$apiKeys = @{
        'github.com' = 'GITHUB.COM'
    }

$apiKeys.Keys |
    Where-Object { Test-Path -Path ('env:{0}' -f $apiKeys[$_]) } |
    ForEach-Object { 
        $apiKeyID = $_
        $envVarName = $apiKeys[$apiKeyID]
        Write-Verbose ('Adding API key "{0}" with value from environment variable "{1}".' -f $apiKeyID,$envVarName)
        Add-WhiskeyApiKey -Context $context -ID $apiKeyID -Value (Get-Item -Path ('env:{0}' -f $envVarName)).Value 
    }