Quick Start

In this example we will build, archive and release a sample project.

Create a GitHub repository, clone and cd into it, and let’s get started!

Initialize your module with:

go mod init github.com/you/your-repo

Then create a main.go file:

main.go

package main

func main() {
  println("Ba dum, tss!")
}

Run the init command to create an example .goreleaser.yaml file:

goreleaser init

Now, let’s run a “local-only” release to see if it works, using the release command:

goreleaser release --snapshot --clean

At this point, you can customize the generated .goreleaser.yaml or leave it as-is — it’s up to you. Either way, check .goreleaser.yaml into source control.

You can verify your .goreleaser.yaml is valid by running the check command:

goreleaser check

You can also use GoReleaser to build the binary for a single target only, which is useful for local development:

GOOS="linux" \
GOARCH="arm64" \
  goreleaser build --single-target

It will default to your current GOOS/GOARCH.

To release to GitHub, export a GITHUB_TOKEN environment variable containing a GitHub token that can create releases in your repository. A classic personal access token needs the repo scope; a fine-grained token needs contents: write permission on the repository. You can create a new classic token with the right scope pre-selected.

Note

Add the write:packages scope as well if you also push Docker images to the GitHub Container Registry. See the GitHub Actions documentation for the full list of permissions each feature needs.

export GITHUB_TOKEN="YOUR_GH_TOKEN"

GoReleaser will use the latest Git tag of your repository.

Now, create a tag and push it to GitHub:

git tag -a v0.1.0 -m "First release"
git push origin v0.1.0

Note

Check if your tag adheres to semantic versioning.

Note

If you don’t want to create a tag yet, you can also run GoReleaser without publishing based on the latest commit by using the --snapshot flag:

goreleaser release --snapshot

Now you can run GoReleaser at the root of your repository:

goreleaser release

That’s all it takes!

GoReleaser will build the binaries for your app for the default targets of the builder being used. You can customize that by changing the builds section. Check the builds documentation for more information.

After building the binaries, GoReleaser will create a separate archive for each target. You can customize several things by changing the archives section, including releasing only the binaries and not creating archives at all. Check the archives documentation for more information.

Finally, it will create a release on GitHub with all the artifacts.

Check your GitHub project’s releases page!

Live examples

We maintain many example repositories. You can use them to learn more and see how GoReleaser works.

Browse example repositories

Dry run

If you want to test everything before doing a release “for real”, you can use the following techniques.

Verify dependencies

You can check if you have every tool needed for the current configuration:

goreleaser healthcheck

Build-only Mode

The build command builds the project without packaging or publishing it:

goreleaser build

This can be useful as part of CI pipelines to verify the project builds without errors for all build targets.

Release Flags

Use the --skip=publish flag to skip publishing:

goreleaser release --skip=publish

More options

Every command documents its own flags. Run the help for any of them:

goreleaser --help
goreleaser release --help

Last updated on August 30, 2026

Introduction How it works