goreleaser-action/README.md

GoReleaser Action

GitHub Action for GoReleaser

---

• Usage
  • Workflow
  • Verification
  • Run on new tag
  • Signing
  • Upload artifacts
  • Install Only
  • Cache the binary
• Customizing
  • inputs
  • outputs
  • environment variables
• Limitation
• Development
• License

Usage

GoReleaser Action runs goreleaser, please follow its docs for more information about how to customize what GoReleaser does.

Workflow

name: goreleaser

on:
  pull_request:
  push:

permissions:
  contents: write

jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v6
        with:
          fetch-depth: 0
      -
        name: Set up Go
        uses: actions/setup-go@v6
      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v7
        with:
          # either 'goreleaser' (default) or 'goreleaser-pro'
          distribution: goreleaser
          # 'latest', 'nightly', or a semver
          version: '~> v2'
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Your GoReleaser Pro key, if you are using the 'goreleaser-pro' distribution
          # GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}

Important

: note the fetch-depth: 0 input in Checkout step. It is required for the changelog to work correctly.

Verification

The action verifies the integrity of the downloaded GoReleaser archive against the published checksums.txt automatically — no configuration required.

If cosign is available on PATH, the action will additionally verify the cosign sigstore signature of the checksums file against the GoReleaser release workflow's OIDC identity. If cosign isn't installed, this step is silently skipped.

Note

: cosign signature verification requires GoReleaser v2.13.0 or newer (and the matching nightly). Earlier releases ship a .sig detached signature signed with cosign v2, which is not compatible with the cosign v3 sigstore-bundle format the action verifies. For older versions the cosign step is silently skipped — only the checksums.txt SHA-256 verification runs.

Note

: when version: nightly is used, the action resolves the latest immutable vX.Y.Z-<sha>-nightly release from the GitHub Releases API. Pass GITHUB_TOKEN to the action step (as in the example above) to avoid unauthenticated API rate limits.

To enable signature verification, install cosign before running the action:

      -
        name: Install cosign
        uses: sigstore/cosign-installer@v3
      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v7
        with:
          distribution: goreleaser
          version: '~> v2'
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Both checksum and signature verification work for tagged releases (≥ v2.13.0) and the nightly channel.

Run on new tag

If you want to run GoReleaser only on new tag, you can use this event:

on:
  push:
    tags:
      - '*'

Or with a condition on GoReleaser step:

      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v7
        if: startsWith(github.ref, 'refs/tags/')
        with:
          version: '~> v2'
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For detailed instructions please follow GitHub Actions workflow syntax.

Signing

If signing is enabled in your GoReleaser configuration, you can use the Import GPG GitHub Action along with this one:

      -
        name: Import GPG key
        id: import_gpg
        uses: crazy-max/ghaction-import-gpg@v7
        with:
          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
          passphrase: ${{ secrets.PASSPHRASE }}
      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v7
        with:
          version: '~> v2'
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }}

And reference the fingerprint in your signing configuration using the GPG_FINGERPRINT environment variable:

signs:
  - artifacts: checksum
    args: ["--batch", "-u", "{{ .Env.GPG_FINGERPRINT }}", "--output", "${signature}", "--detach-sign", "${artifact}"]

Upload artifacts

For some events like pull request or schedule you might want to store the artifacts somewhere for testing purposes. You can do that with the actions/upload-artifact action:

      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v7
        with:
          version: '~> v2'
          args: release --clean
          workdir: myfolder
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      -
        name: Upload assets
        uses: actions/upload-artifact@v6
        with:
          name: myapp
          path: myfolder/dist/*

Install Only

steps:
  -
    name: Install GoReleaser
    uses: goreleaser/goreleaser-action@v7
    with:
      install-only: true
  -
    name: Show GoReleaser version
    run: goreleaser -v

Cache the binary

The action looks for GoReleaser in the runner tool cache before it downloads. A second use of the action in the same job, or any job on a self-hosted runner that already has the version, installs immediately.

A binary taken from the tool cache is not verified again, because the checksum and the cosign signature were verified when it was first written. On a self-hosted runner the tool cache is kept between jobs, so it must be trusted like the runner itself. GitHub-hosted runners start with an empty tool cache in every job, so they always download and verify.

The action does not use the GitHub Actions cache. It was measured and it is slower than a download: restoring the 24 MB entry takes about 1.3 s, while downloading, verifying the checksum, verifying the cosign signature and extracting the release takes about 0.9 s on a GitHub-hosted runner. It would also skip the verification it is supposed to protect.

Customizing

inputs

Following inputs can be used as step.with keys

Name	Type	Default	Description
distribution	String	goreleaser	GoReleaser distribution, either goreleaser or goreleaser-pro
version¹	String	~> v2	GoReleaser version
version-file²	String		Read the GoReleaser version from a file (see below)
args	String		Arguments to pass to GoReleaser
workdir	String	.	Working directory (below repository root)
install-only	Bool	false	Just install GoReleaser

¹ Can be a fixed version like v0.117.0 or a max satisfying semver one like ~> 0.132. In this case this will return v0.132.1.

² Path to a file containing the GoReleaser version. Resolved relative to workdir. Currently only .tool-versions (asdf/mise) format is supported. When set, this takes precedence over version.

# .tool-versions
goreleaser 2.13.0

- uses: goreleaser/goreleaser-action@v7
  with:
    version-file: .tool-versions
    args: release --clean

outputs

Following outputs are available

Name	Type	Description
artifacts	JSON	Build result artifacts
metadata	JSON	Build result metadata

environment variables

Following environment variables can be used as step.env keys

Name	Description
GITHUB_TOKEN	GITHUB_TOKEN as provided by secrets and requires contents:write
GORELEASER_KEY	Your GoReleaser Pro License Key, in case you are using the goreleaser-pro distribution

Limitation

GITHUB_TOKEN permissions are limited to the repository that contains your workflow.

If you need to push the homebrew tap to another repository, you must therefore create a custom Personal Access Token with repo permissions and add it as a secret in the repository. If you create a secret named GH_PAT, the step will look like this:

      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v7
        with:
          version: '~> v2'
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GH_PAT }}

Migrating from v3

If you need the auto-snapshot feature, take a look at this example repository: it's a minimal working example with all you need.

Development

See CONTRIBUTING.md for the full development workflow.

Quick reference:

# install dependencies
npm ci

# format, build dist/, and run tests
npm run pre-checkin

License

MIT. See LICENSE for more details.