golangci-lint-action

golangci-lint-action

It's the official GitHub Action for golangci-lint from its authors.

The action runs golangci-lint and reports issues from linters.

Supporting Us

golangci-lint is a free and open-source project built by volunteers.

If you value it, consider supporting us; we appreciate it! :heart:

How to use

We recommend running this action in a job separate from other jobs (go test, etc.) because different jobs run in parallel.

Add a .github/workflows/golangci-lint.yml file with the following contents:

Simple Example

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:
    name: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-go@v6
        with:
          go-version: stable
      - name: golangci-lint
        uses: golangci/golangci-lint-action@v9
        with:
          version: v2.13

Multiple OS Example

…

You will also likely need to add the following .gitattributes file to ensure that line endings for Windows builds are properly formatted:

*.go text eol=lf

Go Workspace Example

…

Go Workspace Example (Multiple OS)

# ./.github/workflows/golangci-lint.yml
name: golangci-lint (multi OS)

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

jobs:
  golangci-lint:
    strategy:
      matrix:
        go-version: [ stable, oldstable ]
        os: [ubuntu-latest, macos-latest, windows-latest]
    uses: ./.github/workflows/.golangci-lint-reusable.yml
    with:
      os: ${{ matrix.os }}
      go-version: ${{ matrix.go-version }}
      golangci-lint-version: v2.13

…

You will also likely need to add the following .gitattributes file to ensure that line endings for Windows builds are properly formatted:

*.go text eol=lf

Compatibility

• v9.0.0 requires Nodejs runtime node24
• v8.0.0 works with golangci-lint version >= v2.1.0
• v7.0.0 supports golangci-lint v2 only.
• v6.0.0+ removes annotations option, removes the default output format (github-actions).
• v5.0.0+ removes skip-pkg-cache and skip-build-cache because the cache related to Go itself is already handled by actions/setup-go.
• v4.0.0+ requires an explicit actions/setup-go installation step before using this action: uses: actions/setup-go@v5. The skip-go-installation option has been removed.
• v2.0.0+ works with golangci-lint version >= v1.28.3
• v1.2.2 is deprecated because we forgot to change the minimum version of golangci-lint to v1.28.3 (issue)
• v1.2.1 works with golangci-lint version >= v1.14.0 (issue)

Options

Overview

Option Description version The version of golangci-lint to use. version-file Gets the version of golangci-lint to use from a file. install-mode The mode to install golangci-lint. install-only Only install golangci-lint. verify Validates golangci-lint configuration file. github-token Used by the only-new-issues option. only-new-issues Show only new issues. working-directory The golangci-lint working directory. args Golangci-lint command line arguments. skip-cache Disable cache support. skip-save-cache Don't save cache. cache-invalidation-interval Number of days before cache invalidation. problem-matchers Forces the usage of the embedded problem matchers. Experimental Experimental options

Installation

version

(optional)

The version of golangci-lint to use.

When install-mode is:

• binary (default): the value can be v2.3, v2.3.4, or latest to use the latest version.
• goinstall: the value can be v2.3.4, latest, or the hash of a commit.
• none: the value is ignored.

Example

uses: golangci/golangci-lint-action@v9
with:
  version: v2.13
  # ...

version-file

Gets the version of golangci-lint to use from a file.

The path must be relative to the root of the project, or the working-directory if defined.

This parameter supports .golangci-lint-version, and .tool-versions files.

Only works with install-mode: binary (the default).

Example

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

install-mode

(optional)

The mode to install golangci-lint: it can be binary, goinstall, or none.

The default value is binary.

goinstall is not recommended, more explanations here.

Example

uses: golangci/golangci-lint-action@v9
with:
  install-mode: "none"
  # ...

install-only

(optional)

If set to true, the action will only install golangci-lint. It does not run golangci-lint.

The default value is false.

Example

uses: golangci/golangci-lint-action@v9
with:
  install-only: true
  # ...

Run

verify

(optional)

This option is true by default.

If the GitHub Action detects a configuration file, validation will be performed unless this option is set to false. If there is no configuration file, validation is skipped.

The JSON Schema used to validate the configuration depends on the version of golangci-lint you are using.

Example

uses: golangci/golangci-lint-action@v9
with:
  verify: false
  # ...

github-token

(optional)

When using the only-new-issues option, the GitHub API is used, so a token is required.

By default, it uses the github.token from the action.

Example

uses: golangci/golangci-lint-action@v9
with:
  github-token: xxx
  # ...

only-new-issues

(optional)

Show only new issues.

The default value is false.

• pull_request and pull_request_target: the action gets the diff of the PR content from the GitHub API and uses it with --new-from-patch.
• push: the action gets the diff of the push content (the difference between commits before and after the push) from the GitHub API and uses it with --new-from-patch.
• merge_group: the action gets the diff by using the --new-from-rev option (relies on git). You should add the option fetch-depth: 0 to the actions/checkout step.

Example

uses: golangci/golangci-lint-action@v9
with:
  only-new-issues: true
  # ...

working-directory

(optional)

The golangci-lint working directory, useful for monorepos. The default is the project root.

Example

uses: golangci/golangci-lint-action@v9
with:
  working-directory: somedir
  # ...

args

(optional)

golangci-lint command line arguments.

[!NOTE] By default, the .golangci.yml file should be at the root of the repository. The location of the configuration file can be changed by using --config=.

[!IMPORTANT] Adding a = between the flag name and its value is important because the action parses the arguments on spaces.

Example

uses: golangci/golangci-lint-action@v9
with:
  # In some rare cases,
  # you may need to use `${{ github.workspace }}` as the base directory to reference your configuration file.
  args: --config=/my/path/.golangci.yml --issues-exit-code=0
  # ...

Cache

skip-cache

(optional)

If set to true, all caching functionality will be completely disabled. This takes precedence over all other caching options.

The default value is false.

Example

uses: golangci/golangci-lint-action@v9
with:
  skip-cache: true
  # ...

skip-save-cache

(optional)

If set to true, caches will not be saved, but they may still be restored, requiring skip-cache: false.

The default value is false.

Example

uses: golangci/golangci-lint-action@v9
with:
  skip-save-cache: true
  # ...

cache-invalidation-interval

(optional)

Periodically invalidate a cache every cache-invalidation-interval days to ensure that outdated data is removed and fresh data is loaded.

The default value is 7.

If the number is <= 0, the cache will always be invalidated (not recommended).

Example

uses: golangci/golangci-lint-action@v9
with:
  cache-invalidation-interval: 15
  # ...

Extra

problem-matchers

(optional)

Forces the usage of the embedded problem matchers.

By default, the problem matcher of Go (actions/setup-go) already handles the default golangci-lint output (text).

Works only with the text format (the golangci-lint default).

https://golangci-lint.run/usage/configuration/#output-configuration

The default value is false.

Example

uses: golangci/golangci-lint-action@v9
with:
  problem-matchers: true
  # ...

Experimental

The following options are experimental: those may or may not be supported in the future, and so they will be either converted into a dedicated option or removed.

List of comma-separated options.

Example

uses: golangci/golangci-lint-action@v9
with:
  experimental: "foo,bar"

automatic-module-directories

(optional)

This option will run golangci-lint in each module directory, useful for monorepos.

The automatic detection of modules uses the working-directory as the base directory if defined, otherwise the root directory.

[!IMPORTANT]

• The cache key