softprops/action-gh-release

action gh-release

A GitHub Action for creating GitHub Releases on Linux, Windows, and macOS virtual environments

• 🤸 Usage
  • 🚥 Limit releases to pushes to tags
  • ⬆️ Uploading release assets
  • 📝 External release notes
  • 💅 Customizing
    • inputs
    • outputs
    • environment variables
  • Permissions

🤸 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 as it maximizes the reuse value of your workflow for non-tag pushes.

v2.6.2 is the final v2 release and is no longer maintained or supported. It uses the Node 20 runtime deprecated by GitHub Actions. Upgrade to v3, which runs on Node 24. If a problem still reproduces on the latest v3, open a new issue with the exact action ref, workflow run URL, runner, and relevant logs.

Below is a simple example of step.if tag gating

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Release
        uses: softprops/action-gh-release@v3
        if: github.ref_type == 'tag'

You can also use push config tag filter

name: Main

on:
  push:
    tags:
      - "v*.*.*"

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Release
        uses: softprops/action-gh-release@v3

⬆️ Uploading release assets

You can configure a number of options for your GitHub release and all are optional.

A common case for GitHub releases is to upload your binary after its been validated and packaged. Use the with.files input to declare a newline-delimited list of glob expressions matching the files you wish to upload to GitHub releases. If you'd like you can just list the files by name directly. If a tag already has a GitHub release, the existing release will be updated with the release assets.

Below is an example of uploading a single asset named Release.txt

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Build
        run: echo ${{ github.sha }} > Release.txt
      - name: Test
        run: cat Release.txt
      - name: Release
        uses: softprops/action-gh-release@v3
        if: github.ref_type == 'tag'
        with:
          files: Release.txt

Below is an example of uploading more than one asset with a GitHub release

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Build
        run: echo ${{ github.sha }} > Release.txt
      - name: Test
        run: cat Release.txt
      - name: Release
        uses: softprops/action-gh-release@v3
        if: github.ref_type == 'tag'
        with:
          files: |
            Release.txt
            LICENSE

⚠️ Note: Notice the | in the yaml syntax above ☝️. That lets you effectively declare a multi-line yaml string. You can learn more about multi-line yaml syntax here

⚠️ Note for Windows: Both \ and / path separators are accepted in files globs. If you need to match a literal glob metacharacter such as [ or ], keep escaping the metacharacter itself in the pattern.

If your release assets are generated under a subdirectory, set working_directory and keep the files patterns relative to that directory.

- name: Release
  uses: softprops/action-gh-release@v3
  if: github.ref_type == 'tag'
  with:
    working_directory: dist
    files: |
      Release.txt
      checksums/*.txt

📝 External release notes

Many systems exist that can help generate release notes for you. This action supports loading release notes from a path in your repository's build to allow for the flexibility of using any changelog generator for your releases, including a human 👩‍💻

name: Main

on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v6
      - name: Generate Changelog
        run: echo "# Good things have arrived" > ${{ github.workspace }}-CHANGELOG.txt
      - name: Release
        uses: softprops/action-gh-release@v3
        if: github.ref_type == 'tag'
        with:
          body_path: ${{ github.workspace }}-CHANGELOG.txt
          repository: my_gh_org/my_gh_repo
          # note you'll typically need to create a personal access token
          # with permissions to create releases in the other repo.
          # A non-empty explicit token overrides GITHUB_TOKEN.
          # Omit the input to use github.token; passing "" treats the token as unset.
          token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}

When you use GitHub's built-in generate_release_notes support, you can optionally pin the comparison base explicitly with previous_tag. This is useful when the default comparison range does not match the release series you want to publish.

- name: Release
  uses: softprops/action-gh-release@v3
  with:
    tag_name: stage-2026-03-15
    target_commitish: ${{ github.sha }}
    previous_tag: prod-2026-03-01
    generate_release_notes: true

💅 Customizing

inputs

The following are optional as step.with keys

💡 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, prerelease, etc.) are not explicitly set and there is already an existing release for the tag, the release will retain its original info.

💡 Draft status is handled separately during finalization. If the action reuses an existing draft release, set draft: true to keep it draft; if draft is omitted, the action will publish that draft after uploading assets.

💡 GitHub immutable releases lock assets after publication. Standard releases in this action already upload assets before publishing, but prereleases stay published by default so release.prereleased workflows keep firing. On an immutable-release repository, use draft: true for prereleases that upload assets, then publish that draft later and subscribe downstream workflows to release.published.

💡 files is glob-based, so literal filenames that contain glob metacharacters such as [ or ] must be escaped in the pattern.

💡 GitHub may normalize or rewrite uploaded asset filenames that contain special or non-ASCII characters. This action uploads the requested file, but it cannot force the final asset name that GitHub stores or returns from the Releases API. In particular, 4-byte Unicode characters such as emoji cannot currently be restored via asset labels.

outputs

The following outputs can be accessed via ${{ steps.<step-id>.outputs }} from this action

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.

environment variables

The following step.env keys are allowed as a fallback but deprecated in favor of using inputs.

⚠️ 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

Permissions

This Action requires the following permissions on the GitHub integration token:

permissions:
  contents: write

When used with discussion_category_name, additional permission is needed:

permissions:
  contents: write
  discussions: write

GitHub token permissions can be set for an individual job, workflow, or for Actions as a whole.

Note that if you intend to run workflows on the release event (on: { release: { types: [published] } }), you need to use a personal access token for this action, as the default secrets.GITHUB_TOKEN does not trigger another workflow.

Doug Tangren (softprops) 2019