ADR-0001: golangci-lint as Go quality gate
Status
AcceptedTags
go, linting, ci, code-quality, static-analysisDecision
Use golangci-lint for all Go backend static analysis. It gates twice: a pre-commit hook blocks commits that leave issues in touchedbackend/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 officialgolangci/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, neveros.Setenv+defer os.Unsetenv - Deprecated functions must have a blank line before
Deprecated:in the godoc comment - Collapse
else { if cond {} }toelse if cond {}— gocriticelseifrule - Rewrite long
if / else if / else ifchains asswitch— gocriticifElseChainrule
Bad pattern (do not generate)
Good pattern
CI setup
- Job:
lint-goinbackend-flyio-deploy.yml - Blocking:
deploy-go-backendhasneeds: [detect-changes, lint-go] - Uses
golangci/golangci-lint-action@v7pinned tov2.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 in22c4c36d. The gate became blocking in the same change that added the pre-commit hook.