If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/golangci/golangci-lint shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 8 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live golangci/golangci-lint repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/golangci/golangci-lint.

What it runs against: a local clone of golangci/golangci-lint — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in golangci/golangci-lint | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of golangci/golangci-lint. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/golangci/golangci-lint.git
#   cd golangci-lint
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of golangci/golangci-lint and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "golangci/golangci-lint(\\.git)?\\b" \\
  && ok "origin remote is golangci/golangci-lint" \\
  || miss "origin remote is not golangci/golangci-lint (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "cmd/golangci-lint/main.go" \\
  && ok "cmd/golangci-lint/main.go" \\
  || miss "missing critical file: cmd/golangci-lint/main.go"
test -f ".golangci.yml" \\
  && ok ".golangci.yml" \\
  || miss "missing critical file: .golangci.yml"
test -f ".github/workflows/pr-tests.yml" \\
  && ok ".github/workflows/pr-tests.yml" \\
  || miss "missing critical file: .github/workflows/pr-tests.yml"
test -f "docs/content/docs/linters/_index.md" \\
  && ok "docs/content/docs/linters/_index.md" \\
  || miss "missing critical file: docs/content/docs/linters/_index.md"
test -f ".goreleaser.yml" \\
  && ok ".goreleaser.yml" \\
  || miss "missing critical file: .goreleaser.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/golangci/golangci-lint"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

golangci-lint is a fast, parallel-execution linters runner for Go that aggregates 100+ linters (like golint, errcheck, gosimple, gofmt) into a single tool with caching, YAML config support, and IDE integration. It solves the friction of running multiple separate linting tools by executing them concurrently and deduplicating results. Monolithic binary structure: cmd/golangci-lint/main.go is the CLI entry point with plugin loader (plugins.go); the tool reads .golangci.yml/.golangci.next.yml config files and orchestrates linter runners via internal packages. Linter implementations are abstracted behind Go interfaces, allowing swappable linter backends and plugin registration.

Go developers and CI/CD teams who want to enforce code quality standards without the overhead of configuring and running 10+ individual linter tools separately. DevOps engineers integrating linting into GitHub Actions, GitLab CI, and other CI platforms.

Highly mature and production-ready. The project has 14k+ GitHub stars, multiple release channels (.golangci.reference.yml and .golangci.next.reference.yml suggest versioned config schemas), comprehensive CI setup (pr-checks.yml, pr-tests.yml, release.yml workflows), Docker distribution, and active maintenance evidenced by documented incident response (.github/INCIDENT_RESPONSE_PLAN.md) and post-release workflows.

Low risk overall. The codebase is 1.1M+ lines of Go with minimal external runtime dependencies (primarily linter integrations, not runtime libs). Risks are manageable: linter version compatibility (each linter has its own release cycle), potential breaking changes across major versions (CHANGELOG-v1.md exists, suggesting v2 may exist), and dependabot integration shows active dependency management.

Active development with version stratification: reference configs for stable (.golangci.reference.yml) and next versions (.golangci.next.reference.yml) suggest ongoing iteration. GitHub workflows for documentation deployment (deploy-documentation.yml), new linter vetting (new-linter-checklist.yml), and post-release automation indicate a mature release process. The presence of new-linter-proposals.yml suggests the community actively proposes new linters.

Clone the repo, install Go 1.24.0 or later (from go.mod), and use the Makefile:

git clone https://github.com/golangci/golangci-lint.git
cd golangci-lint
make build
./golangci-lint run ./...

Daily commands: Build and run via Makefile: make build compiles cmd/golangci-lint/main.go to the binary. Execute on a codebase with ./golangci-lint run ./... (scans current package tree). Use .golangci.yml in repo root to customize enabled linters and rules.

