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!")
}

Initialize modules with

go mod init main

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

goreleaser init

Now, lets 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. It is best practice to check .goreleaser.yaml into the 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 only for a given GOOS/GOARCH, which is useful for local development:

goreleaser build --single-target

To release to GitHub, 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 new GitHub token here.

!!! info

The minimum permissions the `GITHUB_TOKEN` should have to run this are `write:packages`

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

!!! info

Check if your tag adheres to [semantic versioning](limitations/semver.md).

!!! info

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:

```sh
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 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.

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

Check your GitHub project's releases page!

Example release on GitHub.

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