Quick Start

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

Create a GitHub repository and add a single main package:

// main.go
package main

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

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

$ goreleaser init

   • Generating .goreleaser.yml file
   • config created; please edit accordingly to your needs file=.goreleaser.yml

The generated config file will look like this:

# This is an example goreleaser.yaml file with some sane defaults.
# Make sure to check the documentation at http://goreleaser.com
- env:
    darwin: Darwin
    linux: Linux
    windows: Windows
    386: i386
    amd64: x86_64
  name_template: 'checksums.txt'
  name_template: "{{ .Tag }}-next"
  sort: asc
    - '^docs:'
    - '^test:'

You can test this initial configuration by running GoReleaser with a few extra parameters to not require a version tag, skip publishing to GitHub, and remove any already-built files:

$ goreleaser --snapshot --skip-publish --rm-dist

If you are not using vgo or Go modules, then you will need to comment out the before hooks in the generated config file. Or update them to match your setup accordingly.

GoReleaser will build the binaries for your app for Windows, Linux and macOS, both amd64 and i386 architectures. You can customize that by changing the builds section. Check the documentation for more information.

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

You’ll need to export a GITHUB_TOKEN environment variable, which should contain a valid GitHub token with the repo scope. It will be used to deploy releases to your GitHub repository. You can create a token here.


GoReleaser will use the latest Git tag of your repository. Create a tag and push it to GitHub:

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

Attention: Check if your tag adheres to semantic versioning.

If you don’t want to create a tag yet, you can also create a release based on the latest commit by using the --snapshot flag.

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

$ goreleaser

That’s all! Check your GitHub project’s release page. The release should look like this:

Dry run

If you want to test everything before doing a release “for real”, you can use the --skip-publish flag, which will only build and package things:

$ goreleaser release --skip-publish

You can check the other options by running:

$ goreleaser --help


$ goreleaser release --help

Last updated by Alice on February 6, 2019.