GoReleaser Deliver Go binaries as fast and easily as possible

Introduction

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

Installing Goreleaser

There are three ways to get going install GoReleaser:

Using homebrew

brew install goreleaser/tap/goreleaser

Using Scoop

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

Check the tap source for more details.

Manually

Download your preferred flavor from the releases page and install manually.

Using go get

Note: this method requires Go 1.10+.

$ go get github.com/goreleaser/goreleaser

It is recommended to also run dep ensure to make sure that the dependencies are in the correct versions.

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

By default GoReleaser will build the current directory, but you can change the package path in the GoReleaser configuration file:

# .goreleaser.yml
# Build customization
builds:
  - binary: drum-roll
    goos:
      - windows
      - darwin
      - linux
    goarch:
      - amd64

GoReleaser skips invalid GOOS/GOARCH combinations.

With the above configuration the name of all created binaries will be drum-roll and GoReleaser will build one binary in 64bit architecture for each of the operating systems Windows, Linux and MacOS.

GoReleaser will then archive the resulting binaries of each OS/Arch pair into a separate file. The default format is {{.ProjectName}}_{{.Os}}_{{.Arch}}. You can change the archive’s name and format. You can also replace the OS and the Architecture with your own.

Another useful feature is to add additional files to the created archives:

# .goreleaser.yml
# Build customization
builds:
  - main: main.go
    binary: drum-roll
    goos:
      - windows
      - darwin
      - linux
    goarch:
      - amd64
# Archive customization
archive:
  format: tar.gz
  replacements:
    amd64: 64-bit
    darwin: macOS
    linux: Tux
  files:
    - drum-roll.licence.txt

This configuration will generate tar archives, each containing an additional file called drum-roll.licence.txt. The archives will be located in the dist folder:

  • ./dist/drum-roll_windows_64-bit.tar.gz
  • ./dist/drum-roll_macOS_64-bit.tar.gz
  • ./dist/drum-roll_Tux_64-bit.tar.gz

Next, you need to export a GITHUB_TOKEN environment variable, which should contain a GitHub token with the repo scope selected. It will be used to deploy releases to your GitHub repository. Create a token here.

$ export GITHUB_TOKEN=`YOUR_TOKEN`

GoReleaser uses 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

Note: We recommend the use of semantic versioning. We are not enforcing it though. We do remove the v prefix and then enforce that the next character is a number. So, v0.1.0 and 0.1.0 are virtually the same and both are accepted, while version0.1.0 is not.

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:

Environment

GitHub Token

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: api.github.foo.bar
    upload: uploads.github.foo.bar
    download: github.foo.bar

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

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

GoReleaser always sets a main.version ldflag. You can use it in your main.go file:

package main

var version = "master"

func main() {
  println(version)
}

version will be set to the current Git tag (the v prefix is stripped) or the name of the snapshot, if you’re using the --snapshot flag.

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

Customizing Git

By default, GoReleaser uses full length commit hashes when setting a main.commit ldflag or creating filenames in --snapshot mode.

You can use short, 7 character long commit hashes by setting it in the .goreleaser.yml:

# .goreleaser.yml
git:
  short_hash: true

Customization

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.

We’ll cover all customizations available bellow.

Project Name

The project name is used in the name of the Brew formula, archives, etc. If none is given, it will be inferred from the name of the Git project.

# .goreleaser.yml
project_name: myproject

Global Hooks

Some builds may need pre-build steps before building, e.g. go generate. The before section allows for global hooks which will be executed before the build is started.

The configuration is very simple, here is a complete example:

# .goreleaser.yml
before:
  hooks:
  - make clean
  - go generate ./...

If any of the hooks fails the build process is aborted.

Builds

Builds can be customized in multiple ways. You can specify for which GOOS and GOARCH binaries are generated, and you can changed the name of the binary, flags, ldflags, hooks, etc.

Here is a commented builds section with all fields specified:

