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.
At a glance
- Last reviewed
- Versions referenced
actions/checkout@v7softprops/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
filesmatches no path,softprops/action-gh-releasehas nothing to upload. Confirm the build output path with als diststep. - Workflow doesn’t start. Tags pushed by another workflow using
GITHUB_TOKENdo not trigger new workflow runs. Push the tag with a personal access token or from your machine. - Draft releases. Set
draft: trueonsoftprops/action-gh-release, or pass--drafttogh 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.