2019-09-29 12:51:03 +00:00
< div align = "center" >
📦 :octocat:
< / div >
< h1 align = "center" >
action gh-release
< / h1 >
2019-08-25 06:14:36 +00:00
2019-09-29 12:51:03 +00:00
< p align = "center" >
2020-04-12 03:43:21 +00:00
A GitHub Action for creating GitHub Releases on Linux, Windows, and macOS virtual environments
2019-09-29 12:51:03 +00:00
< / p >
< div align = "center" >
< img src = "demo.png" / >
< / div >
< div align = "center" >
< a href = "https://github.com/softprops/action-gh-release/actions" >
< img src = "https://github.com/softprops/action-gh-release/workflows/Main/badge.svg" / >
< / a >
< / div >
< br / >
2019-08-25 06:13:05 +00:00
2019-08-26 04:59:00 +00:00
## 🤸 Usage
### 🚥 Limit releases to pushes to tags
Typically usage of this action involves adding a step to a build that
is gated pushes to git tags. You may find `step.if` field helpful in accomplishing this
2020-04-12 03:43:21 +00:00
as it maximizes the reuse value of your workflow for non-tag pushes.
2019-08-26 04:59:00 +00:00
Below is a simple example of `step.if` tag gating
```yaml
name: Main
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
2020-01-05 23:05:29 +00:00
uses: actions/checkout@v2
2019-08-26 04:59:00 +00:00
- name: Release
2019-09-09 12:35:52 +00:00
uses: softprops/action-gh-release@v1
2019-08-26 04:59:00 +00:00
if: startsWith(github.ref, 'refs/tags/')
```
2019-09-09 08:36:46 +00:00
You can also use push config tag filter
```yaml
name: Main
on:
push:
tags:
2021-03-22 17:05:06 +00:00
- "v*.*.*"
2019-09-09 08:36:46 +00:00
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
2020-01-05 23:05:29 +00:00
uses: actions/checkout@v2
2019-09-09 08:36:46 +00:00
- name: Release
2019-09-09 12:35:52 +00:00
uses: softprops/action-gh-release@v1
2019-09-09 08:36:46 +00:00
```
2019-08-26 04:59:00 +00:00
### ⬆️ Uploading release assets
2020-04-12 03:43:21 +00:00
You can configure a number of options for your
2019-08-28 02:26:08 +00:00
GitHub release and all are optional.
2019-08-26 04:59:00 +00:00
A common case for GitHub releases is to upload your binary after its been validated and packaged.
2019-09-17 14:14:30 +00:00
Use the `with.files` input to declare a newline-delimited list of glob expressions matching the files
2019-08-26 04:59:00 +00:00
you wish to upload to GitHub releases. If you'd like you can just list the files by name directly.
2019-08-25 19:24:49 +00:00
2019-08-26 05:26:13 +00:00
Below is an example of uploading a single asset named `Release.txt`
2019-08-25 19:24:49 +00:00
```yaml
name: Main
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
2020-01-05 23:05:29 +00:00
uses: actions/checkout@v2
2019-08-25 19:24:49 +00:00
- name: Build
run: echo ${{ github.sha }} > Release.txt
2019-08-26 04:59:00 +00:00
- name: Test
run: cat Release.txt
2019-08-25 19:24:49 +00:00
- name: Release
2019-09-09 12:35:52 +00:00
uses: softprops/action-gh-release@v1
2019-08-25 22:37:27 +00:00
if: startsWith(github.ref, 'refs/tags/')
2019-08-25 19:25:36 +00:00
with:
files: Release.txt
2019-08-25 19:24:49 +00:00
```
2019-08-26 05:00:01 +00:00
2019-09-17 14:21:28 +00:00
Below is an example of uploading more than one asset with a GitHub release
2019-09-17 14:14:30 +00:00
```yaml
name: Main
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
2020-01-05 23:05:29 +00:00
uses: actions/checkout@v2
2019-09-17 14:14:30 +00:00
- name: Build
run: echo ${{ github.sha }} > Release.txt
- name: Test
run: cat Release.txt
- name: Release
uses: softprops/action-gh-release@v1
if: startsWith(github.ref, 'refs/tags/')
with:
2019-09-17 14:21:28 +00:00
files: |
2019-09-17 14:14:30 +00:00
Release.txt
LICENSE
```
> **⚠️ Note:** Notice the `|` in the yaml syntax above ☝️. That let's you effectively declare a multi-line yaml string. You can learn more about multi-line yaml syntax [here](https://yaml-multiline.info)
2019-08-26 05:26:13 +00:00
### 📝 External release notes
Many systems exist that can help generate release notes for you. This action supports
2019-08-28 02:26:08 +00:00
loading release notes from a path in your repository's build to allow for the flexibility
2019-08-26 05:26:13 +00:00
of using any changelog generator for your releases, including a human 👩💻
```yaml
name: Main
on: push
jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
2020-01-05 23:05:29 +00:00
uses: actions/checkout@v2
2019-09-06 02:30:21 +00:00
- name: Generate Changelog
2021-07-26 16:59:56 +00:00
run: echo "# Good things have arrived" > ${{ github.workspace }}-CHANGELOG.txt
2019-08-26 05:26:13 +00:00
- name: Release
2019-09-09 12:35:52 +00:00
uses: softprops/action-gh-release@v1
2019-08-26 05:26:13 +00:00
if: startsWith(github.ref, 'refs/tags/')
with:
2021-07-26 16:59:56 +00:00
body_path: ${{ github.workspace }}-CHANGELOG.txt
2021-08-08 04:47:44 +00:00
# note you'll typically need to create a personal access token
# with permissions to create releases in the other repo
token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}
2019-08-26 05:26:13 +00:00
env:
2021-03-22 17:05:06 +00:00
GITHUB_REPOSITORY: my_gh_org/my_gh_repo
2019-08-26 05:26:13 +00:00
```
2019-08-26 04:59:00 +00:00
### 💅 Customizing
2019-08-25 19:24:49 +00:00
2019-08-26 05:00:01 +00:00
#### inputs
2019-08-26 02:32:14 +00:00
2019-08-26 04:59:00 +00:00
The following are optional as `step.with` keys
2021-11-15 06:30:36 +00:00
| Name | Type | Description |
| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `body` | String | Text communicating notable changes in this release |
| `body_path` | String | Path to load text communicating notable changes in this release |
| `draft` | Boolean | Indicator of whether or not this release is a draft |
| `prerelease` | Boolean | Indicator of whether or not is a prerelease |
| `files` | String | Newline-delimited globs of paths to assets to upload for release |
| `name` | String | Name of the release. defaults to tag name |
| `tag_name` | String | Name of a tag. defaults to `github.ref` |
| `fail_on_unmatched_files` | Boolean | Indicator of whether to fail if any of the `files` globs match nothing |
| `repository` | String | Name of a target repository in `<owner>/<repo>` format. Defaults to GITHUB_REPOSITORY env variable |
2022-01-22 16:40:31 +00:00
| `target_commitish` | String | Commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. Defaults to repository default branch. |
2021-11-15 06:30:36 +00:00
| `token` | String | Secret GitHub Personal Access Token. Defaults to `${{ github.token }}` |
| `discussion_category_name` | String | If specified, a discussion of the specified category is created and linked to the release. The value must be a category that already exists in the repository. For more information, see ["Managing categories for discussions in your repository." ](https://docs.github.com/en/discussions/managing-discussions-for-your-community/managing-categories-for-discussions-in-your-repository ) |
| `generate_release_notes` | Boolean | Whether to automatically generate the name and body for this release. If name is specified, the specified name will be used; otherwise, a name will be automatically generated. If body is specified, the body will be pre-pended to the automatically generated notes. See the [GitHub docs for this feature ](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes ) for more information |
2022-01-22 16:40:31 +00:00
| `append_body` | Boolean | Append existed body instead of overrides |
2019-08-26 05:26:13 +00:00
2021-07-17 23:27:42 +00:00
💡 When providing a `body` and `body_path` at the same time, `body_path` will be
attempted first, then falling back on `body` if the path can not be read from.
💡 When the release info keys (such as `name` , `body` , `draft` , `prerelease` , etc.)
are not explicitly set and there is already an existing release for the tag, the
release will retain its original info.
2019-08-26 02:32:14 +00:00
2019-10-20 22:15:51 +00:00
#### outputs
The following outputs can be accessed via `${{ steps.<step-id>.outputs }}` from this action
2022-01-22 16:40:31 +00:00
| Name | Type | Description |
| ------------ | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | String | Github.com URL for the release |
| `id` | String | Release ID |
| `upload_url` | String | URL for uploading assets to the release |
2022-07-10 04:32:03 +00:00
| `assets` | String | JSON array containing information about each uploaded asset, in the format given [here ](https://docs.github.com/en/rest/releases/assets#get-a-release-asset ) (minus the `uploader` field) |
2021-11-25 23:02:50 +00:00
As an example, you can use `${{ fromJSON(steps.<step-id>.outputs.assets)[0].browser_download_url }}` to get the download URL of the first asset.
2019-10-20 22:15:51 +00:00
2019-08-26 05:00:01 +00:00
#### environment variables
2019-08-26 02:32:14 +00:00
2021-03-16 04:50:23 +00:00
The following `step.env` keys are allowed as a fallback but deprecated in favor of using inputs.
2019-08-26 02:32:14 +00:00
2021-03-22 17:05:06 +00:00
| Name | Description |
| ------------------- | ------------------------------------------------------------------------------------------ |
| `GITHUB_TOKEN` | GITHUB_TOKEN as provided by `secrets` |
| `GITHUB_REPOSITORY` | Name of a target repository in `<owner>/<repo>` format. defaults to the current repository |
2019-09-14 14:46:26 +00:00
2020-04-12 03:43:21 +00:00
> **⚠️ Note:** This action was previously implemented as a Docker container, limiting its use to GitHub Actions Linux virtual environments only. With recent releases, we now support cross platform usage. You'll need to remove the `docker://` prefix in these versions
2019-09-14 14:46:26 +00:00
2021-09-27 19:55:09 +00:00
### Permissions
This Action requires the following permissions on the GitHub integration token:
```yaml
permissions:
contents: write
```
2022-05-23 06:37:32 +00:00
When used with `discussion_category_name` , additional permission is needed:
```yaml
permissions:
contents: write
discussions: write
```
2021-09-27 19:55:09 +00:00
[GitHub token permissions ](https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token ) can be set for an individual job, workflow, or for Actions as a whole.
2019-09-06 02:30:21 +00:00
Doug Tangren (softprops) 2019
