goreleaser/www/docs/quick-start.md

Quick Start

In this example we will build, archive and release a sample 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

You can customize the generated .goreleaser.yml or leave it as-is, it's up to you. It is best practice to check .goreleaser.yml into the source control.

You can test the configuration at any time 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 either a GITHUB_TOKEN or GITLAB_TOKEN environment variable, which should contain a valid GitHub token with the repo scope or GitLab token with api scope. It will be used to deploy releases to your GitHub/GitLab repository. You can create a token here for GitHub or here for GitLab.

export GITHUB_TOKEN="YOUR_GH_TOKEN"

or

export GITLAB_TOKEN="YOUR_GL_TOKEN"

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

!!! info Check if your tag adheres to semantic versioning.

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 --snapshot

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:

Or check your GitLab project's release page. The release should also look like this:

!!! note Releasing to a private-hosted GitLab CE will only work for version v11.7+, because the release feature was introduced in this version.

Dry run

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

Build-only Mode

Build command will build the project

goreleaser build

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

You can check the other options by running:

goreleaser build --help

Release Flags

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

goreleaser release --skip-publish

You can check the other options by running:

goreleaser --help

and

goreleaser release --help