goreleaser/goreleaser-action

Run GoReleaser in CI to build, package, and publish Go project releases from a tag.

Official actionCategory: Release AutomationLatest v7View on GitHub

What it does

goreleaser/goreleaser-action installs a chosen GoReleaser version and runs it, so a pushed tag turns into built binaries, archives, checksums, and a GitHub release described by your .goreleaser.yaml.

It can also run in install-only mode when you want to call the goreleaser binary yourself in later steps.

Usage

workflow (.yml)

on:
  push:
    tags: ['v*']
permissions:
  contents: write
steps:
  - uses: actions/checkout@v4
    with:
      fetch-depth: 0
  - uses: actions/setup-go@v5
  - uses: goreleaser/goreleaser-action@v7
    with:
      version: '~> v2'
      args: release --clean
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Inputs

Input	Description	Default	Required
`distribution`	GoReleaser distribution: goreleaser or goreleaser-pro.	`goreleaser`	No
`version`	GoReleaser version to install.	`~> v2`	No
`args`	Arguments to pass to GoReleaser, e.g. release --clean.	-	No
`workdir`	Working directory below the repository root.	`.`	No
`install-only`	Just install GoReleaser without running it.	`false`	No

Outputs

Output	Description
`artifacts`	Build result artifacts as JSON.
`metadata`	Build result metadata as JSON.

Notes

Check out with fetch-depth: 0, GoReleaser needs full git history and tags to compute the version and changelog.

Creating the GitHub release requires permissions: contents: write and a GITHUB_TOKEN in the step env.

Common errors

git is in a dirty state means an earlier step modified tracked files (generated code, lockfiles) before GoReleaser ran. Clean or gitignore them first.
git doesn't contain any tags means the checkout was shallow or tag-less. Use fetch-depth: 0, or pass --snapshot for untagged test builds.
A 403 while creating the release means GITHUB_TOKEN is missing from the step env or the job lacks contents: write.

Security and pinning

Pin the action to a commit SHA and pin version so a release build is reproducible and not silently upgraded.
Grant only contents: write. If publishing to external registries (Homebrew taps, Docker), scope those tokens to the target repos.

Alternatives and related

softprops/action-gh-releaseCreate a GitHub Release and upload assets when you push a tag. docker/build-push-actionBuild and push a Docker image using Buildx, with cache and multi-platform support.

Frequently asked questions

How do I test my GoReleaser config without publishing?

Run the action with args: release --snapshot --clean on a branch. Snapshot mode builds everything but skips tagging and publishing.