# .goreleaser.yml
builds:
  # You can have multiple builds defined as a yaml list
  -
    # Path to main.go file or main package.
    # Default is `.`.
    main: ./cmd/main.go

    # Name of the binary.
    # This is parsed with the Go template engine and the following variables
    # are available:
    # - Date
    # - Commit
    # - Tag
    # - Version (Git tag without `v` prefix)
    # Date format is `2006-01-02_15:04:05`.
    # Default is the name of the project directory.
    binary: program

    # Set flags for custom build tags.
    # Default is empty.
    flags: -tags dev

    # Custom asmflags template.
    # This is parsed with the Go template engine and the following variables
    # are available:
    # - Date
    # - Commit
    # - Tag
    # - Version (Git tag without `v` prefix)
    # - Env (environment variables)
    # Date format is `2006-01-02_15:04:05`.
    # You can use the `time` function instead of `Date`, for example:
    # `time "2006-01-02"` too if you need custom formats
    #
    # Default is empty.
    asmflags: all=-trimpath={{.Env.GOPATH}}

    # Custom gcflags template.
    # This is parsed with the Go template engine and the following variables
    # are available:
    # - Date
    # - Commit
    # - Tag
    # - Version (Git tag without `v` prefix)
    # - Env (environment variables)
    # Date format is `2006-01-02_15:04:05`.
    # You can use the `time` function instead of `Date`, for example:
    # `time "2006-01-02"` too if you need custom formats
    #
    # Default is empty.
    gcflags: all=-trimpath={{.Env.GOPATH}}

    # Custom ldflags template.
    # This is parsed with the Go template engine and the following variables
    # are available:
    # - Date
    # - Commit
    # - Tag
    # - Version (Git tag without `v` prefix)
    # - Env (environment variables)
    # Date format is `2006-01-02_15:04:05`.
    # You can use the `time` function instead of `Date`, for example:
    # `time "2006-01-02"` too if you need custom formats
    #
    # Default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}`.
    ldflags: -s -w -X main.build={{.Version}}

    # Custom environment variables to be set during the builds.
    # Default is empty.
    env:
      - CGO_ENABLED=0

    # GOOS list to build for.
    # For more info refer to: https://golang.org/doc/install/source#environment
    # Defaults are darwin and linux.
    goos:
      - freebsd
      - windows

    # GOARCH to build for.
    # For more info refer to: https://golang.org/doc/install/source#environment
    # Defaults are 386 and amd64.
    goarch:
      - amd64
      - arm
      - arm64

    # GOARM to build for when GOARCH is arm.
    # For more info refer to: https://golang.org/doc/install/source#environment
    # Default is only 6.
    goarm:
      - 6
      - 7

    # List of combinations of GOOS + GOARCH + GOARM to ignore.
    # Default is empty.
    ignore:
      - goos: darwin
        goarch: 386
      - goos: linux
        goarch: arm
        goarm: 7

    # Hooks can be used to customize the final binary,
    # for example, to run generators.
    # Default is both hooks empty.
    hooks:
      pre: rice embed-go
      post: ./script.sh

Passing environment variables to ldflags

You can do that by using {{ .Env.VARIABLE_NAME }} in the template, for example:

builds:
  - ldflags: -s -w -X "main.goversion={{.Env.GOVERSION}}"

Then you can run:

GOVERSION=$(go version) goreleaser

Archive

The binaries built will be archived together with the README and LICENSE files into a tar.gz file. In the archive section you can customize the archive name, additional files, and format.

Here is a commented archive section with all fields specified:

