How to Use GoReleaser to Automate GoLang Build Releases

To make the project more user-friendly and attractive, authors add docker images and make distribution builds for many different platforms. It is required for each new version of the project, even the minor. Therefore, it is necessary to write automation of this process because doing it by hand is very long and routine and it’s easy to make mistakes or forget something. Below I will tell you about the which automates the build of releases of golang projects almost without cost. GoReleaser In the article, all examples will be for GitHub. But these same techniques can be easily adapted to close projects, too. I have prepared to demonstrate the possibilities of GoReleaser. This project consists of two parts client and server. The server can count the number of words in the text, and the client can address the server with a query for word count. a simple project I need to make the use of the application as user-friendly as possible and I will need to: binary server (mac/linux/windows) binary client (mac/linux/windows) GoReleaser is a utility written in Go that can perform all these actions based on a simple yaml script (in fact, the utility can still do a lot of things useful). After installing on your OS, you need to run a command to get started: goreleaser init • Generating .goreleaser.yaml file • config created; please edit accordingly to your needs file=.goreleaser.yaml This command creates a file in the project root. So far it is empty and does nothing and I have to fill it. So, .goreleaser.yaml # This is an example .goreleaser.yml file with some sensible defaults. # Make sure to check the documentation at https://goreleaser.com before: hooks: # You may remove this if you don't use go modules. - go mod tidy # you may remove this if you don't need go generate - go generate ./... builds: - env: - CGO_ENABLED=0 goos: - linux - windows - darwin archives: - replacements: darwin: Darwin linux: Linux windows: Windows 386: i386 amd64: x86_64 checksum: name_template: 'checksums.txt' snapshot: name_template: "{{ incpatch .Version }}-next" changelog: sort: asc filters: exclude: - '^docs:' - '^test:' I’ll start by describing the builds section. It defines the go builds that should be started. This will create the binaries that we need. Let’s describe this: builds: - id: srv binary: srv env: - CGO_ENABLED=0 goos: - linux - windows - darwin main: ./cmd/server/main.go - id: cli binary: cli env: - CGO_ENABLED=0 goos: - linux - windows - darwin main: ./cmd/client/main.go In this configuration, I have set two builds because it is necessary to build the server and the client. Both build look about the same. I specify which should be used and how the resulting binary should be called. main.go Also, I pointed GOOS and listed the platforms for which I need to compile binaries, that is, the result should not be one client and server file, but three: Linux, Mac, and Windows. If the building were done manually, it would look like this: CGO_ENABLED=0 GOOS=darwin go build -o srv This is an example only for Mac and only for the server. That is, one building of 6. In addition to OS you can also specify architectures: goarch: - amd64 - arm - arm64 And then, each OS will still be built in additional binary for each architecture. In order not to collect any specific OS/architecture pairs that you do not need, you need to specify them in the list: ignore: - goos: darwin goarch: 386 - goos: linux goarch: arm goarm: 7 In my example, I will not do this so as not to complicate the understanding of the result with a large number of resulting files. The reader will later be able to add this to their real projects. Additional environment variables may also often be affected. For example on my latest projects I used , . All of them can be specified in the section , which is separate for each assembly. GOPROXY GOPRIVATE env Let me show you how building works: goreleaser release --skip-publish --snapshot • releasing... • loading config file file=.goreleaser.yaml • loading environment variables • getting and validating git state • ignoring errors because this is a snapshot error=git doesn't contain any tags. Either add a tag or use --snapshot • building... commit=87eea7148d7e07b947cdef49e0b1b6a8c406a60e latest tag=v0.0.0 • pipe skipped error=disabled during snapshot mode • parsing tag • running before hooks • running hook=go mod tidy • running hook=go generate ./... • setting defaults • snapshotting • building snapshot... version=0.0.1-next • checking distribution directory • loading go mod information • build prerequisites • writing effective config file • writing config=dist/config.yaml • building binaries • building binary=/Users/antgubarev/project/gorelex/dist/srv_darwin_arm64/srv • building binary=/Users/antgubarev/project/gorelex/dist/srv_linux_amd64/srv • building binary=/Users/antgubarev/project/gorelex/dist/srv_windows_386/srv.exe • building binary=/Users/antgubarev/project/gorelex/dist/srv_linux_arm64/srv • building binary=/Users/antgubarev/project/gorelex/dist/srv_windows_arm64/srv.exe • building binary=/Users/antgubarev/project/gorelex/dist/srv_windows_amd64/srv.exe • building binary=/Users/antgubarev/project/gorelex/dist/srv_linux_386/srv • building binary=/Users/antgubarev/project/gorelex/dist/srv_darwin_amd64/srv • building binary=/Users/antgubarev/project/gorelex/dist/cli_windows_386/cli.exe • building binary=/Users/antgubarev/project/gorelex/dist/cli_windows_amd64/cli.exe • building binary=/Users/antgubarev/project/gorelex/dist/cli_linux_386/cli • building binary=/Users/antgubarev/project/gorelex/dist/cli_linux_amd64/cli • building binary=/Users/antgubarev/project/gorelex/dist/cli_linux_arm64/cli • building binary=/Users/antgubarev/project/gorelex/dist/cli_darwin_amd64/cli • building binary=/Users/antgubarev/project/gorelex/dist/cli_darwin_arm64/cli • building binary=/Users/antgubarev/project/gorelex/dist/cli_windows_arm64/cli.exe • archives • creating archive=dist/gorelex_0.0.1-next_Linux_x86_64.tar.gz • creating archive=dist/gorelex_0.0.1-next_Linux_arm64.tar.gz • creating archive=dist/gorelex_0.0.1-next_Darwin_x86_64.tar.gz • creating archive=dist/gorelex_0.0.1-next_Darwin_arm64.tar.gz • creating archive=dist/gorelex_0.0.1-next_Windows_arm64.tar.gz • creating archive=dist/gorelex_0.0.1-next_Windows_i386.tar.gz • creating archive=dist/gorelex_0.0.1-next_Linux_i386.tar.gz • creating archive=dist/gorelex_0.0.1-next_Windows_x86_64.tar.gz • calculating checksums • storing artifact list • writing file=dist/artifacts.json • release succeeded after 3.39s From the log, you can see which files were collected and that all of them are in the directory. I passed two arguments at the start of the command: /dist By default, GoReleaser will publish files immediately. This is not required yet, as it is We’re still debugging, but we’ll need it later. --skip-publish Release should be created with a version. GoReleaser takes the version from the latest git tag. And since not yet, I need that flag. --snapshot Both of these flags will be frequently required during the preparation and debugging of future releases. I sometimes use a draft repository on the GitHub on which releases will be posted. So I have the ability to edit and improve my release system without affecting users. I highly recommend to do likewise. As you may have noticed in addition to the build files have also been archived. This is the next opportunity to talk about. The archive must contain everything your user needs to use the product. In the current example, this is the server and client file. By default, the archive name is built using the following template {{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}{{ if .Mips }}_{{ .Mips }}{{ end }} (you can also replace this template for your needs). The replacement section specifies appropriate replacements for variables in the template. By default this parameter is empty, but fortunately, the created has already specified the combinations, which are enough. .goreleaser.yaml The currently created archives contain both srv and client files. It may sometimes be necessary to have them in different archives. This can easily be done by: archives: - id: srv builds: - srv replacements: darwin: Darwin linux: Linux windows: Windows 386: i386 amd64: x86_64 name_template: "{{ .ProjectName }}_srv_{{ .Version }}_{{ .Os }}_{{ .Arch }}" files: - LICENSE - README.md - doc/server/* - id: cli builds: - cli replacements: darwin: Darwin linux: Linux windows: Windows 386: i386 amd64: x86_64 name_template: "{{ .ProjectName }}_cli_{{ .Version }}_{{ .Os }}_{{ .Arch }}" files: - LICENSE - README.md - doc/cli/* In this example, I have listed the archives that need to be created. In the section, I listed the builds that need to be archived. That is, you can distribute any files for the convenience of users. This can be useful in such projects where many components. builds For example, in addition to the client and the server, there may be other agents and utilities for backups and monitoring. Then there will be a reason to separate the CLI utility from the other servers. Executable files are not the only things that can get into the archive. As you could see in the example, I added a file with license and reads. And for each archive, you can set your own sets. It is convenient for the example which I quoted above. For CLI utility, the documentation set will be different from server utilities. And I can’t help but mention another possibility. Its hooks. before: hooks: - make clean - go mod tidy This functionality allows you to perform additional actions before building. For example, remove extra packages, or create a default configuration file, etc. I would recommend doing this as a step of the pipeline when it comes to embedding the GoReleaser in your continuous delivery system. But when this option is not available, hooks will be very useful. I usually add: rm -rf dist/ This is convenient when debugging because for building the target directory should be empty. So, the project is ready for the first release. Let me remind you that as part of this article I will release it on GitHub. Commit our . Don’t forget to add to ! These artifact files don’t exactly belong in the repository. Now you need to create a tag and immediately push it. .goreleaser.yaml /dist . gitignore git tag v0.1.0 git push --tags origin master GoReleaser requires a GitHub token to be able to use the GitHub API to create and edit releases. You can create it in your . You just need to put the flag on management of public repositories . settings Access public repositories export GITHUB_TOKEN=xxx Finally, start the building without additional flags The logs added information about the release creation in the GitHub repository. • publishing • scm releases • creating or updating release repo=antgubarev/pet tag=v0.1.0 • release updated url=https://github.com/antgubarev/pet/releases/tag/v0.1.0 • uploading to release file=dist/checksums.txt name=checksums.txt • uploading to release file=dist/pet_cli_0.1.0_Linux_x86_64.tar.gz name=pet_cli_0.1.0_Linux_x86_64.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Windows_i386.tar.gz name=pet_srv_0.1.0_Windows_i386.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Linux_x86_64.tar.gz name=pet_srv_0.1.0_Linux_x86_64.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Linux_i386.tar.gz name=pet_srv_0.1.0_Linux_i386.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Darwin_x86_64.tar.gz name=pet_srv_0.1.0_Darwin_x86_64.tar.gz • uploading to release file=dist/pet_cli_0.1.0_Linux_i386.tar.gz name=pet_cli_0.1.0_Linux_i386.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Windows_arm64.tar.gz name=pet_srv_0.1.0_Windows_arm64.tar.gz • uploading to release file=dist/pet_cli_0.1.0_Darwin_arm64.tar.gz name=pet_cli_0.1.0_Darwin_arm64.tar.gz • uploading to release file=dist/pet_cli_0.1.0_Windows_i386.tar.gz name=pet_cli_0.1.0_Windows_i386.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Linux_arm64.tar.gz name=pet_srv_0.1.0_Linux_arm64.tar.gz • uploading to release file=dist/pet_cli_0.1.0_Windows_arm64.tar.gz name=pet_cli_0.1.0_Windows_arm64.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Darwin_arm64.tar.gz name=pet_srv_0.1.0_Darwin_arm64.tar.gz • uploading to release file=dist/pet_cli_0.1.0_Windows_x86_64.tar.gz name=pet_cli_0.1.0_Windows_x86_64.tar.gz • uploading to release file=dist/pet_cli_0.1.0_Darwin_x86_64.tar.gz name=pet_cli_0.1.0_Darwin_x86_64.tar.gz • uploading to release file=dist/pet_cli_0.1.0_Linux_arm64.tar.gz name=pet_cli_0.1.0_Linux_arm64.tar.gz • uploading to release file=dist/pet_srv_0.1.0_Windows_x86_64.tar.gz name=pet_srv_0.1.0_Windows_x86_64.tar.gz • announcing • release succeeded after 7.08s Go to the release page and see Hurrah, everything worked out. Besides all the archives still created and changelog, which contains the commits that were made from the previous tag. This will help users to understand what has changed, and the developer from routinely describing it manually. And that’s the kind of simple thing that I did, in a short time, to organize the releases of the project. Of course, it was even more convenient to automate it with GitHub Workflow. But it goes beyond this topic. In future articles, I will describe how can open source project be made even more attractive with GitHub Workflow and capabilities. golangci-lint

How to Use GoReleaser to Automate GoLang Build Releases

Too Long; Didn't Read

Companies Mentioned

@antgubarev

RELATED STORIES