• cmd/golangci-lint/main.go — Entry point of the golangci-lint application—all CLI invocations start here
• .golangci.yml — Default configuration file that defines linter rules and behavior for the project itself
• .github/workflows/pr-tests.yml — CI/CD pipeline that validates all pull requests—defines test matrix and coverage gates
• docs/content/docs/linters/_index.md — Central documentation hub for linters—critical for understanding supported linters and their configuration
• .goreleaser.yml — Build and release automation configuration—controls binary generation and distribution across platforms
• Makefile — Build system entry point—defines common development tasks, testing, and artifact generation
• .github/CONTRIBUTING.md — Contribution guidelines—essential for understanding the development workflow and code standards

• CLI Entry Point (main.go) (Go, standard library) — Parse command-line flags, initialize configuration, orchestrate the linting pipeline, and format output
  • Failure mode: Invalid flags or missing config files crash the application; affects all users
• Configuration Loader (YAML parsing, Go) — Parse YAML configuration files, validate linter settings, and merge CLI overrides with file config
  • Failure mode: Malformed config silently disables linters or uses defaults; could hide user intent
• Linters Engine (Go goroutines, channels, sync primitives) — Orchestrate parallel execution of individual linters, manage goroutine pools, and aggregate results
  • Failure mode: Goroutine leaks or deadlocks cause hangs; race conditions in result collection lose issues
• Cache Layer (File system or in-memory storage, hashing) — Store and retrieve linter results by file hash; manage TTL and cache invalidation
  • Failure mode: Stale cache returns outdated results; incorrect hash logic caches wrong data
• Documentation Site (Hugo, markdown, GitHub Pages) — Serve user-facing docs for installation, configuration, linter reference, and contribution guides
  • Failure mode: Outdated docs mislead users; broken links break user workflow
• CI/CD Pipelines (GitHub Actions, GoReleaser, Go testing) — Validate pull requests, run test suites, scan for security issues, and automate releases
  • Failure mode: Broken CI blocks legitimate PRs; failed security scans delay releases

• User shell → main.go — CLI command with flags and target files/directories
• main.go → Config Loader — Request to load and parse .golangci.yml
• Config Loader → Linters Engine — undefined

Add a New Linter Integration

1. Review the new linter checklist to understand requirements (.github/new-linter-checklist.md)
2. Add linter configuration to the reference configuration file (.golangci.reference.yml)
3. Document the linter in the linters configuration docs (docs/content/docs/linters/configuration.md)
4. Add linter entry to the linters index (docs/content/docs/linters/_index.md)

Update Documentation for a Feature

1. Update the appropriate docs section (linters, formatters, configuration, etc.) (docs/content/docs/configuration/_index.md)
2. Update the CLI help documentation data file (docs/data/cli_help.json)
3. Rebuild Hugo site documentation with your changes (docs/hugo.yaml)

Extend Configuration Support

1. Update the main configuration reference file (.golangci.reference.yml)
2. Document the new configuration option (docs/content/docs/configuration/file.md)
3. Add schema or type validation in the configuration module (cmd/golangci-lint/main.go)

Add a New Release Artifact or Platform

1. Update the GoReleaser configuration to add new build target (.goreleaser.yml)
2. Update Makefile if new build steps are needed (Makefile)
3. Update release workflow if additional validation or publishing steps are needed (.github/workflows/release.yml)

• Go — Native language for linting Go code; compiled binaries ensure fast startup and minimal dependencies
• YAML Configuration — Human-readable config format familiar to DevOps; supports complex nested linter rule definitions
• Hugo Static Site Generator — Fast documentation site generation; integrates with GitHub Pages; supports markdown content structure
• GitHub Actions — Native CI/CD for GitHub repos; enables automated testing, linting validation, and release automation
• GoReleaser — Simplifies multi-platform binary builds and release automation; integrates with GitHub releases

• Parallel linter execution

  • Why: Performance is critical for developer experience; slow linters block the build
  • Consequence: Increased complexity in process orchestration; potential race conditions if linters share state