# .goreleaser.yml
archive:
  # You can change the name of the archive.
  # This is parsed with the Go template engine and the following variables
  # are available:
  # - ProjectName
  # - Binary (Name of the binary if the packaging format is binary)
  # - Tag
  # - Version (Git tag without `v` prefix)
  # - Os
  # - Arch
  # - Arm (ARM version)
  # - Env (environment variables)
  # Defaults:
  # - if format is `tar.gz` or `zip`:
  #   - `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
  # - if format is `binary`:
  #   - `{{ .Binary }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
  name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"

  # Replacements for GOOS and GOARCH in the archive name.
  # Keys should be valid GOOSs or GOARCHs.
  # Values are the respective replacements.
  # Default is empty.
  replacements:
    amd64: 64-bit
    386: 32-bit
    darwin: macOS
    linux: Tux

  # Set to true, if you want all files in the archive to be in a single directory.
  # If set to true and you extract the archive 'goreleaser_Linux_arm64.tar.gz',
  # you get a folder 'goreleaser_Linux_arm64'.
  # If set to false, all files are extracted separately.
  # Default is false.
  wrap_in_directory: true

  # Archive format. Valid options are `tar.gz`, `zip` and `binary`.
  # If format is `binary`, no archives are created and the binaries are instead uploaded directly.
  # In that case name_template and the below specified files are ignored.
  # Default is `tar.gz`.
  format: zip

  # Can be used to change the archive formats for specific GOOSs.
  # Most common use case is to archive as zip on Windows.
  # Default is empty.
  format_overrides:
    - goos: windows
      format: zip

  # Additional files/globs you want to add to the archive.
  # Defaults are any files matching `LICENCE*`, `LICENSE*`,
  # `README*` and `CHANGELOG*` (case-insensitive).
  files:
    - LICENSE.txt
    - README.md
    - CHANGELOG.md
    - docs/*
    - design/*.png

Passing environment variables to name_template

You can do that by using {{ .Env.VARIABLE_NAME }} in the template, for example:

archive:
  name_template: '{{.ProjectName}}-{{.Version}}-{{.Env.GOVERSION_NR}}'

Then you can run:

GOVERSION_NR=$(go version | awk '{print $3;}') goreleaser

Packaging only the binaries

Since GoReleaser will always add the README and LICENSE files to the archive if the file list is empty, you’ll need to provide a filled files on the archive section.

A working hack is to use something like this:

# goreleaser.yml
archive:
  files:
  - none*

This would add all files matching the glob none*, provide that you don’t have any files matching that glob, only the binary will be added to the archive.

For more information, check #602

Checksum

GoReleaser generates a project_1.0.0_checksums.txt file and uploads it with the release, so your users can validate if the downloaded files are correct.

The checksum section allows customizations of the filename:

# .goreleaser.yml
checksum:
  # You can change the name of the checksums file.
  # This is parsed with the Go template engine and the following variables
  # are available:
  # - ProjectName
  # - Tag
  # - Version (Git tag without `v` prefix)
  # - Env (environment variables)
  # Default is `{{ .ProjectName }}_{{ .Version }}_checksums.txt`.
  name_template: "{{ .ProjectName }}_checksums.txt"

Signing

GoReleaser can sign some or all of the generated artifacts. Signing ensures that the artifacts have been generated by yourself and your users can verify that by comparing the generated signature with your public signing key.

Signing works in combination with checksum files and it is generally sufficient to sign the checksum files only.

The default is configured to create a detached signature for the checksum files with GnuPG and your default key. To enable signing just add

# goreleaser.yml
sign:
   artifacts: checksum

To customize the signing pipeline you can use the following options:

# .goreleaser.yml
sign:
  # name of the signature file.
  # '${artifact}' is the path to the artifact that should be signed.
  #
  # signature: "${artifact}.sig"

  # path to the signature command
  #
  # cmd: gpg

  # command line arguments for the command
  #
  # to sign with a specific key use
  # args: ["-u", "<key id, fingerprint, email, ...>", "--output", "${signature}", "--detach-sign", "${artifact}"]
  #
  # args: ["--output", "${signature}", "--detach-sign", "${artifact}"]


  # which artifacts to sign
  #
  #   checksum: only checksum file(s)
  #   all:      all artifacts
  #   none:     no signing
  #
  # artifacts: none

Snapshots

Sometimes we want to generate a full build of our project, but neither want to validate anything nor upload it to anywhere. GoReleaser supports this with the --snapshot flag and also with the snapshot customization section:

# .goreleaser.yml
snapshot:
  # Allows you to change the name of the generated snapshot
  # releases. The following variables are available:
  # - Commit
  # - Tag
  # - Timestamp
  # Default is `SNAPSHOT-{{.Commit}}`.
  name_template: SNAPSHOT-{{.Commit}}

Linux Packages

GoReleaser can generate RPM, Deb and Snap packages for your projects.

Let’s see each option in detail:

NFPM

GoReleaser can be wired to nfpm to generate and publish .deb and .rpm packages.

Available options:

# .goreleaser.yml
nfpm:
  # You can change the name of the package.
  # This is parsed with the Go template engine and the following variables
  # are available:
  # - ProjectName
  # - Tag
  # - Version (Git tag without `v` prefix)
  # - Os
  # - Arch
  # - Arm (ARM version)
  # - Env (environment variables)
  # Default: `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
  name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"

  # Replacements for GOOS and GOARCH in the package name.
  # Keys should be valid GOOSs or GOARCHs.
  # Values are the respective replacements.
  # Default is empty.
  replacements:
    amd64: 64-bit
    386: 32-bit
    darwin: macOS
    linux: Tux

  # Your app's vendor.
  # Default is empty.
  vendor: Drum Roll Inc.
  # Your app's homepage.
  # Default is empty.
  homepage: https://example.com/

  # Your app's maintainer (probably you).
  # Default is empty.
  maintainer: Drummer <[email protected]>

  # Your app's description.
  # Default is empty.
  description: Software to create fast and easy drum rolls.

  # Your app's license.
  # Default is empty.
  license: Apache 2.0

  # Formats to be generated.
  formats:
    - deb
    - rpm

  # Packages your package depends on.
  dependencies:
    - git
    - zsh

  # Packages your package recommends installing.
  # For RPM packages rpmbuild >= 4.13 is required
  recommends:
    - bzr
    - gtk

  # Packages your package suggests installing.
  # For RPM packages rpmbuild >= 4.13 is required
  suggests:
    - cvs
    - ksh

  # Packages that conflict with your package.
  conflicts:
    - svn
    - bash

  # Override default /usr/local/bin destination for binaries
  bindir: /usr/bin

  # Files or directories to add to your package (beyond the binary).
  # Keys are source paths/globs to get the files from.
  # Values are the destination locations of the files in the package.
  files:
    "scripts/etc/init.d/": "/etc/init.d"
    "path/**/glob": "/var/foo/glob"

  # Config files to add to your package. They are about the same as
  # the files keyword, except package managers treat them differently (while
  # uninstalling, mostly).
  # Keys are source paths/globs to get the files from.
  # Values are the destination locations of the files in the package.
  config_files:
    "tmp/app_generated.conf": "/etc/app.conf"
    "conf/*.conf": "/etc/foo/"

  # Scripts to execute during the installation of the package.
  # Keys are the possible targets during the installation process
  # Values are the paths to the scripts which will be executed
  scripts:
    preinstall: "scripts/preinstall.sh"
    postinstall: "scripts/postinstall.sh"
    preremove: "scripts/preremove.sh"
    postremove: "scripts/postremove.sh"

  # Some attributes can be overrided per package format.
  overrides:
    deb:
      conflicts:
        - subversion
      dependencies:
        - git
      suggests:
        - gitk
      recommends:
        - tig
    rpm:
      replacements:
        amd64: x86_64
      name_template: "{{ .ProjectName }}-{{ .Version }}-{{ .Arch }}"
      files:
        "tmp/man.gz": "/usr/share/man/man8/app.8.gz"
      config_files:
        "tmp/app_generated.conf": "/etc/app-rpm.conf"
      scripts:
        preinstall: "scripts/preinstall-rpm.sh"

