GoReleaser


GoReleaser is a release automation tool for Go projects, the goal is to simplify the build, release and publish steps while providing variant customization options for all steps.

GoReleaser is built for CI tools; you only need to download and execute it in your build script. Of course, you can also install it locally.

You can customize your release process by creating a .goreleaser.yml file.

The idea started with a simple shell script, but it quickly became more complex and I also wanted to publish binaries via Homebrew taps, which would have made the script even more “hacky”, so I let go of that and rewrote the whole thing in Go.

You can install the pre-compiled binary, use Docker or compile from source.

Install the pre-compiled binary

homebrew tap:

$ brew install goreleaser/tap/goreleaser

homebrew (may not be the latest version):

$ brew install goreleaser

snapcraft:

$ snap install goreleaser

scoop:

$ scoop bucket add goreleaser https://github.com/goreleaser/scoop-bucket.git
$ scoop install goreleaser

deb/rpm:

Download the .deb or .rpm from the releases page and install with dpkg -i and rpm -i respectively.

manually:

Download the pre-compiled binaries from the releases page and copy to the desired location.

Running with Docker

You can use Docker to do simple releases. Currently, the provided docker image does not provide support for snapcraft.

$ docker run --rm --privileged \
 -v $PWD:/go/src/github.com/user/repo \
 -v /var/run/docker.sock:/var/run/docker.sock \
 -w /go/src/github.com/user/repo \
 -e GITHUB_TOKEN \
 -e DOCKER_USERNAME \
 -e DOCKER_PASSWORD \
 -e DOCKER_REGISTRY \
 goreleaser/goreleaser release

Note that the image will almost always have the last stable Go version.

The DOCKER_REGISTRY environment variables can be left empty when you are releasing to the public docker registry.

If you need more things, you are encouraged to have your own image. You can always use GoReleaser’s own Dockerfile as an example though.

Compiling from source

Note: this method requires Go 1.11+.

$ git clone [email protected]:goreleaser/goreleaser.git
$ cd goreleaser
$ make setup build

After that, the goreleaser binary will be in the root folder:

For more information, check the contributing guide.

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
builds:
- env: - CGO_ENABLED=0
archive: replacements: darwin: Darwin linux: Linux windows: Windows 386: i386 amd64: x86_64
checksum: name_template: 'checksums.txt'
snapshot: name_template: "{{ .Tag }}-next"
changelog: sort: asc filters: exclude: - '^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.