• Caching layer for results

  • Why: Most development runs lint the same files; caching avoids redundant work
  • Consequence: Cache invalidation logic must be robust; stale results could hide real issues

• Monolithic binary distribution

  • Why: Users want a single executable without dependency installation
  • Consequence: Binary size increases; all linters bundled even if unused; larger disk footprint

• Plugin architecture for extensibility

  • Why: Allows third-party linters without modifying core binary
  • Consequence: More complex initialization logic; plugin compatibility matrix to maintain

• Does not format/fix code automatically (linting-only, not auto-fixing)

Config file precedence: .golangci.yml is loaded from repo root; .golangci.next.reference.yml signals breaking changes in the next major version, so contributor PRs should test against both stable and next configs. Plugin loading (plugins.go) requires plugins to be built and discoverable in PATH or vendor directory—this is non-obvious for first-time contributors adding linter integrations. Go version pinning in go.mod is strict (1.24.0)—build may fail silently on older Go versions without clear error messaging.

• Linter aggregation and deduplication — golangci-lint's core value is running 100+ independent linters in parallel and merging duplicate findings—understanding this orchestration pattern is essential to modifying the linter selection or output logic
• Go AST (Abstract Syntax Tree) analysis — All bundled linters analyze Go code via the ast package to detect patterns; contributors adding linter integrations must understand how Go's loader package and ast.Inspector work
• Static analysis via type checking — golangci-lint linters like golint, errcheck, and staticcheck use Go's type checker to infer types and detect logical errors—critical for understanding why some linter configurations require full dependency resolution
• Plugin architecture and dynamic loading — plugins.go hints at a plugin system for custom linters; understanding Go's plugin package and how golangci-lint discovers linters at runtime is key to extending the tool
• Goroutine-based parallelization — The README explicitly states linters run in parallel for speed; the implementation likely uses goroutine pools and channels to manage concurrent linter execution and result aggregation
• YAML-based configuration schema — golangci-lint uses YAML config (.golangci.yml) with versioned reference files (.golangci.reference.yml); understanding how config is marshaled/unmarshaled and validated is crucial for adding new config options
• Configuration versioning and breaking changes — The presence of both .golangci.reference.yml and .golangci.next.reference.yml signals a mature versioning strategy for config schemas—contributors must understand how breaking changes are communicated and tested across versions

• golang/lint — Official Go linter (golint) that golangci-lint wraps and executes alongside other linters
• golangci/awesome-go-linters — Companion repository curating the universe of Go linters and their maturity levels—directly informs which linters golangci-lint should integrate
• uber-go/goleak — Goroutine leak detector linter commonly used with golangci-lint for detecting resource leaks in concurrent Go programs
• dominikh/go-tools — Source of the staticcheck and honnef linters (gosimple, unused) that are core linters bundled and executed by golangci-lint
• mgechev/revive — Fast linter written in Go that serves as an alternative to golint; golangci-lint often runs both for comprehensive style coverage

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive linter integration tests for newly added linters

The repo has a new-linter-checklist.yml workflow and new-linter-proposals discussion template, but there's no visible integration test suite verifying that newly enabled linters work correctly end-to-end. This is critical for a linters runner where false positives or integration bugs directly impact users. Adding tests that validate each linter's output format, error handling, and configuration parsing would catch regressions early.

• [ ] Create test/linters/ directory with integration test files for each major linter category
• [ ] Add test fixtures in test/testdata/ with intentional code violations for each linter
• [ ] Create a test suite that validates linter output format matches expected JSON/text structure
• [ ] Integrate tests into .github/workflows/pr-tests.yml to run on all linter-related PRs
• [ ] Reference the new-linter-checklist.md to include test requirements for future linters

Document and implement config schema validation tests in docs/content/docs/configuration/

The repo has .golangci.reference.yml, .golangci.next.reference.yml, and .custom-gcl.reference.yml configuration files but lacks visible validation tests or schema documentation. Users frequently misconfigure linters (evident from issue patterns). Creating a test suite that validates YAML configuration against a JSON schema and documenting common configuration errors would reduce support burden.

