github.com/marianogappa/goreleaser@v0.26.2-0.20170715090149-96acd0a9fc46/README.md (about) 1 <p align="center"> 2 <img alt="GoReleaser Logo" src="https://avatars2.githubusercontent.com/u/24697112?v=3&s=200" height="140" /> 3 <h3 align="center">GoReleaser</h3> 4 <p align="center">Deliver Go binaries as fast and easily as possible.</p> 5 <p align="center"> 6 <a href="https://github.com/goreleaser/goreleaser/releases/latest"><img alt="Release" src="https://img.shields.io/github/release/goreleaser/goreleaser.svg?style=flat-square"></a> 7 <a href="/LICENSE.md"><img alt="Software License" src="https://img.shields.io/badge/license-MIT-brightgreen.svg?style=flat-square"></a> 8 <a href="https://travis-ci.org/goreleaser/goreleaser"><img alt="Travis" src="https://img.shields.io/travis/goreleaser/goreleaser.svg?style=flat-square"></a> 9 <a href="https://codecov.io/gh/goreleaser/goreleaser"><img alt="Codecov branch" src="https://img.shields.io/codecov/c/github/goreleaser/goreleaser/master.svg?style=flat-square"></a> 10 <a href="https://goreportcard.com/report/github.com/goreleaser/goreleaser"><img alt="Go Report Card" src="https://goreportcard.com/badge/github.com/goreleaser/goreleaser?style=flat-square"></a> 11 <a href="http://godoc.org/github.com/goreleaser/goreleaser"><img alt="Go Doc" src="https://img.shields.io/badge/godoc-reference-blue.svg?style=flat-square"></a> 12 <a href="https://saythanks.io/to/caarlos0"><img alt="SayThanks.io" src="https://img.shields.io/badge/SayThanks.io-%E2%98%BC-1EAEDB.svg?style=flat-square"></a> 13 <a href="https://github.com/goreleaser"><img alt="Powered By: GoReleaser" src="https://img.shields.io/badge/powered%20by-goreleaser-green.svg?style=flat-square"></a> 14 </p> 15 </p> 16 17 --- 18 19 20 GoReleaser builds Go binaries for several platforms, creates a GitHub release and then 21 pushes a Homebrew formula to a repository. All that wrapped in your favorite CI. 22 23 This project adheres to the Contributor Covenant [code of conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. 24 We appreciate your contribution. Please refer to our [contributing guidelines](CONTRIBUTING.md) for further information. 25 26 For questions join the [#goreleaser](https://gophers.slack.com/messages/goreleaser/) channel in the [Gophers Slack](https://invite.slack.golangbridge.org/). 27 28 # Table of contents 29 30 - [Introduction](#introduction) 31 - [Quick start](#quick-start) 32 - [Environment setup](#environment-setup) 33 - [Release customization](#release-customization) 34 - [Integration with CI](#integration-with-ci) 35 36 ## Introduction 37 38 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. 39 40 GoReleaser is built for CI tools; you only need to [download and execute it](#integration-with-ci) in your build script. 41 You can [customize](#release-customization) your release process by createing a `.goreleaser.yml` file. 42 We are also working on integrating with package managers, we currently support Homebrew. 43 44 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. 45 46 ## Quick start 47 48 In this example we will build, archive and release a Golang project. 49 Create a GitHub repository and add a single main package: 50 ```go 51 // main.go 52 package main 53 54 func main() { 55 println("Ba dum, tss!") 56 } 57 ``` 58 59 By default GoReleaser will build the current directory, but you can change the build package path in the GoReleaser configuration file. 60 61 ```yml 62 # .goreleaser.yml 63 # Build customization 64 builds: 65 - binary: drum-roll 66 goos: 67 - windows 68 - darwin 69 - linux 70 goarch: 71 - amd64 72 ``` 73 74 PS: Invalid GOOS/GOARCH combinations will automatically be skipped. 75 76 This configuration specifies the build operating systems to Windows, Linux and MacOS using 64bit architecture, the name of the binaries is `drum-roll`. 77 78 GoReleaser will then archive the result binaries of each Os/Arch into a separate file. The default format is `{{.ProjectName}}_{{.Os}}_{{.Arch}}`. 79 You can change the archives name and format. You can also replace the OS and the Architecture with your own. 80 Another useful feature is to add files to archives, this is very useful for integrating assets like resource files. 81 82 ```yml 83 # .goreleaser.yml 84 # Build customization 85 builds: 86 - main: main.go 87 binary: drum-roll 88 goos: 89 - windows 90 - darwin 91 - linux 92 goarch: 93 - amd64 94 # Archive customization 95 archive: 96 format: tar.gz 97 replacements: 98 amd64: 64-bit 99 darwin: macOS 100 linux: Tux 101 files: 102 - drum-roll.licence.txt 103 ``` 104 105 This configuration will generate tar archives, contains an additional file `drum-roll.licence.txt`, the archives will be located in: 106 107 - `./dist/drum-roll_windows_64-bit.tar.gz` 108 - `./dist/drum-roll_macOS_64-bit.tar.gz` 109 - `./dist/drum-roll_Tux_64-bit.tar.gz` 110 111 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). 112 113 ```console 114 $ export GITHUB_TOKEN=`YOUR_TOKEN` 115 ``` 116 117 GoReleaser uses the latest [Git tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) of your repository. 118 Create a tag and push it to GitHub: 119 120 ```console 121 $ git tag -a v0.1.0 -m "First release" && git push origin v0.1.0 122 ``` 123 124 **Note**: we recommend the use of [semantic versioning](http://semver.org/). We 125 are not enforcing it though. We do remove the `v` prefix and then enforce 126 that the next character is a number. So, `v0.1.0` and `0.1.0` are virtually the 127 same and are both accepted, while `version0.1.0` is not. 128 129 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. 130 131 Now you can run GoReleaser at the root of your repository: 132 133 ```console 134 $ goreleaser 135 ``` 136 137 That's it! Check your GitHub project's release page. 138 The release should look like this: 139 140 [ 141 ](https://github.com/goreleaser/goreleaser/releases) 142 143 ## Environment setup 144 145 ### GitHub Token 146 147 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). 148 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). 149 150 ### A note about `main.version` 151 152 GoReleaser always sets a `main.version` ldflag. You can use it in your 153 `main.go` file: 154 155 ```go 156 package main 157 158 var version = "master" 159 160 func main() { 161 println(version) 162 } 163 ``` 164 165 `version` will be the current Git tag (with `v` prefix stripped) or the name of the snapshot if you're using the `--snapshot` flag. 166 167 ## GoReleaser customization 168 169 GoReleaser provides multiple customizations via the `.goreleaser.yml` file. 170 You can generate it by running `goreleaser init` or start from scratch. The 171 defaults are sensible and fit for most projects. 172 173 We'll cover all customizations available bellow: 174 175 ### Project name 176 177 ```yml 178 # .goreleaser.yml 179 # The name of the project. It is used in the name of the brew formula, archives, 180 # etc. Defaults to the name of the git project. 181 project_name: myproject 182 ``` 183 184 ### Build customization 185 186 ```yml 187 # .goreleaser.yml 188 builds: 189 # You can have multiple builds, its a common yaml list 190 - 191 # Path to main.go file or main package. 192 # Default is `.` 193 main: ./cmd/main.go 194 195 # Name of the binary. 196 # Default is the name of the project directory. 197 binary: program 198 199 # Custom build tags. 200 # Default is empty 201 flags: -tags dev 202 203 # Custom ldflags template. 204 # This is parsed with Golang template engine and the following variables 205 # are available: 206 # - Date 207 # - Commit 208 # - Tag 209 # - Version (Tag with the `v` prefix stripped) 210 # The default is `-s -w -X main.version={{.Version}} -X main.commit={{.Commit}} -X main.date={{.Date}}` 211 # Date format is `2006-01-02_15:04:05` 212 ldflags: -s -w -X main.build={{.Version}} 213 214 # Custom environment variables to be set durign the builds. 215 # Default is empty 216 env: 217 - CGO_ENABLED=0 218 219 # GOOS list to build in. 220 # For more info refer to https://golang.org/doc/install/source#environment 221 # Defaults are darwin and linux 222 goos: 223 - freebsd 224 - windows 225 226 # GOARCH to build in. 227 # For more info refer to https://golang.org/doc/install/source#environment 228 # Defaults are 386 and amd64 229 goarch: 230 - amd64 231 - arm 232 - arm64 233 234 # GOARM to build in when GOARCH is arm. 235 # For more info refer to https://golang.org/doc/install/source#environment 236 # Defaults are 6 237 goarm: 238 - 6 239 - 7 240 241 # List of combinations of GOOS + GOARCH + GOARM to ignore. 242 # Default is empty. 243 ignore: 244 - goos: darwin 245 goarch: 386 246 - goos: linux 247 goarch: arm 248 goarm: 7 249 250 # Hooks can be used to customize the final binary, for example, to run 251 # generator or whatever you want. 252 # Default is both hooks empty. 253 hooks: 254 pre: rice embed-go 255 post: ./script.sh 256 ``` 257 258 ### Archive customization 259 260 ```yml 261 # .goreleaser.yml 262 archive: 263 # You can change the name of the archive. 264 # This is parsed with Golang template engine and the following variables 265 # are available: 266 # - ProjectName 267 # - Tag 268 # - Version (Tag with the `v` prefix stripped) 269 # - Os 270 # - Arch 271 # - Arm (ARM version) 272 # The default is `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}` 273 name_template: "{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}" 274 275 # Archive format. Valid options are `tar.gz`, `zip` and `binary`. 276 # If format is `binary` no archives are created and the binaries are instead uploaded directly. 277 # In that case name_template the below specified files are ignored. 278 # Default is `tar.gz` 279 format: zip 280 281 # Can be used to archive on different formats for specific GOOSs. 282 # Most common use case is to archive as zip on Windows. 283 # Default is empty 284 format_overrides: 285 - goos: windows 286 format: zip 287 288 # Replacements for GOOS and GOARCH on the archive name. 289 # The keys should be valid GOOS or GOARCH values followed by your custom 290 # replacements. 291 replacements: 292 amd64: 64-bit 293 386: 32-bit 294 darwin: macOS 295 linux: Tux 296 297 # Additional files/globs you want to add to the archive. 298 # Defaults are any files matching `LICENCE*`, `LICENSE*`, 299 # `README*` and `CHANGELOG*` (case-insensitive) 300 files: 301 - LICENSE.txt 302 - README.md 303 - CHANGELOG.md 304 - docs/* 305 - design/*.png 306 ``` 307 308 ### Release customization 309 310 ```yml 311 # .goreleaser.yml 312 release: 313 # Repo in which the release will be created. 314 # Default is extracted from the origin remote URL. 315 github: 316 owner: user 317 name: repo 318 319 # If set to true, will not auto-publish the release. 320 # Default is false 321 draft: true 322 ``` 323 324 You can also specify a release notes file in markdown format using the 325 `--release-notes` flag. 326 327 ### Snapshot customization 328 329 ```yml 330 # .goreleaser.yml 331 snapshot: 332 # Allows you to change the name of the generated snapshot 333 # releases. The following variables are available: 334 # - Commit 335 # - Tag 336 # - Timestamp 337 # Default: SNAPSHOT-{{.Commit}} 338 name_template: SNAPSHOT-{{.Commit}} 339 ``` 340 341 ### Homebrew tap customization 342 343 The brew section specifies how the formula should be created. 344 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. 345 346 ```yml 347 # .goreleaser.yml 348 brew: 349 # Reporitory to push the tap to. 350 github: 351 owner: user 352 name: homebrew-tap 353 354 # Folder inside the repository to put the formula. 355 # Default is the root folder. 356 folder: Formula 357 358 # Caveats for the user of your binary. 359 # Default is empty. 360 caveats: "How to use this binary" 361 362 # Your app's homepage 363 # Default is empty 364 homepage: "https://example.com/" 365 366 # Your app's description 367 # Default is empty 368 description: "Software to create fast and easy drum rolls." 369 370 # Dependencies of your package 371 dependencies: 372 - git 373 - zsh 374 375 # Packages that conflict with your package 376 conflicts: 377 - svn 378 - bash 379 380 # Packages that run as a service 381 plist:| 382 <?xml version="1.0" encoding="UTF-8"?> 383 ... 384 385 # Custom install script for brew. Default: "bin.install "program" 386 install:| 387 bin.install "program" 388 ... 389 ``` 390 391 By defining the `brew` section, GoReleaser will take care of publishing the Homebrew tap. 392 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: 393 394 ```rb 395 class Program < Formula 396 desc "How to use this binary" 397 homepage "https://github.com/user/repo" 398 url "https://github.com/user/repo/releases/download/v1.2.3/program_v1.2.3_macOs_64bit.zip" 399 version "v1.2.3" 400 sha256 "9ee30fc358fae8d248a2d7538957089885da321dca3f09e3296fe2058e7fff74" 401 402 depends_on "git" 403 depends_on "zsh" 404 405 def install 406 bin.install "program" 407 end 408 end 409 ``` 410 411 ### FPM build customization 412 413 GoReleaser can be wired to [fpm]() to generate `.deb`, `.rpm` and other archives. Check its 414 [wiki](https://github.com/jordansissel/fpm/wiki) for more info. 415 416 [fpm]: https://github.com/jordansissel/fpm 417 418 ```yml 419 # .goreleaser.yml 420 fpm: 421 # Your app's vendor 422 # Default is empty 423 vendor: Drum Roll Inc. 424 # Your app's homepage 425 # Default is empty 426 homepage: https://example.com/ 427 428 # Your app's maintainer (probably you) 429 # Default is empty 430 maintainer: Drummer <drum-roll@example.com> 431 432 # Your app's description 433 # Default is empty 434 description: Software to create fast and easy drum rolls. 435 436 # Your app's license 437 # Default is empty 438 license: Apache 2.0 439 440 # Formats to generate as output 441 formats: 442 - deb 443 - rpm 444 445 # Dependencies of your package 446 dependencies: 447 - git 448 - zsh 449 450 # Packages that conflict with your package 451 conflicts: 452 - svn 453 - bash 454 ``` 455 456 Note that GoReleaser will not install `fpm` nor any of its dependencies for you. 457 458 ### Custom release notes 459 460 You can have a markdown file previously created with the release notes, and 461 pass it down to goreleaser with the `--release-notes=FILE` flag. 462 463 ## Integration with CI 464 465 You may want to wire this to auto-deploy your new tags on [Travis](https://travis-ci.org), for example: 466 467 ```yaml 468 # .travis.yml 469 after_success: 470 - test -n "$TRAVIS_TAG" && curl -sL https://git.io/goreleaser | bash 471 ``` 472 473 Here is how to do it with [CircleCI](https://circleci.com): 474 475 ```yml 476 # circle.yml 477 deployment: 478 tag: 479 tag: /v[0-9]+(\.[0-9]+)*(-.*)*/ 480 owner: user 481 commands: 482 - curl -sL https://git.io/goreleaser | bash 483 ``` 484 485 *Note that if you test multiple versions or multiple OSes you probably want to make sure GoReleaser is just run once* 486 487 ### Stargazers over time 488 489 [](https://starcharts.herokuapp.com/goreleaser/goreleaser) 490 491 492 --- 493 494 Would you like to fix something in the documentation? Feel free to open an [issue](https://github.com/goreleaser/goreleaser/issues).