softprops/action-gh-release

You can load release notes from a file in your repository using body_path. This allows you to use custom changelog generators.

If you are using GitHub's built-in generate_release_notes: true, you can optionally pin the comparison base using previous_tag to control the range of changes included in the notes.

- 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
    token: ${{ secrets.CUSTOM_GITHUB_TOKEN }}

To prevent the action from running on every push (like to branches), gate the release step using step.if or configure the workflow on: push trigger to only listen for specific tag patterns.

Option 1: Using step.if Use if: github.ref_type == 'tag' to ensure the release step only executes when a tag is pushed.

Option 2: Using push tag filters Configure your workflow trigger to only fire on specific tag patterns (e.g., v*.*.*).

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'

Use the with.files input to upload files to a GitHub release. The input accepts a newline-delimited list of glob expressions or direct filenames.

• Multiple files: Use the YAML | syntax for multi-line strings.
• Subdirectories: If assets are in a subdirectory, set working_directory and keep files patterns relative to it.
• Windows: Both \ and / path separators are supported.
• Escaping: If a filename contains glob metacharacters like [ or ], you must escape them in the pattern.
• Existing Releases: If a release for the tag already exists, the action will update it with the new assets.

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

The action requires specific permissions on the GitHub integration token:

Standard release:

permissions:
  contents: write

When using discussion_category_name:

permissions:
  contents: write
  discussions: write

Note: If you want to trigger other workflows on the release event (e.g., on: release: published), you must use a Personal Access Token (PAT), as the default GITHUB_TOKEN does not trigger subsequent workflow runs.

The files input allows you to specify one or more files or glob patterns to upload as release assets. You can provide them in two ways:

1. Newline-separated list
2. Comma-separated list (supports complex patterns containing braces like {a,b})

Example of a multi-line input:

files: |
  dist/*.js
  assets/*.zip

The action requires a GitHub token to create releases. It follows this priority for authentication:

1. token input (INPUT_TOKEN): If provided, this explicitly overrides the default GitHub token.
2. GITHUB_TOKEN environment variable: Used if no explicit token is provided.

If neither is provided, the action will fail to authenticate.

The following outputs are available via ${{ steps.<step-id>.outputs }}:

Example: Get download URL of the first asset {{ fromJSON(steps.<step-id>.outputs.assets)[0].browser_download_url }}

When configuring the files input, you can control how the action behaves if a provided glob pattern or file path does not match any actual files in the working directory.

• If fail_on_unmatched_files is set to true, the action will throw an error and fail the workflow if a pattern is unmatched.
• If fail_on_unmatched_files is not set (or false), the action will log a warning for the unmatched pattern but continue execution.

If you attempt to upload an asset to a release that has already been published, GitHub will return a 422 error. The library identifies this as an immutable release failure.

Workaround: Upload assets to a draft release first, then publish the release. Draft pre-releases publish with the release.published event, allowing for asset uploads before the final publication.