golangci-lint Integration

About 598 wordsAbout 2 min

2025-01-16

golint-sl integrates with golangci-lint as a module plugin (golangci-lint v2). This provides unified configuration, nolint directives, and issue exclusion through golangci-lint's config.

Building a Custom Binary

Create a .custom-gcl.yml file in your project root:

version: v2.8.0

plugins:
  - module: 'github.com/spechtlabs/golint-sl'
    version: v0.1.0  # Use the latest version

Build the custom binary:

golangci-lint custom

This creates a ./custom-gcl binary with golint-sl included.

Configure golangci-lint to enable the plugin in .golangci.yml:

version: "2"

linters:
  enable:
    - golint-sl

  settings:
    custom:
      golint-sl:
        type: module
        description: SpechtLabs Go linter collection
        original-url: github.com/spechtlabs/golint-sl
        settings:
          # Optional: disable specific analyzers
          disabled-analyzers:
            - todotracker      # If you don't want TODO tracking
            - reconciler       # If not a Kubernetes project
            - statusupdate
            - sideeffects

Run the linter:

./custom-gcl run ./...

Verifying the Plugin

To verify golint-sl is loaded:

./custom-gcl linters | grep golint-sl

GitHub Actions

name: Lint

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
          cache: true

      - name: Install golangci-lint
        run: |
          curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.8.0

      - name: Build custom golangci-lint with golint-sl
        run: golangci-lint custom

      - name: Run linter
        run: ./custom-gcl run ./...

Caching the Custom Binary

For faster CI runs, you can cache the custom binary:

- name: Cache custom golangci-lint
  uses: actions/cache@v4
  id: cache-custom-gcl
  with:
    path: ./custom-gcl
    key: custom-gcl-${{ hashFiles('.custom-gcl.yml', 'go.sum') }}

- name: Build custom golangci-lint
  if: steps.cache-custom-gcl.outputs.cache-hit != 'true'
  run: golangci-lint custom

Why Both golangci-lint and golint-sl?

golangci-lint and golint-sl serve complementary purposes:

Tool	Focus
golangci-lint	Broad coverage: style, complexity, bugs, security
golint-sl	Production patterns: observability, Kubernetes, safety

By running golint-sl as a golangci-lint plugin, you get both in a single tool invocation.

Avoiding Overlap

Some golangci-lint linters overlap with golint-sl analyzers:

golangci-lint	golint-sl	Recommendation
`nilerr`	`nilcheck`	Use golint-sl (more comprehensive)
`bodyclose`	`resourceclose`	Use golint-sl (catches more)
`contextcheck`	`contextpropagation`	Use golint-sl (production-focused)

Disable overlapping golangci-lint linters in your config:

# .golangci.yml
linters:
  disable:
    - nilerr       # Using golint-sl's nilcheck
    - bodyclose    # Using golint-sl's resourceclose
    - contextcheck # Using golint-sl's contextpropagation

Using nolint Directives

Use standard nolint directives to suppress warnings:

//nolint:golint-sl
func ignoredFunction() {
    // All golint-sl checks are suppressed for this function
}

// Suppress specific analyzer by name
//nolint:nilcheck
func nilNotChecked(ptr *string) {
    fmt.Println(*ptr) // nilcheck won't report this
}

Available Analyzers

golint-sl includes 30 analyzers across these categories:

Category	Analyzers
Error Handling	`humaneerror`, `errorwrap`, `sentinelerrors`
Observability	`wideevents`, `contextlogger`, `contextpropagation`
Kubernetes	`reconciler`, `statusupdate`, `sideeffects`
Testability	`clockinterface`, `interfaceconsistency`, `mockverify`, `optionspattern`
Resources	`resourceclose`, `httpclient`
Safety	`goroutineleak`, `nilcheck`, `nopanic`, `nestingdepth`, `syncaccess`
Clean Code	`closurecomplexity`, `emptyinterface`, `returninterface`
Architecture	`contextfirst`, `pkgnaming`, `functionsize`, `exporteddoc`, `todotracker`, `hardcodedcreds`, `lifecycle`, `dataflow`

Disabling Specific Analyzers

Disable analyzers via the plugin settings in .golangci.yml:

# .golangci.yml
linters:
  settings:
    custom:
      golint-sl:
        type: module
        settings:
          disabled-analyzers:
            - todotracker
            - reconciler
            - statusupdate
            - sideeffects

Makefile Integration

.PHONY: lint
lint: custom-gcl
    ./custom-gcl run ./...

custom-gcl:
    golangci-lint custom

Pre-commit with golangci-lint Plugin

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/SpechtLabs/golint-sl
    rev: v0.1.0
    hooks:
      - id: golint-sl      # Full analysis on ./...
      - id: golint-sl-pkg  # Fast mode for pre-commit

Next Steps

Configure Analyzers - Customize golint-sl
GitHub Actions - CI integration