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@v3

Inputs

NameRequiredDefaultDescription
bodyNononeNote-worthy description of changes in release
body_pathNononePath to load note-worthy description of changes in release from
nameNononeGives the release a custom name. Defaults to tag name
tag_nameNononeGives a tag name. Defaults to github.ref_name. refs/tags/<name> values are normalized to <name>.
draftNononeKeeps 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.
prereleaseNononeIdentify the release as a prerelease. Defaults to false
preserve_orderNononeUpload artifacts sequentially in the provided order. This does not control the final display order GitHub uses for release assets.
filesNononeNewline-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_directoryNononeBase directory to resolve 'files' globs against. Defaults to the workspace root used by the action step.
overwrite_filesNotrueOverwrite existing files with the same name. Defaults to true
fail_on_unmatched_filesNononeFails if any of the `files` globs match nothing. Defaults to false
repositoryNononeRepository to make releases against, in <owner>/<repo> format
tokenNo${{ 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_commitishNononeCommitish 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_nameNononeIf 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_notesNononeWhether 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_tagNononeOptional. 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_bodyNononeAppend to existing body instead of overwriting it. Default is false.
make_latestNononeSpecifies 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

NameDescription
urlURL to the Release HTML Page
idRelease ID
upload_urlURL for uploading assets to the release
assetsJSON 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: true

Each 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.