en-US/about_Whiskey_GitHubRelease_Task.help.txt
|
TOPIC
about_Whiskey_GitHubRelease_Task SUMMARY Creates a release in a GitHub repository. DESCRIPTION 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](https://git-scm.com/docs/gitrevisions) 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(https://www.iana.org/assignments/media-types/media-types.xhtml) (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 an 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](https://github.com/settings/tokens). * `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 relative to the whiskey.yml file. * `ContentType` (***mandatory***): the file's [media type](https://www.iana.org/assignments/media-types/media-types.xhtml) (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 } |