GitHub Actions¶

GoReleaser can also be used within our official GoReleaser Action through GitHub Actions.

You can create a workflow for pushing your releases by putting YAML configuration to .github/workflows/release.yml.

Usage¶

Workflow¶

Below is a simple snippet to use this action in your workflow:

name: goreleaser

on:
  push:
    # run only against tags
    tags:
      - '*'

permissions:
  contents: write
  # packages: write
  # issues: write

jobs:
  goreleaser:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      - run: git fetch --force --tags
      - uses: actions/setup-go@v3
        with:
          go-version: '>=1.20.1'
          cache: true
      # More assembly might be required: Docker logins, GPG, etc. It all depends
      # on your needs.
      - uses: goreleaser/goreleaser-action@v4
        with:
          # either 'goreleaser' (default) or 'goreleaser-pro':
          distribution: goreleaser
          version: latest
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Your GoReleaser Pro key, if you are using the 'goreleaser-pro'
          # distribution:
          # GORELEASER_KEY: ${{ secrets.GORELEASER_KEY }}

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, Syft, Cosign and any other tools the release might need. It's also the user's responsibility to log in into tools that need it, such as docker.

Fetch depthness¶

Notice the fetch-depth: 0 option on the Checkout workflow step. It is required for GoReleaser to work properly. Without that, GoReleaser might fail or behave incorrectly.

Tag fetching¶

Notice the git fetch --force -tags. This is needed if you use fields like TagBody, TagSubject or TagContents in your templates. For more information, take a look at actions/checkout#290.

Caching go dependencies¶

When using the setup-go action, you can optionally set cache: true for it to aumatically cache and restore your go dependencies, which usually helps speed up build times.

Tip

For detailed instructions please follow GitHub Actions workflow syntax.

Signing¶

If signing is enabled in your GoReleaser configuration, you can use the Import GPG GitHub Action along with this one:

      -
        name: Import GPG key
        id: import_gpg
        uses: crazy-max/ghaction-import-gpg@v4
        with:
          gpg_private_key: ${{ secrets.GPG_PRIVATE_KEY }}
          passphrase: ${{ secrets.PASSPHRASE }}
      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v4
        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:

signs:
  - artifacts: checksum
    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`¹	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

Outputs¶

Following outputs are available

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 as provided by `secrets`
`GORELEASER_KEY`	Your GoReleaser Pro License Key, in case you are using the `goreleaser-pro` distribution

Token Permissions¶

The following permissions are required by GoReleaser:

contents: write if you wish to
- upload archives as GitHub Releases, or
- publish to Homebrew, or 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 to GitHub
issues: write if you use milestone closing capability

GITHUB_TOKEN permissions are limited to the repository that contains your workflow.

If you need to push the homebrew tap to another repository, you must create a custom Personal Access Token with repo permissions and add it as a secret in the repository. If you create a secret named GH_PAT, the step will look like this:

      -
        name: Run GoReleaser
        uses: goreleaser/goreleaser-action@v4
        with:
          version: latest
          args: release --clean
        env:
          GITHUB_TOKEN: ${{ secrets.GH_PAT }}

You can also read the GitHub documentation about it.

What does it look like?¶

You can check this example repository for a real world example.

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. ↩