Note that GoReleaser will not install rpmbuild or any dependencies for you. As for now, rpmbuild is recommended if you want to generate rpm packages. You can install it with apt-get install rpm or brew install rpm.

Snapcraft

GoReleaser can also generate snap packages. Snaps are a new packaging format, that will let you publish your project directly to the Ubuntu store. From there it will be installable in all the supported Linux distros, with automatic and transactional updates.

You can read more about it in the snapcraft docs.

Available options:

# .goreleaser.yml
snapcraft:
  # You can change the name of the package.
  # This is parsed with the Go template engine and the following variables
  # are available:
  # - ProjectName
  # - Tag
  # - Version (Git tag without `v` prefix)
  # - Os
  # - Arch
  # - Arm (ARM version)
  # - Env (environment variables)
  # Default: `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
  name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"

  # Replacements for GOOS and GOARCH in the package name.
  # Keys should be valid GOOSs or GOARCHs.
  # Values are the respective replacements.
  # Default is empty.
  replacements:
    amd64: 64-bit
    386: 32-bit
    darwin: macOS
    linux: Tux

  # The name of the snap. This is optional.
  # Default is project name.
  name: drumroll

  # Single-line elevator pitch for your amazing snap.
  # 79 char long at most.
  summary: Software to create fast and easy drum rolls.

  # This the description of your snap. You have a paragraph or two to tell the
  # most important story about your snap. Keep it under 100 words though,
  # we live in tweetspace and your description wants to look good in the snap
  # store.
  description: |
    This is the best drum roll application out there.
    Install it and awe!

  # A guardrail to prevent you from releasing a snap to all your users before
  # it is ready.
  # `devel` will let you release only to the `edge` and `beta` channels in the
  # store. `stable` will let you release also to the `candidate` and `stable`
  # channels. More info about channels here:
  # https://snapcraft.io/docs/reference/channels
  grade: stable

  # Snaps can be setup to follow three different confinement policies:
  # `strict`, `devmode` and `classic`. A strict confinement where the snap
  # can only read and write in its own namespace is recommended. Extra
  # permissions for strict snaps can be declared as `plugs` for the app, which
  # are explained later. More info about confinement here:
  # https://snapcraft.io/docs/reference/confinement
  confinement: strict

  # Each binary built by GoReleaser is an app inside the snap. In this section
  # you can declare extra details for those binaries. It is optional.
  apps:

    # The name of the app must be the same name as the binary built.
    drumroll:

      # If your app requires extra permissions to work outside of its default
      # confined space, declare them here.
      # You can read the documentation about the available plugs and the
      # things they allow:
      # https://snapcraft.io/docs/reference/interfaces).
      plugs: ["home", "network"]

      # If you want your app to be autostarted and to always run in the
      # background, you can make it a simple daemon.
      daemon: simple

