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