$ export GITHUB_TOKEN=`YOUR_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

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:

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:

and

$ goreleaser release --help

GoReleaser enforces semantic versioning and will error on non compliant tags.

Your tag should be a valid semantic version. If it is not, GoReleaser will error.

The v prefix is not mandatory. You can check the templating documentation to see how to use the tag or each part of the semantic version in name templates.

Unfortunately, GoReleaser does not support CGO.

You can see the discussion about this in this issue.

You can see the comments on the issue referenced for workarounds on it.

GoReleaser requires a GitHub API token with the repo scope selected to deploy the artifacts to GitHub. You can create one here.

This token should be added to the environment variables as GITHUB_TOKEN. Here is how to do it with Travis CI: Defining Variables in Repository Settings.

Alternatively, you can provide the GitHub token in a file. GoReleaser will check ~/.config/goreleaser/github_token by default, you can change that in the .goreleaser.yml file:

# .goreleaser.yml
env_files: github_token: ~/.path/to/my/token

GitHub Enterprise

You can use GoReleaser with GitHub Enterprise by providing its URLs in the .goreleaser.yml configuration file:

# .goreleaser.yml
github_urls: api: https://git.company.com/api/v3/ upload: https://git.company.com/api/uploads/ download: https://git.company.com/ # set to true if you use a self-signed certificate skip_tls_verify: false

If none are set, they default to GitHub’s public URLs.

IMPORTANT: be careful with the URLs, they may change from one installation to another. If they are wrong, goreleaser will fail at some point, so, make sure they’re right before opening an issue. See for example #472.

The dist folder

By default, GoReleaser will create its artifacts in the ./dist folder. If you must, you can change it by setting it in the .goreleaser.yml file:

# .goreleaser.yml
dist: another-folder-that-is-not-dist

Using the main.version

Default wise GoReleaser sets three ldflags:

  • main.version: Current Git tag (the v prefix is stripped) or the name of the snapshot, if you’re using the --snapshot flag
  • main.commit: Current git commit SHA
  • main.date: Date according RFC3339

You can use it in your main.go file:

package main import "fmt" var ( version = "dev" commit = "none" date = "unknown"
) func main() { fmt.Printf("%v, commit %v, built at %v", version, commit, date)
}

You can override this by changing the ldflags option in the build section.

GoReleaser provides multiple customizations via the .goreleaser.yml file.

You can generate it by running goreleaser init or start from scratch. The defaults are sensible and fit for most projects.

GoReleaser was built from the very first commit with the idea of running it as part of the CI pipeline in mind.

Let’s see how we can get it working on popular CI software.

Travis CI

You may want to setup your project to auto-deploy your new tags on Travis, for example:

# .travis.yml
language: go addons: apt: packages: # needed for the nfpm pipe: - rpm # needed for the snap pipe: - snapd env:
# needed for the snap pipe:
- PATH=/snap/bin:$PATH install:
# needed for the snap pipe:
- sudo snap install snapcraft --classic # needed for the docker pipe
services:
- docker after_success:
# docker login is required if you want to push docker images.
# DOCKER_PASSWORD should be a secret in your .travis.yml configuration.
- test -n "$TRAVIS_TAG" && docker login -u=myuser -p="$DOCKER_PASSWORD"
# snapcraft login is required if you want to push snapcraft packages to the
# store.
# You'll need to run `snapcraft export-login snap.login` and
# `travis encrypt-file snap.login --add` to add the key to the travis
# environment.
- test -n "$TRAVIS_TAG" && snapcraft login --with snap.login # calls goreleaser
deploy:
- provider: script skip_cleanup: true script: curl -sL https://git.io/goreleaser | bash on: tags: true condition: $TRAVIS_OS_NAME = linux

Note the last line (condition: $TRAVIS_OS_NAME = linux): it is important if you run a build matrix with multiple Go versions and/or multiple OSes. If that’s the case you will want to make sure GoReleaser is run just once.

CircleCI

Here is how to do it with CircleCI 2.0:

# .circleci/config.yml
version: 2
jobs: release: docker: - image: circleci/golang:1.10 steps: - checkout - run: curl -sL https://git.io/goreleaser | bash
workflows: version: 2 release: jobs: - release: filters: branches: ignore: /.*/ tags: only: /v[0-9]+(\.[0-9]+)*(-.*)*/

Drone

By default, drone does not fetch tags. plugins/git is used with default values, in most cases we’ll need overwrite the clone step enabling tags in order to make goreleaser work correctly.

In this example we’re creating a new release every time a new tag is pushed. Note that you’ll need to enable tags in repo settings and add github_token secret.

pipeline: clone: image: plugins/git tags: true test: image: golang:1.10 commands: - go test ./... -race release: image: golang:1.10 secrets: [github_token] commands: curl -sL https://git.io/goreleaser | bash when: event: tag

Google CloudBuild

CloudBuild works off a different clone than your github repo: it seems that your changes are pulled to a repo like source.developers.google.com/p/YourProjectId/r/github-YourGithubUser-YourGithubRepo, and that’s what you’re building off.

This repo has the wrong name, so to prevent Goreleaser from publishing to the wrong github repo, put in the your .goreleaser.yml file’s release section:

release: github: owner: YourGithubUser name: YourGithubRepo

Create two build triggers: - a “push to any branch” trigger for your regular CI (doesn’t invoke goreleaser) - a “push to tag” trigger which invokes goreleaser

The push to any branch trigger could use a Dockerfile or a cloudbuild.yaml, whichever you prefer.

You should have a dedicated cloudbuild.release.yaml that is only used by the “push to tag” trigger.

In this example we’re creating a new release every time a new tag is pushed. See Using Encrypted Resources for how to encrypt and base64-encode your github token.

The clone that the build uses has no tags, which is why we must explicitly run git tag $TAG_NAME (note that $TAG_NAME is only set when your build is triggered by a “push to tag”.) This will allow goreleaser to create a release with that version, but it won’t be able to build a proper changelog containing just the messages from the commits since the prior tag.

steps:
~ # Setup the workspace so we have a viable place to point GOPATH at.
~ - name: gcr.io/cloud-builders/go
~ env: ['PROJECT_ROOT=github.com/YourGithubUser/YourGithubRepo']
~_ args: ['env'] ~ # Create github release.
~ - name: goreleaser/goreleaser
~ entrypoint: /bin/sh
~ dir: gopath/src/github.com
~ env: ['GOPATH=/workspace/gopath']
~ args: ['-c', 'cd YourGithubUser/YourGithubRepo && git tag $TAG_NAME && /goreleaser' ]
~_ secretEnv: ['GITHUB_TOKEN'] secrets:
~ - kmsKeyName: projects/YourProjectId/locations/global/keyRings/YourKeyRing/cryptoKeys/YourKey
~ secretEnv:
~ GITHUB_TOKEN: |
~ ICAgICAgICBDaVFBZUhVdUVoRUtBdmZJSGxVWnJDZ0hOU2NtMG1ES0k4WjF3L04zT3pEazhRbDZr
~ QVVTVVFEM3dVYXU3cVJjK0g3T25UVW82YjJaCiAgICAgICAgREtBMWVNS0hOZzcyOUtmSGoyWk1x
~_ ICAgICAgIEgwYndIaGUxR1E9PQo=

Semaphore

In Sempahore 2.0 each project starts with the default pipeline specified in .semaphore/semaphore.yml.

# .semaphore/semaphore.yml.
version: v1.0
name: Build
agent: machine: type: e1-standard-2 os_image: ubuntu1804 blocks: - name: "Test" task: prologue: commands: # set go version - sem-version go 1.11 - "export GOPATH=~/go" - "export PATH=/home/semaphore/go/bin:$PATH" - checkout jobs: - name: "Lint" commands: - go get ./... - go test ./... # On Semaphore 2.0 deployment and delivery is managed with promotions,
# which may be automatic or manual and optionally depend on conditions.
promotions: - name: Release pipeline_file: goreleaser.yml auto_promote_on: - result: passed branch: - "^refs/tags/v*"

Pipeline file in .semaphore/goreleaser.yml:

version: "v1.0"
name: GoReleaser
agent: machine: type: e1-standard-2 os_image: ubuntu1804
blocks: - name: "Release" task: secrets: - name: goreleaser prologue: commands: - sem-version go 1.11 - "export GOPATH=~/go" - "export PATH=/home/semaphore/go/bin:$PATH" - checkout jobs: - name: goreleaser commands: - curl -sL https://git.io/goreleaser | bash

The following YAML file, createSecret.yml creates a new secret item that is called goreleaser with one environment variable, named GITHUB_TOKEN:

apiVersion: v1alpha
kind: Secret
metadata: name: goreleaser
data: env_vars: - name: GITHUB_TOKEN value: "4afk4388304hfhei34950dg43245"

Check Managing Secrets for more detailed documentation.

GoReleaser can also be used within GitHub Actions.

You can create a workflow like this to push your releases.

workflow "Release" { on = "push" resolves = ["goreleaser"]
} action "is-tag" { uses = "actions/bin/[email protected]" args = "tag"
} action "goreleaser" { uses = "docker://goreleaser/goreleaser" secrets = [ "GITHUB_TOKEN", "GORELEASER_GITHUB_TOKEN", # either GITHUB_TOKEN or GORELEASER_GITHUB_TOKEN is required "DOCKER_USERNAME", "DOCKER_PASSWORD", ] args = "release" needs = ["is-tag"]
}

This should support almost everything already supported by GoReleaser’s Docker image. Check the install section for more details.

If you need to push the homebrew tap to another repository, you’ll need a custom github token, for that, add a GORELEASER_GITHUB_TOKEN secret and remove the default GITHUB_TOKEN. The default, auto-generated token only has access to current the repo.

What doesn’t work

Projects that depend on $GOPATH. GitHub Actions override the WORKDIR instruction and it seems like we can’t override it.

In the future releases we may hack something together to work around this, but, for now, only projects using Go modules are supported.

This page will eventually have information for those who want to contribute to the project.

Also check the CONTRIBUTING.md file on the root of our repository.

Tutorials made by the community.

Want to add your tutorial here? Please do! Edit this file and open a Pull Request! Thanks!