Note that GoReleaser will not install snapcraft nor any of its dependencies for you.

Homebrew

After releasing to GitHub, GoReleaser can generate and publish a homebrew-tap recipe into a repository that you have access to.

The brew section specifies how the formula should be created. You can check the Homebrew documentation and the formula cookbook for more details.

# .goreleaser.yml
brew:
  # Name of the recipe
  # Default to project name
  name: myproject

  # Reporitory to push the tap to.
  github:
    owner: user
    name: homebrew-tap

  # Allows you to set a custom download strategy.
  # Default is empty.
  download_strategy: GitHubPrivateRepositoryReleaseDownloadStrategy

  # Git author used to commit to the repository.
  # Defaults are shown.
  commit_author:
    name: goreleaserbot
    email: [email protected]

  # Folder inside the repository to put the formula.
  # Default is the root folder.
  folder: Formula

  # Caveats for the user of your binary.
  # Default is empty.
  caveats: "How to use this binary"

  # Your app's homepage.
  # Default is empty.
  homepage: "https://example.com/"

  # Your app's description.
  # Default is empty.
  description: "Software to create fast and easy drum rolls."

  # Setting this will prevent goreleaser to actually try to commit the updated
  # formula - instead, the formula file will be stored on the dist folder only,
  # leaving the responsibility of publishing it to the user.
  # Default is false.
  skip_upload: true

  # Packages your package depends on.
  dependencies:
    - git
    - zsh

  # Packages your source package depends on.
  build_dependencies:
    - make
    - gcc

  # Packages that conflict with your package.
  conflicts:
    - svn
    - bash

  # Specify for packages that run as a service.
  # Default is empty.
  plist: |
    <?xml version="1.0" encoding="UTF-8"?>
    ...

  # So you can `brew test` your formula.
  # Default is empty.
  test: |
    system "#{bin}/program --version"
    ...

  # Custom install script for brew.
  # Default is 'bin.install "program"'.
  install: |
    bin.install "program"
    ...

