go/goreleaser
go/goreleaser
1
0
Fork 0
mirror of https://github.com/goreleaser/goreleaser.git synced 2025-01-24 04:16:27 +02:00
Code Issues Releases Activity

Merge pull request #353 from goreleaser/docs

Browse Source 
new docs
This commit is contained in:
Carlos Alexandro Becker 2017-09-10 22:39:20 -03:00 committed by GitHub
commit ac2ecf05d9
19 changed files with 666 additions and 560 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
Makefile
View File

@ -2,7 +2,8 @@ SOURCE_FILES?=$$(go list ./... | grep -v /vendor/)
TEST_PATTERN?=. TEST_PATTERN?=.
TEST_OPTIONS?= TEST_OPTIONS?=
setup: ## Install all the build and lint dependencies # Install all the build and lint dependencies
setup:
go get -u github.com/alecthomas/gometalinter go get -u github.com/alecthomas/gometalinter
go get -u github.com/golang/dep/cmd/dep go get -u github.com/golang/dep/cmd/dep
go get -u github.com/pierrre/gotestcover go get -u github.com/pierrre/gotestcover
@ -10,16 +11,20 @@ setup: ## Install all the build and lint dependencies
dep ensure dep ensure
gometalinter --install gometalinter --install
test: ## Run all the tests # Run all the tests
test:
gotestcover $(TEST_OPTIONS) -covermode=atomic -coverprofile=coverage.txt $(SOURCE_FILES) -run $(TEST_PATTERN) -timeout=2m gotestcover $(TEST_OPTIONS) -covermode=atomic -coverprofile=coverage.txt $(SOURCE_FILES) -run $(TEST_PATTERN) -timeout=2m
cover: test ## Run all the tests and opens the coverage report # Run all the tests and opens the coverage report
cover: test
go tool cover -html=coverage.txt go tool cover -html=coverage.txt
fmt: ## gofmt and goimports all go files # gofmt and goimports all go files
fmt:
find . -name '*.go' -not -wholename './vendor/*' | while read -r file; do gofmt -w -s "$$file"; goimports -w "$$file"; done find . -name '*.go' -not -wholename './vendor/*' | while read -r file; do gofmt -w -s "$$file"; goimports -w "$$file"; done
lint: ## Run all the linters # Run all the linters
lint:
gometalinter --vendor --disable-all \ gometalinter --vendor --disable-all \
--enable=deadcode \ --enable=deadcode \
--enable=ineffassign \ --enable=ineffassign \
@ -35,13 +40,29 @@ lint: ## Run all the linters
--deadline=10m \ --deadline=10m \
./... ./...
ci: test lint ## Run all the tests and code checks # Run all the tests and code checks
ci: test lint
build: ## Build a beta version of goreleaser # Build a beta version of goreleaser
build:
go build go build
# Absolutely awesome: http://marmelab.com/blog/2016/02/29/auto-documented-makefile.html HIGHLIGHT=https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0
help:
@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}' # Generate the static documentation
static:
@static-docs \
--in docs \
--out ../goreleaser.github.io \
--title GoReleaser \
--subtitle "Deliver Go binaries as fast and easily as possible" \
--google UA-106198408-1 \
--script "$(HIGHLIGHT)/highlight.min.js" \
--script "$(HIGHLIGHT)/languages/go.min.js" \
--script "$(HIGHLIGHT)/languages/yaml.min.js" \
--style "$(HIGHLIGHT)/styles/atom-one-dark.min.css" \
--inline-script 'hljs.initHighlightingOnLoad();' \
--inline-style 'pre { padding: 0; }'
.DEFAULT_GOAL := build .DEFAULT_GOAL := build

553
README.md
View File

