softprops/action-gh-release@v3
Github Action for creating Github Releases
At a glance
- Latest major
v3- Repository
- softprops/action-gh-release
- Inputs
- 19 (0 required)
- Outputs
- 4
- Runs using
node24- License
- MIT
- Last checked
Inputs and outputs come straight from the action's official action.yml. See our editorial standards.
Usage
- uses: softprops/action-gh-release@v3Inputs
| Name | Required | Default | Description |
|---|---|---|---|
body | No | none | Note-worthy description of changes in release |
body_path | No | none | Path to load note-worthy description of changes in release from |
name | No | none | Gives the release a custom name. Defaults to tag name |
tag_name | No | none | Gives a tag name. Defaults to github.ref_name. refs/tags/<name> values are normalized to <name>. |
draft | No | none | Keeps the release as a draft. Defaults to false. When reusing an existing draft release, set this to true to keep it draft; omit it to publish after upload. On immutable-release repositories, use this for prereleases that upload assets and publish the draft later. |
prerelease | No | none | Identify the release as a prerelease. Defaults to false |
preserve_order | No | none | Upload artifacts sequentially in the provided order. This does not control the final display order GitHub uses for release assets. |
files | No | none | Newline-delimited list of path globs for asset files to upload. Escape glob metacharacters when matching literal filenames that contain them. `~/...` expands to the runner home directory. On Windows, both \ and / path separators are accepted. GitHub may normalize raw asset filenames that contain special characters; the action restores the asset label when possible, but the final download name remains GitHub-controlled. |
working_directory | No | none | Base directory to resolve 'files' globs against. Defaults to the workspace root used by the action step. |
overwrite_files | No | true | Overwrite existing files with the same name. Defaults to true |
fail_on_unmatched_files | No | none | Fails if any of the `files` globs match nothing. Defaults to false |
repository | No | none | Repository to make releases against, in <owner>/<repo> format |
token | No | ${{ github.token }} | Authorized GitHub token or PAT. Defaults to github.token when omitted. A non-empty explicit token overrides GITHUB_TOKEN. Passing an empty string treats the token as unset. |
target_commitish | No | none | Commitish value that determines where the Git tag is created from. Can be any branch or commit SHA. When creating a new tag for an older commit, `github.token` may not have permission to create the ref; use a PAT or another token with sufficient contents permissions if you hit 403 `Resource not accessible by integration`. |
discussion_category_name | No | none | 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. If there is already a discussion linked to the release, this parameter is ignored. |
generate_release_notes | No | none | 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. |
previous_tag | No | none | Optional. When generate_release_notes is enabled, use this tag as GitHub's previous_tag_name comparison base. If omitted, GitHub chooses the comparison base automatically. |
append_body | No | none | Append to existing body instead of overwriting it. Default is false. |
make_latest | No | none | Specifies whether this release should be set as the latest release for the repository. Drafts and prereleases cannot be set as latest. Can be `true`, `false`, or `legacy`. Uses GitHub api default if not provided |
Outputs
| Name | Description |
|---|---|
url | URL to the Release HTML Page |
id | Release ID |
upload_url | URL for uploading assets to the release |
assets | JSON array containing information about each uploaded asset, in the format given [here](https://docs.github.com/en/rest/reference/repos#upload-a-release-asset--code-samples) (minus the `uploader` field) |
Read an output with ${{ steps.<step-id>.outputs.<name> }}; the step needs an id.
Examples
Create a release from a tag
Publish release notes and attach build files when you push a version tag.
name: Example
on:
push:
tags: ["v*"]
permissions:
contents: write
jobs:
example:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- name: Build
run: mkdir -p dist && echo build > dist/app.txt
- name: GH Release
uses: softprops/action-gh-release@v3
with:
files: "dist/*"
generate_release_notes: trueEach example passed actionlint (syntax, expressions and the inputs it knows for this action). They were not run in a live repository, so replace placeholder values such as names, ARNs and paths with your own.
Something out of date or wrong? Report it on our Contact page. This page is rebuilt from the action's repository roughly once a week.