• [ ] Create docs/content/docs/configuration/schema-validation.md documenting the config file schema
• [ ] Add test/config/ directory with unit tests validating .golangci.yml parsing and schema compliance
• [ ] Generate and document a JSON schema from the code (reference .golangci.reference.yml structure)
• [ ] Add examples of invalid configurations with explanatory error messages in test fixtures
• [ ] Create PR validation workflow step that validates all reference .yml files against the schema

Create GitHub Actions documentation and examples for common CI/CD platforms

The assets/github-action-config-*.json files suggest GitHub Actions integration exists, and docs mention CI/CD installation, but there's no visible workflow examples in .github/workflows/ for popular CI systems (GitHub Actions, GitLab CI, CircleCI, etc.). New contributors often struggle with CI integration. Creating reusable workflow templates and documentation would improve adoption.

• [ ] Create .github/workflows/example-github-actions.yml as a documented template for basic usage
• [ ] Add docs/content/docs/welcome/install/ci-examples.md with platform-specific configuration examples
• [ ] Create example workflow files showing caching, matrix testing, and reporting (reference dependabot.yml structure)
• [ ] Document the github-action-config-*.json assets and how they're used in the GitHub Action
• [ ] Add version pinning and security best practices examples to the CI documentation

• Add integration tests for the config loading logic (.golangci.yml parsing) by examining cmd/golangci-lint/main.go; currently no visible test files in the top-level structure suggest test coverage gaps here.
• Document the plugin system by adding usage examples to docs/content—plugins.go exists but docs/content lacks a 'Writing Custom Linters' guide, a common contributor request.
• Migrate linters from .golangci.reference.yml to .golangci.next.reference.yml for a specific major linter (e.g., golint → golangci-lint deprecation); this is mechanical, high-visibility work that teaches config management.

The golangci-lint codebase demonstrates reasonable security practices with a well-organized structure and documented contribution guidelines. No critical vulnerabilities were identified in the static analysis. The primary concerns are around plugin system security (which should be validated through code review), transitive dependency management, and Go version specification. The project appears to follow standard Go practices with CI/CD workflows (CodeQL, dependabot), security incident response planning, and contribution guidelines visible. Recommend conducting code review of the plugin loading mechanism and ensuring all transitive dependencies are regularly audited.

• Medium · Indirect Dependency without Direct Version Control — go.mod - github.com/imfing/hextra v0.12.1. The module github.com/imfing/hextra is marked as indirect (// indirect comment) in go.mod. This indicates it's a transitive dependency not directly managed by this project. While this is normal for indirect dependencies, lack of explicit version pinning in the documentation could lead to unexpected updates. Fix: Review the direct dependencies that pull in hextra. Consider using 'go mod why' to understand the dependency chain and ensure transitive dependencies are vetted. Regularly update and audit dependencies using 'go mod tidy' and 'go mod verify'.
• Low · Potential Plugin Security Risk — cmd/golangci-lint/plugins.go. The presence of 'cmd/golangci-lint/plugins.go' suggests the tool supports plugin functionality. Plugin systems can introduce security risks if plugins are loaded from untrusted sources or lack proper sandboxing. Fix: Ensure plugin loading mechanisms validate plugin signatures, restrict plugin sources to trusted repositories, implement sandboxing, and document plugin security requirements. Review CONTRIBUTING.md and new-linter-checklist.md for plugin vetting procedures.
• Low · Go Version Not Fully Specified — go.mod - go 1.24.0. The go.mod specifies 'go 1.24.0', which is a future/unreleased version. This could indicate development against an unstable Go version or a documentation/configuration error. Fix: Verify that Go 1.24.0 is the intended target version. For production builds, use a stable, released Go version. Update CI/CD pipelines to use consistent, tested Go versions.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.