diff --git a/www/docs/ci/actions.md b/www/docs/ci/actions.md index 72bb158e4..6b04d7691 100644 --- a/www/docs/ci/actions.md +++ b/www/docs/ci/actions.md @@ -13,13 +13,14 @@ configuration to `.github/workflows/release.yml`. Below is a simple snippet to use this action in your workflow: ```yaml +# .github/workflows/release.yml name: goreleaser on: push: # run only against tags tags: - - '*' + - "*" permissions: contents: write @@ -37,9 +38,9 @@ jobs: - uses: actions/setup-go@v4 with: go-version: stable - # More assembly might be required: Docker logins, GPG, etc. It all depends - # on your needs. - - uses: goreleaser/goreleaser-action@v4 + # More assembly might be required: Docker logins, GPG, etc. + # It all depends on your needs. + - uses: goreleaser/goreleaser-action@v5 with: # either 'goreleaser' (default) or 'goreleaser-pro': distribution: goreleaser @@ -53,6 +54,7 @@ jobs: ``` !!! warning "Some things to look closely..." + #### The action does not install, configure or authenticate into dependencies GoReleaser Action will not install nor setup any other software needed to release. It's the user's responsibility to install and configure Go, Docker, @@ -71,6 +73,7 @@ jobs: [actions/checkout#290](https://github.com/actions/checkout/issues/290). !!! tip + For detailed instructions please follow GitHub Actions [workflow syntax][syntax]. ### Signing @@ -79,69 +82,83 @@ If [signing is enabled][signing] in your GoReleaser configuration, you can use the [Import GPG][import-gpg] GitHub Action along with this one: ```yaml - - - name: Import GPG key +# .github/workflows/release.yml +jobs: + # ... + goreleaser: + # ... + steps: + # ... + - name: Import GPG key id: import_gpg - uses: crazy-max/ghaction-import-gpg@v4 + uses: crazy-max/ghaction-import-gpg@v6 with: gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }} passphrase: ${{ secrets.PASSPHRASE }} - - - name: Run GoReleaser - uses: goreleaser/goreleaser-action@v4 + - name: Run GoReleaser + uses: goreleaser/goreleaser-action@v5 with: version: latest args: release --clean env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} GPG_FINGERPRINT: ${{ steps.import_gpg.outputs.fingerprint }} + # ... ``` And reference the fingerprint in your signing configuration using the `GPG_FINGERPRINT` environment variable: ```yaml +# .goreleaser.yaml signs: - artifacts: checksum - args: ["--batch", "-u", "{{ .Env.GPG_FINGERPRINT }}", "--output", "${signature}", "--detach-sign", "${artifact}"] + cms: gpg2 + args: + - "--batch" + - "-u" + - "{{ .Env.GPG_FINGERPRINT }}" + - "--output" + - "${signature}" + - "--detach-sign" + - "${artifact}" ``` ## Customizing - - ### Inputs Following inputs can be used as `step.with` keys -Name |Type |Default |Description ---------------|------|------------|---------------------------------------------------------------- -`distribution`|String|`goreleaser`|GoReleaser distribution, either `goreleaser` or `goreleaser-pro` -`version`[^1] |String|`latest` |GoReleaser version -`args` |String| |Arguments to pass to GoReleaser -`workdir` |String|`.` |Working directory (below repository root) -`install-only`|Bool |`false` |Just install GoReleaser +| Name | Type | Default | Description | +| -------------- | ------ | ------------ | ---------------------------------------------------------------- | +| `distribution` | String | `goreleaser` | GoReleaser distribution, either `goreleaser` or `goreleaser-pro` | +| `version`[^1] | String | `latest` | GoReleaser version | +| `args` | String | | Arguments to pass to GoReleaser | +| `workdir` | String | `.` | Working directory (below repository root) | +| `install-only` | Bool | `false` | Just install GoReleaser | -[^1]: Can be a fixed version like `v0.117.0` or a max satisfying SemVer one like - `~> 0.132`. In this case this will return `v0.132.1`. +[^1]: + Can be a fixed version like `v0.117.0` or a max satisfying SemVer one like + `~> 0.132`. In this case this will return `v0.132.1`. ### Outputs Following outputs are available -Name |Type|Description ------------|----|---------------------- -`artifacts`|JSON|Build result artifacts -`metadata` |JSON|Build result metadata +| Name | Type | Description | +| ----------- | ---- | ---------------------- | +| `artifacts` | JSON | Build result artifacts | +| `metadata` | JSON | Build result metadata | ### Environment Variables Following environment variables can be used as `step.env` keys -Name |Description -----------------|--------------------------------------------------------------------------------------------------------------------------------------------------- -`GITHUB_TOKEN` |[GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) as provided by `secrets` -`GORELEASER_KEY`|Your [GoReleaser Pro](https://goreleaser.com/pro) License Key, in case you are using the `goreleaser-pro` distribution +| Name | Description | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| `GITHUB_TOKEN` | [GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token) as provided by `secrets` | +| `GORELEASER_KEY` | Your [GoReleaser Pro](https://goreleaser.com/pro) License Key, in case you are using the `goreleaser-pro` distribution | ## Token Permissions @@ -149,15 +166,15 @@ The following [permissions](https://docs.github.com/en/actions/reference/authentication-in-a-workflow#permissions-for-the-github_token) are required by GoReleaser: - - `contents: write` if you wish to - - [upload archives as GitHub Releases](/customization/release/), or - - publish to [Homebrew](/customization/homebrew/), or - [Scoop](/customization/scoop/) (assuming it's part of the same repository) - - or just `contents: read` if you don't need any of the above - - `packages: write` if you [push Docker images](/customization/docker/) to - GitHub - - `issues: write` if you use [milestone closing - capability](/customization/milestone/) +- `contents: write` if you wish to + - [upload archives as GitHub Releases](/customization/release/), or + - publish to [Homebrew](/customization/homebrew/), or + [Scoop](/customization/scoop/) (assuming it's part of the same repository) +- or just `contents: read` if you don't need any of the above +- `packages: write` if you [push Docker images](/customization/docker/) to + GitHub +- `issues: write` if you use [milestone closing + capability](/customization/milestone/) `GITHUB_TOKEN` permissions [are limited to the repository][about-github-token] that contains your workflow. @@ -168,14 +185,21 @@ secret in the repository][secrets]. If you create a secret named `GH_PAT`, the step will look like this: ```yaml - - - name: Run GoReleaser - uses: goreleaser/goreleaser-action@v4 +# .github/workflows/release.yml +jobs: + # ... + goreleaser: + # ... + steps: + # ... + - name: Run GoReleaser + uses: goreleaser/goreleaser-action@v5 with: version: latest args: release --clean env: GITHUB_TOKEN: ${{ secrets.GH_PAT }} + # ... ``` You can also read the [GitHub documentation](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token) about it.