By defining the brew section, GoReleaser will take care of publishing the Homebrew tap. Assuming that the current tag is v1.2.3, the above configuration will generate a program.rb formula in the Formula folder of user/homebrew-tap repository:

class Program < Formula
  desc "How to use this binary"
  homepage "https://github.com/user/repo"
  url "https://github.com/user/repo/releases/download/v1.2.3/program_v1.2.3_macOs_64bit.zip"
  version "v1.2.3"
  sha256 "9ee30fc358fae8d248a2d7538957089885da321dca3f09e3296fe2058e7fff74"

  depends_on "git"
  depends_on "zsh"

  def install
    bin.install "program"
  end
end

Important“: Note that GoReleaser does not yet generate a valid homebrew-core formula. The generated formulas are meant to be published as homebrew taps, and in their current form will not be accepted in any of the official homebrew repositories.

Scoop

After releasing to GitHub, GoReleaser can generate and publish a Scoop App Manifest into a repository that you have access to.

The scoop section specifies how the manifest should be created. See the commented example bellow:

# .goreleaser.yml
scoop:
  # Repository to push the app manifest to.
  bucket:
    owner: user
    name: scoop-bucket

  # Git author used to commit to the repository.
  # Defaults are shown.
  commit_author:
    name: goreleaserbot
    email: [email protected]

  # Your app's homepage.
  # Default is empty.
  homepage: "https://example.com/"

  # Your app's description.
  # Default is empty.
  description: "Software to create fast and easy drum rolls."

  # Your app's license
  # Default is empty.
  license: MIT

By defining the scoop section, GoReleaser will take care of publishing the Scoop app. Assuming that the project name is drumroll and the current tag is v1.2.3, the above configuration will generate a drumroll.json manifest in the root of the repository specified in the bucket section.

{
  "version": "1.2.3",
  "architecture": {
    "64bit": {
      "url":
        "https://github.com/user/drumroll/releases/download/1.2.3/drumroll_1.2.3_windows_amd64.tar.gz",
      "bin": "drumroll.exe"
    },
    "32bit": {
      "url":
        "https://github.com/user/drumroll/releases/download/1.2.3/drumroll_1.2.3_windows_386.tar.gz",
      "bin": "drumroll.exe"
    }
  },
  "homepage": "https://example.com/"
}

Your users can then install your app by doing:

scoop bucket add app https://github.com/org/repo.git
scoop install app

You can check the Scoop documentation for more details.

Release

GoReleaser will create a GitHub release with the current tag, upload all the artifacts and generate the changelog based on the new commits since the previous tag.

Let’s see what can be customized in the release section:

# .goreleaser.yml
release:
  # Repo in which the release will be created.
  # Default is extracted from the origin remote URL.
  github:
    owner: user
    name: repo

  # If set to true, will not auto-publish the release.
  # Default is false.
  draft: true

  # If set to true, will mark the release as not ready for production.
  # Default is false.
  prerelease: true

  # You can change the name of the GitHub release.
  # This is parsed with the Go template engine and the following variables
  # are available:
  # - ProjectName
  # - Tag
  # - Version (Git tag without `v` prefix)
  # There is also a template function "time" that takes a Go time format
  # string to insert a formated timestamp into the release name.
  # Default is ``
  name_template: "{{.ProjectName}}-v{{.Version}}"

  # You can disable this pipe in order to not upload any artifacts to
  # GitHub.
  # Defaults to false.
  disable: true

