golangci-lint-action

You can control how golangci-lint is installed using the version, version-file, and install-mode options.

version

Specifies the version of golangci-lint to use. The allowed values depend on the install-mode:

• binary (default): Supports versions like v2.3, v2.3.4, or latest.
• goinstall: Supports v2.3.4, latest, or a specific commit hash.
• none: The version is ignored.

version-file

Reads the version from a file relative to the project root or working-directory. Supports .golangci-lint-version and .tool-versions files. This only works when install-mode is set to binary.

install-mode

Determines the installation method:

• binary (default)
• goinstall (not recommended)
• none (only use if you want to skip installation)

install-only

If set to true, the action installs the binary but does not execute the linting process.

# Example: specifying a version
uses: golangci/golangci-lint-action@v9
with:
  version: v2.12

# Example: using a version file
uses: golangci/golangci-lint-action@v9
with:
  version-file: .tool-versions

# Example: only installing, not running
uses: golangci/golangci-lint-action@v9
with:
  install-only: true

You can use a GitHub Actions matrix strategy to run linting on multiple operating systems (e.g., ubuntu-latest, macos-latest, and windows-latest).

Important for Windows users: To ensure line endings are properly formatted for Windows builds, add a .gitattributes file to your repository root with the following content:

*.go text eol=lf

name: golangci-lint
on:
  push:
    branches:
      - main
      - master
  pull_request:

permissions:
  contents: read
  # Optional: allow read access to pull requests. Use with `only-new-issues` option.
  # pull-requests: read

jobs:
  golangci:
    strategy:
      matrix:
        go: [stable]
        os: [ubuntu-latest, macos-latest, windows-latest]
    name: lint
    runs-on: ${{ matrix.os }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: ${{ matrix.go }}
      - name: golangci-lint
        uses: golangci/golangci-lint-action@v9
        with:
          version: v2.12

In repositories using Go workspaces or multiple modules, you can dynamically detect modules and run the linter for each one using a matrix. This involves a detect-modules job that uses go list -m -json to find module directories, which are then passed to the golangci-lint job via job outputs.

name: golangci-lint

on:
  pull_request:
  push:
    branches:
      - main
      - master

env:
  GO_VERSION: stable
  GOLANGCI_LINT_VERSION: v2.12

jobs:
  detect-modules:
    runs-on: ubuntu-latest
    outputs:
      modules: ${{ steps.set-modules.outputs.modules }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: ${{ env.GO_VERSION }}
      - id: set-modules
        run: echo "modules=$(go list -m -json | jq -s '.' | jq -c '[.[].Dir]')" >> $GITHUB_OUTPUT

  golangci-lint:
    needs: detect-modules
    runs-on: ubuntu-latest
    strategy:
      matrix:
        modules: ${{ fromJSON(needs.detect-modules.outputs.modules) }}
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: ${{ env.GO_VERSION }}
      - name: golangci-lint ${{ matrix.modules }}
        uses: golangci/golangci-lint-action@v9
        with:
          version: ${{ env.GOLANGCI_LINT_VERSION }}
          working-directory: ${{ matrix.modules }}

Control how the linter runs using these options:

verify

(Default: true) Validates your golangci-lint configuration file. Set to false to skip validation.

working-directory

Sets the directory where golangci-lint runs. Useful for monorepos. Defaults to the project root.

args

Pass custom command-line arguments to golangci-lint. Important: Use = between flags and values (e.g., --flag=value) because the action parses arguments based on spaces.

only-new-issues

(Default: false) Shows only issues introduced in the current change.

• pull_request / pull_request_target: Uses the GitHub API to get the PR diff and applies --new-from-patch.
• push: Uses the GitHub API to get the commit diff and applies --new-from-patch.
• merge_group: Uses --new-from-rev (requires fetch-depth: 0 in actions/checkout).

When using only-new-issues, you may need to provide a github-token if the default github.token lacks sufficient permissions.

uses: golangci/golangci-lint-action@v9
with:
  working-directory: somedir
  args: --config=/my/path/.golangci.yml --issues-exit-code=0
  only-new-issues: true
  github-token: ${{ secrets.GITHUB_TOKEN }}

The action determines which version of golangci-lint to run using a specific priority order. You can specify the version via the version input, a version file, or by letting the action detect it from your project files.

Version Resolution Priority

1. version input: If provided, this takes highest precedence. If both version and version-file are provided, a warning is issued and only version is used.
2. go.mod detection: If version is empty, the action looks for github.com/golangci/golangci-lint/v2 in your go.mod file.
3. version-file input: If version is empty, the action reads the file specified in version-file.
   • If the file is .tool-versions (asdf/mise), it looks for a line starting with golangci-lint.
   • For other files (like .golangci-lint-version), it reads the content directly.
4. Default: If no version is found, it defaults to latest.

Supported Versions

• The action requires golangci-lint v2.1.0 or later.
• Versions where the major version is not 2 are not supported by golangci-lint-action (v7+).