ADR-0001: golangci-lint as Go quality gate

Status

Accepted

Tags

go, linting, ci, code-quality, static-analysis

Decision

Use golangci-lint for all Go backend static analysis. It gates twice: a pre-commit hook blocks commits that leave issues in touched backend/go files, and the CI deploy job waits on the lint job, so a failing lint blocks the deploy.

Why

The Go backend had no automated quality gate. Issues like unchecked errors, deprecated API usage, dead code, and style inconsistencies accumulated silently. golangci-lint runs multiple linters in a single pass with low overhead and integrates directly into GitHub Actions via the official golangci/golangci-lint-action. A non-blocking CI job was chosen first to establish a clean baseline without halting existing deploys.

Enabled linters

errcheck is excluded on _test.go files to avoid noise from test assertions.

Rules for agents

  • Never use defer x.Close() without //nolint:errcheck — defer cannot capture the return value
  • Use _ = fn() for fire-and-forget calls where the error is intentionally ignored (event publish, cache write)
  • Use _, _ = fmt.Sscanf(...) and _, _ = fmt.Fprintf(...) — both return (int, error)
  • Use t.Setenv(key, val) in tests, never os.Setenv + defer os.Unsetenv
  • Deprecated functions must have a blank line before Deprecated: in the godoc comment
  • Collapse else { if cond {} } to else if cond {} — gocritic elseif rule
  • Rewrite long if / else if / else if chains as switch — gocritic ifElseChain rule

Bad pattern (do not generate)

Good pattern

CI setup

  • Job: lint-go in backend-flyio-deploy.yml
  • Blocking: deploy-go-backend has needs: [detect-changes, lint-go]
  • Uses golangci/golangci-lint-action@v7 pinned to v2.12.2
  • Config: backend/go/.golangci.yml

Local gate

scripts/hooks/pre-commit (wired through core.hooksPath) runs golangci-lint run --new-from-rev=HEAD --whole-files in backend/go when staged files include Go under backend/go. Any issue in a touched file fails the commit; golangci-lint fmt fixes the formatting ones. It lints the working tree, not only the staged snapshot. A missing golangci-lint binary prints a warning and lets the commit through. Bypass once with git commit --no-verify.

History

The job started non-blocking to build a clean baseline. It never became blocking, and with no local check the baseline drifted to 70 issues (49 of them gofumpt formatting) before they were cleared in 22c4c36d. The gate became blocking in the same change that added the pre-commit hook.