Customize the changelog

You can customize how the changelog is generated using the changelog section in the config file:

# .goreleaser.yml
changelog:
  filters:
    # commit messages matching the regexp listed here will be removed from
    # the changelog
    # Default is empty
    exclude:
      - '^docs:'
      - typo
      - (?i)foo
    # could either be asc, desc or empty
    # Default is empty
    sort: asc

Custom release notes

You can specify a file containing your custom release notes, and pass it with the --release-notes=FILE flag. GoReleaser will then skip its own release notes generation, using the contents of your file instead. You can use Markdown to format the contents of your file.

On Unix systems you can also generate the release notes in-line by using process substitution. To list all commits since the last tag, but skip ones starting with Merge or docs, you could run this command:

$ goreleaser --release-notes <(some_changelog_generator)

Some changelog generators you can use:

Artifactory

Since v0.38.0, GoReleaser supports building and pushing artifacts into Artifactory.

How it works

You can declare multiple Artifactory instances. All binaries generated by your builds section will be pushed to each configured Artifactory.

If you have only one Artifactory instance, the configuration is as easy as adding the upload target and a username to your .goreleaser.yml file:

artifactories:
  - name: production
    target: http://<Your-Instance>:8081/artifactory/example-repo-local/{{ .ProjectName }}/{{ .Version }}/
    username: goreleaser

Prerequisites:

  • A running Artifactory instances
  • A user + password / API key with grants to upload an artifact

Target

The target is the URL to upload the artifacts to (without the name of the artifact).

An example configuration for goreleaser in upload mode binary with the target can look like

- mode: binary
  target: 'http://artifacts.company.com:8081/artifactory/example-repo-local/{{ .ProjectName }}/{{ .Version }}/{{ .Os }}/{{ .Arch }}{{ if .Arm }}{{ .Arm }}{{ end }}'

and will result in a final deployment like http://artifacts.company.com:8081/artifactory/example-repo-local/goreleaser/1.0.0/Darwin/x86_64/goreleaser.

Supported variables:

  • Version
  • Tag
  • ProjectName
  • Os
  • Arch
  • Arm

Attention: Variables Os, Arch and Arm are only supported in upload mode binary.

Password / API Key

Your configured username needs to be authenticated against your Artifactory.

The password or API key will be stored in a environment variable. The configured name of your Artifactory instance will be used. With this way we support auth for multiple instances. This also means that the name per configured instance needs to be unique per goreleaser configuration.

The name of the environment variable will be ARTIFACTORY_NAME_SECRET. If your instance is named production, you need to store the secret in the environment variable ARTIFACTORY_PRODUCTION_SECRET. The name will be transformed to uppercase.

Customization

Of course, you can customize a lot of things:

# .goreleaser.yml
artifactories:
  # You can have multiple Artifactory instances.
  -
    # Unique name of your artifactory instance. Used to identify the instance
    name: production
    # Upload mode. Valid options are `binary` and `archive`.
    # If mode is `archive`, variables _Os_, _Arch_ and _Arm_ for target name are not supported.
    # In that case these variables are empty.
    # Default is `archive`.
    mode: archive
    # URL of your Artifactory instance + path to deploy to
    target: http://artifacts.company.com:8081/artifactory/example-repo-local/{{ .ProjectName }}/{{ .Version }}/
    # User that will be used for the deployment
    username: deployuser

These settings should allow you to push your artifacts into multiple Artifactories.

Docker

Since v0.31.0, GoReleaser supports building and pushing Docker images.

How it works

You can declare multiple Docker images. They will be matched against the binaries generated by your builds section.

If you have only one build setup, the configuration is as easy as adding the name of your image to your .goreleaser.yml file:

dockers:
  - image: user/repo

You also need to create a Dockerfile in your project’s root folder:

