Upload Build Binaries to a GitHub Release from GitHub Actions

Upload build binaries to a GitHub release from GitHub Actions on tag push, using softprops/action-gh-release or the gh CLI, with matrix builds and checksums.

Published

At a glance

Last reviewed
Versions referenced
actions/checkout@v7 softprops/action-gh-release@v3
Reading time
2 min read

Code samples are not run in a live repository. See our editorial standards.

On this page

Trigger the workflow on a tag push, give the job permissions: contents: write, and attach your files with softprops/action-gh-release. Without that permission, the default GITHUB_TOKEN cannot create a release or add assets. For a related walkthrough, see Pass Outputs Between GitHub Actions Jobs.

name: Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      - name: Build
        run: |
          # Replace with your real build command
          mkdir -p dist
          echo "binary" > dist/myapp-linux-amd64

      - name: Publish release
        uses: softprops/action-gh-release@v3
        with:
          files: dist/*

Push a tag such as v1.2.0 to run it. The action defaults the release to the tag that triggered the workflow, so you don’t need to set tag_name. The files input accepts newline-separated paths and glob patterns.

Grant write permission

Set permissions at the workflow level (as above) or on the job. Once you declare any permissions key, every unlisted scope drops to none, so add other scopes your job needs.

If the permission is missing, the Releases API call fails with 403 Resource not accessible by integration. Also check Settings → Actions → General → Workflow permissions: a repository or organization policy can restrict the token, and an explicit permissions block in the workflow is the reliable fix. For a related walkthrough, see Fix ‘Resource not accessible by integration’ (403) in GitHub Actions.

The permission does not apply to workflows triggered from forks’ pull requests, where the token is read-only. Release workflows should run on tag pushes in your own repository, not on pull_request.

Upload from a matrix build

Building on several operating systems means several jobs uploading to one release. If every job creates the release, the jobs can race. Create the release once in its own job, then have the build jobs needs it and upload.

name: Release

on:
  push:
    tags:
      - 'v*'

permissions:
  contents: write

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  GH_REPO: ${{ github.repository }}
  TAG: ${{ github.ref_name }}

jobs:
  create-release:
    runs-on: ubuntu-latest
    steps:
      - name: Create release
        run: gh release create "$TAG" --title "$TAG" --generate-notes

  build:
    needs: create-release
    runs-on: ${{ matrix.os }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - os: ubuntu-latest
            asset: myapp-linux-amd64
          - os: macos-latest
            asset: myapp-darwin-arm64
          - os: windows-latest
            asset: myapp-windows-amd64.exe
    steps:
      - uses: actions/checkout@v7

      - name: Build
        shell: bash
        run: |
          # Replace with your real build command
          mkdir -p dist
          echo "binary for ${{ matrix.os }}" > "dist/${{ matrix.asset }}"

      - name: Generate checksum
        shell: bash
        working-directory: dist
        run: |
          shasum -a 256 "${{ matrix.asset }}" > "${{ matrix.asset }}.sha256"
          cat "${{ matrix.asset }}.sha256"

      - name: Upload assets
        shell: bash
        run: |
          gh release upload "$TAG" \
            "dist/${{ matrix.asset }}" \
            "dist/${{ matrix.asset }}.sha256" \
            --clobber

GH_TOKEN is not populated automatically. The gh CLI is preinstalled on GitHub-hosted runners, but you must pass the token through env. GH_REPO lets gh run in the create-release job, which has no checkout.

--clobber overwrites an existing asset with the same name, which makes re-runs of a failed job safe. runs-on: ${{ matrix.os }} is what makes each entry build on its own OS; a hardcoded ubuntu-latest would build everything on Linux.

The tag name goes through an environment variable rather than being interpolated into the script. Tag names are attacker-influenced in some setups, and env avoids shell injection.

Pitfalls

  • Same asset name from several jobs. Assets in a release must have unique names. Include the OS and architecture in each filename.
  • Glob matches nothing. If files matches no path, softprops/action-gh-release has nothing to upload. Confirm the build output path with a ls dist step.
  • Workflow doesn’t start. Tags pushed by another workflow using GITHUB_TOKEN do not trigger new workflow runs. Push the tag with a personal access token or from your machine.
  • Draft releases. Set draft: true on softprops/action-gh-release, or pass --draft to gh release create, if you want to review before publishing. Drafts are not visible to the public.

Verify the release

Run this locally, or add it as a final step in a job that has GH_TOKEN set:

gh release view v1.2.0 --repo OWNER/REPO --json assets --jq '.assets[].name'

Every file you uploaded, including each .sha256, should appear in the list. You can also open the release page in the repository’s Releases section and check the Assets list. If an asset is missing, open the failed job’s log and look at the upload step.

Spotted an error? Report it on our Contact page and see our editorial standards for how we correct articles.