github.com/goreleaser/goreleaser@v1.25.1/www/docs/ci/actions.md (about) 1 # GitHub Actions 2 3 GoReleaser can also be used within our official [GoReleaser 4 Action][goreleaser-action] through [GitHub Actions][actions]. 5 6 You can create a workflow for pushing your releases by putting YAML 7 configuration to `.github/workflows/release.yml`. 8 9 ## Usage 10 11 ### Workflow 12 13 Below is a simple snippet to use this action in your workflow: 14 15 ```yaml 16 # .github/workflows/release.yml 17 name: goreleaser 18 19 on: 20 pull_request: 21 push: 22 # run only against tags 23 tags: 24 - "*" 25 26 permissions: 27 contents: write 28 # packages: write 29 # issues: write 30 31 jobs: 32 goreleaser: 33 runs-on: ubuntu-latest 34 steps: 35 - name: Checkout 36 uses: actions/checkout@v4 37 with: 38 fetch-depth: 0 39 - name: Set up Go 40 uses: actions/setup-go@v5 41 with: 42 go-version: stable 43 # More assembly might be required: Docker logins, GPG, etc. 44 # It all depends on your needs. 45 - name: Run GoReleaser 46 uses: goreleaser/goreleaser-action@v5 47 with: 48 # either 'goreleaser' (default) or 'goreleaser-pro' 49 distribution: goreleaser 50 # 'latest', 'nightly', or a semver 51 version: latest 52 args: release --clean 53 env: 54 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 55 # Your GoReleaser Pro key, if you are using the 'goreleaser-pro' distribution 56 # GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }} 57 ``` 58 59 !!! warning "Some things to look closely..." 60 61 #### The action does not install, configure or authenticate into dependencies 62 GoReleaser Action will not install nor setup any other software needed to 63 release. It's the user's responsibility to install and configure Go, Docker, 64 Syft, Cosign and any other tools the release might need. It's also the 65 user's responsibility to log in into tools that need it, such as docker. 66 67 #### Fetch depthness 68 Notice the `fetch-depth: 0` option on the `Checkout` workflow step. 69 It is required for GoReleaser to work properly. 70 Without that, GoReleaser might fail or behave incorrectly. 71 72 #### Tag fetching 73 Notice the `git fetch --force -tags`. This is needed if you use fields like 74 `TagBody`, `TagSubject` or `TagContents` in your templates. 75 For more information, take a look at 76 [actions/checkout#290](https://github.com/actions/checkout/issues/290). 77 78 !!! tip 79 80 For detailed instructions please follow GitHub Actions [workflow syntax][syntax]. 81 82 ### Signing 83 84 If [signing is enabled][signing] in your GoReleaser configuration, you can use 85 the [Import GPG][import-gpg] GitHub Action along with this one: 86 87 ```yaml 88 # .github/workflows/release.yml 89 jobs: 90 # ... 91 goreleaser: 92 # ... 93 steps: 94 # ... 95 - name: Import GPG key 96 id: import_gpg 97 uses: crazy-max/ghaction-import-gpg@v6 98 with: 99 gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} 100 passphrase: ${{ secrets.PASSPHRASE }} 101 - name: Run GoReleaser 102 uses: goreleaser/goreleaser-action@v5 103 with: 104 version: latest 105 args: release --clean 106 env: 107 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 108 GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }} 109 # ... 110 ``` 111 112 And reference the fingerprint in your signing configuration using the 113 `GPG_FINGERPRINT` environment variable: 114 115 ```yaml 116 # .goreleaser.yaml 117 signs: 118 - artifacts: checksum 119 cmd: gpg2 120 args: 121 - "--batch" 122 - "-u" 123 - "{{ .Env.GPG_FINGERPRINT }}" 124 - "--output" 125 - "${signature}" 126 - "--detach-sign" 127 - "${artifact}" 128 ``` 129 130 ## Customizing 131 132 ### Inputs 133 134 Following inputs can be used as `step.with` keys 135 136 | Name | Type | Default | Description | 137 | -------------- | ------ | ------------ | ---------------------------------------------------------------- | 138 | `distribution` | String | `goreleaser` | GoReleaser distribution, either `goreleaser` or `goreleaser-pro` | 139 | `version`[^1] | String | `latest` | GoReleaser version | 140 | `args` | String | | Arguments to pass to GoReleaser | 141 | `workdir` | String | `.` | Working directory (below repository root) | 142 | `install-only` | Bool | `false` | Just install GoReleaser | 143 144 [^1]: 145 Can be a fixed version like `v0.117.0` or a max satisfying SemVer one like 146 `~> 0.132`. In this case this will return `v0.132.1`. 147 148 ### Outputs 149 150 Following outputs are available 151 152 | Name | Type | Description | 153 | ----------- | ---- | ---------------------- | 154 | `artifacts` | JSON | Build result artifacts | 155 | `metadata` | JSON | Build result metadata | 156 157 ### Environment Variables 158 159 Following environment variables can be used as `step.env` keys 160 161 | Name | Description | 162 | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | 163 | `GITHUB_TOKEN` | [GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) as provided by `secrets` | 164 | `GORELEASER_KEY` | Your [GoReleaser Pro](https://goreleaser.com/pro) License Key, in case you are using the `goreleaser-pro` distribution | 165 166 ## Token Permissions 167 168 The following 169 [permissions](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token) 170 are required by GoReleaser: 171 172 - `contents: write` if you wish to 173 - [upload archives as GitHub Releases](/customization/release/), or 174 - publish to [Homebrew](/customization/homebrew/), or 175 [Scoop](/customization/scoop/) (assuming it's part of the same repository) 176 - or just `contents: read` if you don't need any of the above 177 - `packages: write` if you [push Docker images](/customization/docker/) to 178 GitHub 179 - `issues: write` if you use [milestone closing 180 capability](/customization/milestone/) 181 182 `GITHUB_TOKEN` permissions [are limited to the repository][about-github-token] 183 that contains your workflow. 184 185 If you need to push the homebrew tap to another repository, you must create a 186 custom [Personal Access Token][pat] with `repo` permissions and [add it as a 187 secret in the repository][secrets]. If you create a secret named `GH_PAT`, the 188 step will look like this: 189 190 ```yaml 191 # .github/workflows/release.yml 192 jobs: 193 # ... 194 goreleaser: 195 # ... 196 steps: 197 # ... 198 - name: Run GoReleaser 199 uses: goreleaser/goreleaser-action@v5 200 with: 201 version: latest 202 args: release --clean 203 env: 204 GITHUB_TOKEN: ${{ secrets.GH_PAT }} 205 # ... 206 ``` 207 208 You can also read the [GitHub documentation](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) about it. 209 210 ## What does it look like? 211 212 You can check [this example repository](https://github.com/goreleaser/example) for a real world example. 213 214 <a href="https://github.com/goreleaser/example/releases"> 215 <figure> 216 <img src="https://img.carlosbecker.dev/goreleaser-github.png"/> 217 <figcaption>Example release on GitHub.</figcaption> 218 </figure> 219 </a> 220 221 [goreleaser-action]: https://github.com/goreleaser/goreleaser-action 222 [actions]: https://github.com/features/actions 223 [syntax]: https://help.github.com/en/articles/workflow-syntax-for-github-actions#About-yaml-syntax-for-workflows 224 [signing]: https://goreleaser.com/customization/sign/ 225 [import-gpg]: https://github.com/crazy-max/ghaction-import-gpg 226 [github-token]: https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token 227 [about-github-token]: https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#about-the-github_token-secret 228 [pat]: https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/ 229 [secrets]: https://help.github.com/en/actions/automating-your-workflow-with-github-actions/creating-and-using-encrypted-secrets