FROM scratch
COPY mybin /
ENTRYPOINT ["/mybin"]

This configuration will build and push a Docker image named user/repo:tagname.

Customization

Of course, you can customize a lot of things:

# .goreleaser.yml
dockers:
  # You can have multiple Docker images.
  -
    # GOOS of the built binary that should be used.
    goos: linux
    # GOARCH of the built binary that should be used.
    goarch: amd64
    # GOARM of the built binary that should be used.
    goarm: ''
    # Name of the built binary that should be used.
    binary: mybinary
    # Docker image name.
    image: myuser/myimage
    # Skips the docker push. Could be useful if you also do draft releases.
    # Defaults to false.
    skip_push: false
    # Path to the Dockerfile (from the project root).
    dockerfile: Dockerfile
    # Template of the docker tag. Defaults to `{{ .Version }}`. Other allowed
    # fields are `.Tag`, `.Major`, `.Minor` and `.Patch` and
    # `.Env.VARIABLE_NAME`.
    tag_templates:
    - "{{ .Tag }}"
    - "{{ .Tag }}-{{ .Env.GO_VERSION }}"
    - "v{{ .Major }}"
    - latest
    # If your Dockerfile copies files other than the binary itself,
    # you should list them here as well.
    extra_files:
    - config.yml

These settings should allow you to generate multiple Docker images, for example, using multiple FROM statements, as well as generate one image for each binary in your project.

Passing environment variables to tag_template

You can do that by using {{ .Env.VARIABLE_NAME }} in the template, for example:

dockers:
  -
    tag_template: "{{ .Tag }}-{{ .Env.GOVERSION_NR }}"

Then you can run:

GOVERSION_NR=$(go version | awk '{print $3}') goreleaser

Keeping docker images updated for current major

Some users might want to when version to push docker tags :v1, :v1.6, :v1.6.4 and :latest when v1.6.4 (for example) is built. That can be accomplished by using multiple tag_templates:

# .goreleaser.yml
dockers:
  -
    binary: mybinary
    image: myuser/myimage
    tag_templates:
    - "{{ .Tag }}"
    - "v{{ .Major }}"
    - "v{{ .Major }}.{{ .Minor }}"
    - latest

This will build and publish the following images:

  • myuser/myimage:v1.6.4
  • myuser/myimage:v1
  • myuser/myimage:v1.6
  • myuser/myimage:latest

With these settings you can hopefully push several different docker images with multiple tags.

Continuous Integration

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 softwares.

Travis

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:
    - snapcraft

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

# 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.

Circle

Here is how to do it with CircleCI:

# circle.yml
deployment:
  tag:
    tag: /v[0-9]+(\.[0-9]+)*(-.*)*/
    owner: user
    commands:
      - curl -sL https://git.io/goreleaser | bash

Deprecation notices

This page will be used to list deprecation notices accross GoReleaser.

fpm

since 2018-02-17

FPM is deprecated in favor of nfpm, which is a simpler alternative written in Go. The objective is to remove the ruby dependency thus simplify the CI/CD pipelines.

Just replace the fpm keyword by nfpm in your goreleaser.yaml file.

Change this:

fpm:
  # ...

to this:

nfpm:
  # ...

docker.name_template

since 2018-01-19

This property was deprecated in favor of the pluralized name_templates. The idea is to be able to define several tags instead of just one.

Change this:

dockers:
- image: foo/bar
  name_template: '{{ .Tag }}'

to this:

dockers:
- image: foo/bar
  tag_templates:
    - '{{ .Tag }}'

docker.latest

since 2018-01-19

The latest field in Docker config is deprecated in favor of the newer tag_templates field.

Change this:

dockers:
- image: foo/bar
  latest: true

to this:

dockers:
- image: foo/bar
  tag_templates:
    - '{{ .Tag }}'
    - latest

Sponsors

Does your company use goreleaser? Help keep the project bug-free and feature rich by sponsoring the project.

Backers

Love our work and community? Become a backer.