@ -16,7 +16,6 @@
--- ---
GoReleaser builds Go binaries for several platforms, creates a GitHub release and then GoReleaser builds Go binaries for several platforms, creates a GitHub release and then
pushes a Homebrew formula to a tap repository. All that wrapped in your favorite CI. pushes a Homebrew formula to a tap repository. All that wrapped in your favorite CI.
@ -25,556 +24,10 @@ We appreciate your contribution. Please refer to our [contributing guidelines](C
For questions join the [#goreleaser](https://gophers.slack.com/messages/goreleaser/) channel in the [Gophers Slack](https://invite.slack.golangbridge.org/). For questions join the [#goreleaser](https://gophers.slack.com/messages/goreleaser/) channel in the [Gophers Slack](https://invite.slack.golangbridge.org/).
# Table of contents ## Documentation
- [Introduction](#introduction) Documentation can be found in the [docs folder](docs) and live
- [Quick start](#quick-start) at https://goreleaser.com
- [Environment setup](#environment-setup)
- [Release customization](#release-customization)
- [Integration with CI](#integration-with-ci)
## Introduction
GoReleaser is a release automation tool for Golang 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](#integration-with-ci) in your build script.
You can [customize](#release-customization) your release process by createing a `.goreleaser.yml` file.
We are also working on integrating with package managers, we currently support Home
.
The idea started with a [simple shell script](https://github.com/goreleaser/old-go-releaser), but it quickly became more complex and I also wanted to publish binaries via Homebrew taps.
## Quick start
In this example we will build, archive and release a Golang project.
Create a GitHub repository and add a single main package:
```go
// main.go
package main
func main() {
println("Ba dum, tss!")
}
```
By default GoReleaser will build the current directory, but you can change the build package path in the GoReleaser configuration file.
```yml
# .goreleaser.yml
# Build customization
builds:
- binary: drum-roll
goos:
- windows
- darwin
- linux
goarch:
- amd64
```
PS: Invalid GOOS/GOARCH combinations will automatically be skipped.
This configuration specifies the build operating systems to Windows, Linux and MacOS using 64bit architecture, the name of the binaries is `drum-roll`.
GoReleaser will then archive the result binaries of each Os/Arch into a separate file. The default format is `{{.ProjectName}}_{{.Os}}_{{.Arch}}`.
You can change the archives name and format. You can also replace the OS and the Architecture with your own.
Another useful feature is to add files to archives, this is very useful for integrating assets like resource files.
```yml
# .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, contains an additional file `drum-roll.licence.txt`, the archives will be located in:
- `./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 export a `GITHUB_TOKEN` environment variable with the `repo` scope selected. This will be used to deploy releases to your GitHub repository. Create yours [here](https://github.com/settings/tokens/new).
```console
$ export GITHUB_TOKEN=`YOUR_TOKEN`
```
GoReleaser uses the latest [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your repository.
Create a tag and push it to GitHub:
```console
$ git tag -a v0.1.0 -m "First release" && git push origin v0.1.0
```
**Note**: we recommend the use of [semantic versioning](http://semver.org/). 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 are both accepted, while `version0.1.0` is not.
If you don't want to create a tag yet but instead simply create a package based on the latest commit, then you can also use the `--snapshot` flag.
Now you can run GoReleaser at the root of your repository:
```console
$ goreleaser
```
That's it! Check your GitHub project's release page.
The release should look like this:
[![image](https://cloud.githubusercontent.com/assets/245435/23342061/fbcbd506-fc31-11e6-9d2b-4c1b776dee9c.png)
](https://github.com/goreleaser/goreleaser/releases)
## Environment setup
### GitHub Token
GoReleaser requires a GitHub API token with the `repo` scope checked to deploy the artefacts to GitHub. You can create one [here](https://github.com/settings/tokens/new).
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](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings).
### A note about `main.version`
GoReleaser always sets a `main.version` ldflag. You can use it in your
`main.go` file:
```go
package main
var version = "master"
func main() {
println(version)
}
```
`version` will be the current Git tag (with `v` prefix stripped) or the name of the snapshot if you're using the `--snapshot` flag.
## GoReleaser 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
```yml
# .goreleaser.yml
# The name of the project. It is used in the name of the brew formula, archives,
# etc. Defaults to the name of the git project.
project_name: myproject
```
### Build customization
```yml
# .goreleaser.yml
builds:
# You can have multiple builds, its a common yaml list
-
# Path to main.go file or main package.
# Default is `.`
main: ./cmd/main.go
# Name of the binary.
# Default is the name of the project directory.
binary: program
# Custom build tags.
# Default is empty
flags: -tags dev
# Custom ldflags template.
# This is parsed with Golang template engine and the following variables
# are available:
# - Date
# - Commit
# - Tag
# - Version (Tag with the `v` prefix stripped)
# The default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}`
# Date format is `2006-01-02_15:04:05`
ldflags: -s -w -X main.build={{.Version}}
# Custom environment variables to be set durign the builds.
# Default is empty
env:
- CGO_ENABLED=0
# GOOS list to build in.
# For more info refer to https://golang.org/doc/install/source#environment
# Defaults are darwin and linux
goos:
- freebsd
- windows
# GOARCH to build in.
# For more info refer to https://golang.org/doc/install/source#environment
# Defaults are 386 and amd64
goarch:
- amd64
- arm
- arm64
# GOARM to build in when GOARCH is arm.
# For more info refer to https://golang.org/doc/install/source#environment
# Defaults are 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
# generator or whatever you want.
# Default is both hooks empty.
hooks:
pre: rice embed-go
post: ./script.sh
```
### Archive customization
```yml
# .goreleaser.yml
archive:
# You can change the name of the archive.
# This is parsed with Golang template engine and the following variables
# are available:
# - ProjectName
# - Tag
# - Version (Tag with the `v` prefix stripped)
# - Os
# - Arch
# - Arm (ARM version)
# The default is `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
# 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 the below specified files are ignored.
# Default is `tar.gz`
format: zip
# Can be used to archive on different formats for specific GOOSs.
# Most common use case is to archive as zip on Windows.
# Default is empty
format_overrides:
- goos: windows
format: zip
# Replacements for GOOS and GOARCH on the archive name.
# The keys should be valid GOOS or GOARCH values followed by your custom
# replacements.
replacements:
amd64: 64-bit
386: 32-bit
darwin: macOS
linux: Tux
# 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
```
### Release customization
```yml
# .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
```
You can also specify a release notes file in markdown format using the
`--release-notes` flag.
### Snapshot customization
```yml
# .goreleaser.yml
snapshot:
# Allows you to change the name of the generated snapshot
# releases. The following variables are available:
# - Commit
# - Tag
# - Timestamp
# Default: SNAPSHOT-{{.Commit}}
name_template: SNAPSHOT-{{.Commit}}
```
### Checksums file customization
```yml
# .goreleaser.yml
checksum:
# You can change the name of the checksums file.
# This is parsed with Golang template engine and the following variables
# are available:
# - ProjectName
# - Tag
# - Version (Tag with the `v` prefix stripped)
# The default is `{{ .ProjectName }}_{{ .Version }}_checksums.txt`
name_template: "{{ .ProjectName }}_checksums.txt"
```
### Homebrew tap customization
The brew section specifies how the formula should be created.
Check [the Homebrew documentation](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md) and the [formula cookbook](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md) for details.
```yml
# .goreleaser.yml
brew:
# Reporitory to push the tap to.
github:
owner: user
name: homebrew-tap
# 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."
# Dependencies of your package
dependencies:
- git
- zsh
# Packages that conflict with your package
conflicts:
- svn
- bash
# 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 config will generate a `program.rb` formula in the `Formula` folder of `user/homebrew-tap` repository:
```rb
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
```
Note that GoReleaser does not yet generate a valid homebrew-core formula. The generated formulas
are meant to be published as [homebrew taps](https://docs.brew.sh/brew-tap.html), not in any
of the official homebrew repositories.
### FPM build customization
GoReleaser can be wired to [fpm]() to generate `.deb`, `.rpm` and other archives. Check its
[wiki](https://github.com/jordansissel/fpm/wiki) for more info.
[fpm]: https://github.com/jordansissel/fpm
```yml
# .goreleaser.yml
fpm:
# 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 <drum-roll@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: Apache 2.0
# Formats to generate as output
formats:
- deb
- rpm
# Dependencies of your package
dependencies:
- git
- zsh
# Packages that conflict with your package
conflicts:
- svn
- bash
# Files or directories to add to your package (beyond the binary)
files:
"scripts/etc/init.d/": "/etc/init.d"
```
Note that GoReleaser will not install `fpm` nor any of its dependencies for you.
### Snapcraft build customization
GoReleaser can generate `snap` packages. [Snaps](http://snapcraft.io/) 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](https://snapcraft.io/docs/core/install), with automatic and transactional updates.
You can read more about it in the [snapcraft docs](https://snapcraft.io/docs/).
```yml
# .goreleaser.yml
snapcraft:
# The name of the snap. This is optional and defaults to the 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 of the binary built.
drumroll:
# If your app requires extra permissions to work outside of its default
# confined space, delcare 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.
### Custom release notes
You can have a markdown file previously created with the release notes, and
pass it down to goreleaser with the `--release-notes=FILE` flag.
## Integration with CI
You may want to wire this to auto-deploy your new tags on [Travis](https://travis-ci.org), for example:
```yaml
# .travis.yml
after_success:
- test -n "$TRAVIS_TAG" && curl -sL https://git.io/goreleaser | bash
```
Here is how to do it with [CircleCI](https://circleci.com):
```yml
# circle.yml
deployment:
tag:
tag: /v[0-9]+(\.[0-9]+)*(-.*)*/
owner: user
commands:
- curl -sL https://git.io/goreleaser | bash
```
*Note that if you test multiple versions or multiple OSes you probably want to make sure GoReleaser is just run once*
### Stargazers over time ### Stargazers over time

14
docs/000-introduction.md Normal file
View File

@ -0,0 +1,14 @@
---
title: Introduction
---
GoReleaser is a release automation tool for Golang 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](#integration-with-ci) in your build script.
You can [customize](#release-customization) your release process by createing a `.goreleaser.yml` file.
The idea started with a
[simple shell script](https://github.com/goreleaser/old-go-releaser),
but it quickly became more complex and I also wanted to publish binaries via
Homebrew taps, which would made the script even more hacky, so I let go of
that and rewrote the whole thing in Go.

113
docs/010-quick-start.md Normal file
View File

@ -0,0 +1,113 @@
---
title: Quick Start
---
In this example we will build, archive and release a Golang project.
Create a GitHub repository and add a single main package:
```go
// main.go
package main
func main() {
println("Ba dum, tss!")
}
```
By default GoReleaser will build the current directory, but you can change
the build package path in the GoReleaser configuration file.
```yml
# .goreleaser.yml
# Build customization
builds:
- binary: drum-roll
goos:
- windows
- darwin
- linux
goarch:
- amd64
```
PS: Invalid GOOS/GOARCH combinations will automatically be skipped.
This configuration specifies the build operating systems to Windows, Linux and
MacOS using 64bit architecture, the name of the binaries is `drum-roll`.
GoReleaser will then archive the result binaries of each Os/Arch into a
separate file. The default format is `{{.ProjectName}}_{{.Os}}_{{.Arch}}`.
You can change the archives name and format. You can also replace the OS
and the Architecture with your own.
Another useful feature is to add files to archives, this is very useful for
integrating assets like resource files.
```yml
# .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, 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 export a `GITHUB_TOKEN` environment variable with the `repo` scope
selected. This will be used to deploy releases to your GitHub repository.
Create yours [here](https://github.com/settings/tokens/new).
```console
$ export GITHUB_TOKEN=`YOUR_TOKEN`
```
GoReleaser uses the latest
[Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your repository.
Create a tag and push it to GitHub:
```console
$ git tag -a v0.1.0 -m "First release"
$ git push origin v0.1.0
```
**Note**: @e recommend the use of [semantic versioning](http://semver.org/). 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 are both accepted, while `version0.1.0` is not.
If you don't want to create a tag yet but instead simply create a package
based on the latest commit, then you can also use the `--snapshot` flag.
Now you can run GoReleaser at the root of your repository:
```console
$ goreleaser
```
That's it! Check your GitHub project's release page.
The release should look like this:
<a href="https://github.com/goreleaser/goreleaser/releases">
<img width="100%"
src="https://cloud.githubusercontent.com/assets/245435/23342061/fbcbd506-fc31-11e6-9d2b-4c1b776dee9c.png">
</a>

33
docs/020-environment.md Normal file
View File

@ -0,0 +1,33 @@
---
title: Environment Setup
---
### GitHub Token
GoReleaser requires a GitHub API token with the `repo` scope checked to
deploy the artefacts to GitHub. You can create one
[here](https://github.com/settings/tokens/new).
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](https://docs.travis-ci.com/user/environment-variables/#Defining-Variables-in-Repository-Settings).
### A note about `main.version`
GoReleaser always sets a `main.version` ldflag. You can use it in your
`main.go` file:
```go
package main
var version = "master"
func main() {
println(version)
}
```
`version` will be the current Git tag (with `v` prefix 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.

9
docs/030-customization.md Normal file
View File

@ -0,0 +1,9 @@
---
title: 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.

12
docs/040-project.md Normal file
View File

@ -0,0 +1,12 @@
---
title: Custom project name
---
The project name is used in the name of the brew formula, archives, etc.
If none is given, it will be infered from the name of the git project.
```yaml
# .goreleaser.yml
project_name: myproject
```

80
docs/050-build.md Normal file
View File

@ -0,0 +1,80 @@
---
title: Custom builds
---
Builds can be customized in multiple ways. You can change which `GOOS` and
`GOARCH` would be built, the name of the binary, flags, ldflags, hooks and etc.
Here is a full commented `builds` section:
```yml
# .goreleaser.yml
builds:
# You can have multiple builds defined as a common yaml list
-
# Path to main.go file or main package.
# Default is `.`
main: ./cmd/main.go
# Name of the binary.
# Default is the name of the project directory.
binary: program
# Custom build tags.
# Default is empty
flags: -tags dev
# Custom ldflags template.
# This is parsed with Golang template engine and the following variables
# are available:
# - Date
# - Commit
# - Tag
# - Version (Tag with the `v` prefix stripped)
# The default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}`
# Date format is `2006-01-02_15:04:05`
ldflags: -s -w -X main.build={{.Version}}
# Custom environment variables to be set durign the builds.
# Default is empty
env:
- CGO_ENABLED=0
# GOOS list to build in.
# For more info refer to https://golang.org/doc/install/source#environment
# Defaults are darwin and linux
goos:
- freebsd
- windows
# GOARCH to build in.
# For more info refer to https://golang.org/doc/install/source#environment
# Defaults are 386 and amd64
goarch:
- amd64
- arm
- arm64
# GOARM to build in when GOARCH is arm.
# For more info refer to https://golang.org/doc/install/source#environment
# Defaults are 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
# generator or whatever you want.
# Default is both hooks empty.
hooks:
pre: rice embed-go
post: ./script.sh
```

57
docs/060-archive.md Normal file
View File

@ -0,0 +1,57 @@
---
title: Custom archiving
---
The binaries built will be archived within the README and LICENSE files into a
`tar.gz` file. In the `archive` section you can customize the archive name,
files, and format.
Here is a full commented `archive` section:
```yml
# .goreleaser.yml
archive:
# You can change the name of the archive.
# This is parsed with Golang template engine and the following variables
# are available:
# - ProjectName
# - Tag
# - Version (Tag with the `v` prefix stripped)
# - Os
# - Arch
# - Arm (ARM version)
# The default is `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}`
name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}"
# 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 the below specified files are ignored.
# Default is `tar.gz`
format: zip
# Can be used to archive on different formats for specific GOOSs.
# Most common use case is to archive as zip on Windows.
# Default is empty
format_overrides:
- goos: windows
format: zip
# Replacements for GOOS and GOARCH on the archive name.
# The keys should be valid GOOS or GOARCH values followed by your custom
# replacements.
replacements:
amd64: 64-bit
386: 32-bit
darwin: macOS
linux: Tux
# 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
```

22
docs/070-checksum.md Normal file
View File

@ -0,0 +1,22 @@
---
title: Custom checksum
---
GoRelease generates a `project_1.0.0_checksums.txt` and uploads it to the
release as well, so your users can validate if the downloaded files are
right.
The `checksum` section allows the customization of the filename:
```yml
# .goreleaser.yml
checksum:
# You can change the name of the checksums file.
# This is parsed with Golang template engine and the following variables
# are available:
# - ProjectName
# - Tag
# - Version (Tag with the `v` prefix stripped)
# The default is `{{ .ProjectName }}_{{ .Version }}_checksums.txt`
name_template: "{{ .ProjectName }}_checksums.txt"
```

20
docs/080-snapshots.md Normal file
View File

@ -0,0 +1,20 @@
---
title: Snapshots
---
Sometimes we want to generate a full build of our project for some reason,
but don't want to validate anything nor upload it to anywhere.
GoRelease supports this with a `--snapshot` flag and with a `snapshot`
customization section as well.
```yml
# .goreleaser.yml
snapshot:
# Allows you to change the name of the generated snapshot
# releases. The following variables are available:
# - Commit
# - Tag
# - Timestamp
# Default: SNAPSHOT-{{.Commit}}
name_template: SNAPSHOT-{{.Commit}}
```

51
docs/100-fpm.md Normal file
View File

@ -0,0 +1,51 @@
---
title: Custom linux packages
---
GoReleaser can be wired to [fpm](https://github.com/jordansissel/fpm) to generate `.deb`, `.rpm` and other archives. Check its
[wiki](https://github.com/jordansissel/fpm/wiki) for more info.
```yml
# .goreleaser.yml
fpm:
# 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 <drum-roll@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: Apache 2.0
# Formats to generate as output
formats:
- deb
- rpm
# Dependencies of your package
dependencies:
- git
- zsh
# Packages that conflict with your package
conflicts:
- svn
- bash
# Files or directories to add to your package (beyond the binary)
files:
"scripts/etc/init.d/": "/etc/init.d"
```
Note that GoReleaser will not install `fpm` nor any of its dependencies for you.

63
docs/110-snapcraft.md Normal file
View File

@ -0,0 +1,63 @@
---
title: Snapcraft
---
GoReleaser can generate `snap` packages. [Snaps](http://snapcraft.io/) 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](https://snapcraft.io/docs/core/install), with automatic and transactional updates.
You can read more about it in the [snapcraft docs](https://snapcraft.io/docs/).
```yml
# .goreleaser.yml
snapcraft:
# The name of the snap. This is optional and defaults to the 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 of the binary built.
drumroll:
# If your app requires extra permissions to work outside of its default
# confined space, delcare 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.

30
docs/115-release.md Normal file
View File

@ -0,0 +1,30 @@
---
title: Custom releasing
---
GoRelease will create a release in GitHub with the current tag, upload all
the archives and checksums, also generating a changelog from the commit
log between the current and previous tags.
Let's see what can be customized in the `release` section:
```yml
# .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
```
## Custom release notes
You can have a markdown file previously created with the release notes, and
pass it down to goreleaser with the `--release-notes=FILE` flag.
GoReleaser will then skip its own release notes generation,
using the contents of your file instead.

90
docs/120-homebrew.md Normal file
View File

@ -0,0 +1,90 @@
---
title: Custom homebrew tap
---
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](https://github.com/Homebrew/brew/blob/master/docs/How-to-Create-and-Maintain-a-Tap.md)
and the
[formula cookbook](https://github.com/Homebrew/brew/blob/master/docs/Formula-Cookbook.md)
for more details.
```yml
# .goreleaser.yml
brew:
# Reporitory to push the tap to.
github:
owner: user
name: homebrew-tap
# 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."
# Dependencies of your package
dependencies:
- git
- zsh
# Packages that conflict with your package
conflicts:
- svn
- bash
# 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 config will generate a
`program.rb` formula in the `Formula` folder of `user/homebrew-tap` repository:
```rb
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](https://docs.brew.sh/brew-tap.html), and in their current
form will not be accepted in any of the official homebrew repositories.

25
docs/140-ci.md Normal file
View File

@ -0,0 +1,25 @@
---
title: CI integration
---
You may want to wire this to auto-deploy your new tags on [Travis](https://travis-ci.org), for example:
```yaml
# .travis.yml
after_success:
- test -n "$TRAVIS_TAG" && curl -sL https://git.io/goreleaser | bash
```
Here is how to do it with [CircleCI](https://circleci.com):
```yml
# circle.yml
deployment:
tag:
tag: /v[0-9]+(\.[0-9]+)*(-.*)*/
owner: user
commands:
- curl -sL https://git.io/goreleaser | bash
```
*Note that if you test multiple versions or multiple OSes you probably want to make sure GoReleaser is just run once*

13
docs/999-links.md Normal file
View File

@ -0,0 +1,13 @@
---
title: Links
---
- Follow the progress on [GitHub repository](https://github.com/goreleaser/goreleaser)
- Follow [@caarlos0](https://twitter.com/caarlos0) on Twitter for updates
- [Slack](https://gophers.slack.com/messages/goreleaser/) to chat about GoReleaser,
quetions and etc. Join using [this link](https://invite.slack.golangbridge.org/).
- [Contributing Guidelines](https://github.com/goreleaser/goreleaser/blob/master/CONTRIBUTING.md)
This project adheres to the Contributor Covenant
[code of conduct](https://github.com/goreleaser/goreleaser/blob/master/CODE_OF_CONDUCT.md).
By participating, you are expected to uphold this code.

BIN
docs/apple-touch-icon-144-precomposed.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.6 KiB

BIN
docs/favicon.ico Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 13 KiB