📦 :octocat:

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.

v3 requires a GitHub Actions runtime that supports Node 24. If you still need the last Node 20-compatible line, stay on v2.6.2.

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