fleetlint Policy for a fleet of repositories
v0.11 (latest)
Getting started

Rule catalog

The rules the fleetlint:* presets ship, grouped by family, with a one-line summary of what each checks. The rule reference has a page per rule, generated from the catalog, with the exact requirement, parameters and fix. The practices behind the rules are in the baseline and, per stack, in the stack profiles.

Reading the tables

Preset names the smallest preset that selects the rule:

  • minimal: the floor for any repository. Nothing secret, accidental or oversized is tracked, no conflict markers are committed, a public repository has a license, and hooks exist. The two hook rules apply at tiers 1 and 2, not to experiments.
  • recommended, the default: minimal plus the families below.
  • strict: recommended with every severity raised one step. The security rules take no exceptions and cannot be disabled.
  • oss: recommended with its public/* rules run whatever the detected visibility.
  • slop: an add-on with the heuristic slop/* rules and the two agent-trace rules for public repositories.

Severity is the default. A repository may raise it freely and lower it with a reason.

Tiers: all, or the tiers the rule applies to. What runs at each tier lists them per tier.

Kind says how the rule decides:

  • expr: a CEL predicate. A repository can except a finding, but cannot add ways to pass.
  • outcome: an outcome rule. It names a result and lists the known ways of reaching it, its satisfiers; the first that holds passes the rule and is reported as the evidence. A repository adds its own way with accept: (writing rules).
  • capability: one requirement that each stack meets with its own tools. lint/configured is implemented by lint/configured/go, lint/configured/python and so on, each an expr or outcome rule with its own page. Every implementation that runs must pass. Selecting, overriding or excepting the capability reaches every implementation, and accept: reaches its outcome implementations; an implementation id adjusts one stack. The capability matrix shows which stack implements which (writing rules).
  • capability by artifact: a capability implemented per kind of published artifact instead of per stack. Each image, package or set of release files is checked on its own (artifacts).
  • go: written in Go inside fleetlint. Only quality/check-passes, which runs the repository’s code.

repo: repository hygiene

RuleSeverityTiersPresetKindChecks
repo/no-tracked-junkerrorallminimalexprno OS, editor or backup files, bytecode or dependency directories tracked (.DS_Store, *.log, __pycache__/, node_modules/, …)
repo/no-tracked-enverrorallminimalexprno .env* with values tracked (.env.example allowed)
repo/no-large-fileswarningallminimalexprno tracked file over params.max_kb (default 2048) unless git-lfs takes its pattern
repo/gitignore-presentwarningallminimalexpra .gitignore at the root
repo/editorconfigwarningallrecommendedexpran .editorconfig exists
repo/gitattributeswarningallrecommendedexpr.gitattributes contains text=auto
repo/readme-presentwarningallrecommendedexpra README of at least 10 lines with a heading on installing, running or using the project
repo/lockfile-committederror1, 2recommendedcapabilitythe lockfile of each stack’s dependency manager is tracked
repo/toolchain-pinnedwarning1, 2recommendedcapabilityeach stack pins its compiler or runtime with a version (the stack’s version file, .tool-versions/mise.toml naming the tool, or devbox.json naming its package with a version); a JDK pin for Java and Kotlin
repo/dev-environmentwarning1, 2recommendedoutcomethe tools are reproducible: in a container mode the container; on the machine a Nix flake, devenv or devbox with its lock file (or shell.nix), mise.toml / .tool-versions, or a tools target with pinned versions
repo/codeownersinfo1recommendedexpra CODEOWNERS file at the root or in .github/, docs/ or .gitea/

taskrunner: the task-runner contract

RuleSeverityTiersPresetKindChecks
taskrunner/targetserror1, 2recommendedexprfmt lint test cover audit check check-fast exist and are not placeholders (Makefile, justfile, Taskfile or package.json scripts; not checked with Gradle, whose check is the convention)
taskrunner/containerwarning1, 2recommendedoutcomewhen facts.container is not none: a target called outside the container runs inside it (devcontainer CLI, docker, podman, or an accept:ed way); Makefile, justfile, Taskfile
taskrunner/check-compositionwarningallrecommendedexprcheck reaches lint and test (up to three levels deep) and neither bench nor release; Makefile, justfile, Taskfile

format, lint, types: static analysis per stack

The per-stack tools and settings are in the stack profiles.

RuleSeverityTiersPresetKindChecks
format/configuredwarning1, 2recommendedcapabilitya formatter is configured or runs (gofumpt, ruff format, rustfmt, Prettier or Biome, Spotless, dart format, dotnet format, clang-format, RuboCop, PHP CS Fixer, …); not applicable to Hugo
lint/configuredwarning1, 2recommendedcapabilitya linter is configured (golangci-lint v2, ruff, clippy [lints], ESLint/Biome/oxlint, detekt 2, Checkstyle/Error Prone/SpotBugs/PMD, .NET analyzers, clang-tidy, RuboCop, PHPStan/Psalm, a Dart lint set; for Hugo hugo --panicOnWarning)
lint/strictwarning1, 2recommendedcapabilitythe linter’s required checks are on, one finding per missing check (golangci-lint errcheck govet staticcheck errorlint gosec gocognit funlen; ruff E F I B UP SIM BLE S C90 T20; clippy unwrap_used expect_used panic todo dbg_macro; five detekt rules; .NET Nullable, warnings as errors, analysis level; clang-tidy WarningsAsErrors; Java analyzers that fail the build; RuboCop NewCops: enable)
types/strictwarning1, 2recommendedcapabilitythe type checker runs in strict mode (tsconfig strict flags; mypy or pyright strict; PHPStan max or Psalm level 1; the Dart analyzer’s three strict modes); not applicable where the compiler is the type checker
lint/shellinfoallrecommendedexprwhen shell scripts are tracked, shellcheck runs as a hook, in the task runner or in CI

quality: behaviour, not configuration

RuleSeverityTiersPresetKindChecks
quality/check-passeserror1, 2recommendedgowith --deep: the task runner’s check exits 0 within the budget
quality/policy-enforcedwarning1, 2recommendedexprfleetlint check runs as a hook, in the task runner or in CI
quality/coverage-thresholdwarning1, 2recommendedcapabilitytests fail below a coverage floor (the stack’s coverage tool with a minimum, diff-cover --fail-under, a codecov target)
quality/duplication-gateinfo1recommendedcapabilitya duplication detector runs: golangci-lint dupl, pylint duplicate-code, PMD CPD, or for every stack jscpd, Simian, duplo or Sonar
quality/mutation-gateinfo1recommendedcapabilitya mutation testing tool runs on the core: gremlins, mutmut, cargo-mutants, StrykerJS, Pitest, mutation_test, Stryker.NET, Mull, mutant, Infection

docs and changelog: the documents that must exist

RuleSeverityTiersPresetKindChecks
docs/architecturewarning1recommendedexprdocs/ARCHITECTURE.md, ARCHITECTURE.md or an Architecture section in the README
docs/adr-directoryinfo1recommendedexprat least one Markdown record in docs/adr/ (or docs/decisions/, doc/adr/, adr/, …)
changelog/presentwarning1, 2recommendedexprCHANGELOG.md with at least one ## section
changelog/generator-configuredinfo1recommendedoutcomea changelog generator is configured: git-cliff, GoReleaser, release-please, cocogitto, semantic-release, commitizen, changesets or towncrier

hooks: prek, pre-commit or lefthook

RuleSeverityTiersPresetKindChecks
hooks/config-presenterror1, 2minimalexpr.pre-commit-config.yaml or a lefthook configuration
hooks/secret-scanerror1, 2minimaloutcomea pre-commit hook runs a secret scanner (gitleaks, trufflehog, ggshield, detect-secrets, secretlint); detect-private-key alone is a partial result
hooks/shared-hygienewarning1, 2recommendedexpr.pre-commit-config.yaml runs the shared hygiene hooks (trailing whitespace, end of file, merge conflicts, large files); lefthook is not read
hooks/conventional-commitswarning1, 2recommendedoutcomea commit-msg hook checks every message
hooks/pre-push-checkwarning1, 2recommendedoutcomea pre-push hook runs the task runner’s check (check-fast does not count)
hooks/revs-pinnedwarning1, 2recommendedexprevery rev: in .pre-commit-config.yaml is a version tag or a commit SHA, never a branch

deps: dependency hygiene

RuleSeverityTiersPresetKindChecks
deps/locked-installwarning1, 2recommendedcapabilityinstalls use the lockfile strictly (npm ci, uv sync --locked, cargo --locked, composer install, Bundler frozen, …) and nothing rewrites it outside an update target
deps/vulnerability-scanwarning1, 2recommendedcapabilitythe task runner or CI runs a vulnerability scanner (the stack’s tool, or osv-scanner, trivy, grype and the like for every stack)
deps/license-checkinfo1recommendedcapabilitythe task runner or CI checks dependency licenses against an allowlist
deps/unused-checkinfo1recommendedcapabilityunused dependencies are detected (go mod tidy -diff, deptry, cargo-machete, knip, composer-unused, dependency_validator, …)
deps/update-automationwarning1, 2recommendedexprRenovate or Dependabot is configured
deps/update-coverageinfo1, 2recommendedexprthe update automation covers every detected stack, GitHub Actions and Dockerfiles
deps/update-cooldowninfo1, 2recommendedexprupdates wait a few days after a release: Renovate minimumReleaseAge, Dependabot cooldown
deps/install-scripts-disabledinfo1, 2recommendedexprNode: install scripts are off or allowlisted (.npmrc, .yarnrc.yml, pnpm onlyBuiltDependencies, bun trustedDependencies)
deps/forks-documentedinfo1, 2recommendedcapabilitya dependency taken from a fork (go.mod replace, git sources in Cargo.toml, package.json, Python requirements or the Gemfile, a VCS repository in composer.json) is documented in FORKS.md, a Forks section, or a comment on its line

containers: repositories with a Dockerfile

RuleSeverityTiersPresetKindChecks
containers/dockerignorewarningallrecommendedexpra .dockerignore exists
containers/non-root-userwarningallrecommendedexprevery Dockerfile sets a non-root USER or builds on a non-root base (:nonroot, Chainguard); one finding per file
containers/base-image-pinnedinfo1recommendedexprevery FROM carries @sha256:; scratch, build arguments and earlier stages exempt

ci: the check workflow and its safety

The CI rules read GitHub, Gitea and Forgejo Actions workflows and .gitlab-ci.yml with its local includes. A rule about something only one system has applies to that system only; the rule’s page says which.

RuleSeverityTiersPresetKindChecks
ci/check-workflowwarning1, 2recommendedoutcomea workflow or pipeline on push or pull/merge request runs the task runner’s check (check-fast does not count)
ci/actions-pinnedwarning1recommendedexprevery uses: is pinned to a commit SHA, docker:// images by digest; GitLab includes and components to a commit SHA, remote includes by integrity:
ci/least-privilegewarning1, 2recommendedexprGitHub Actions only: top-level or per-job permissions: present and not write-all
ci/no-script-injectionwarning1, 2recommendedexprActions: no ${{ }} over outsider-controlled event data inside a run: or github-script script:
ci/no-pipe-to-shellwarning1, 2recommendedexprno download piped into a shell in CI scripts or Dockerfiles
ci/no-pull-request-targeterrorallrecommendedexprno pull_request_target workflow checks out or fetches the PR’s code (GitHub, Gitea, Forgejo)
ci/checkout-no-persist-credentialsinfo1recommendedexprActions: every actions/checkout sets persist-credentials: false
ci/workflow-lintinfo1recommendedoutcomeActions workflows are linted with actionlint or zizmor
ci/sastinfo1recommendedcapabilitya SAST tool runs: CodeQL, Semgrep or Opengrep, GitLab SAST, SonarQube; for Ruby also Brakeman, for PHP Psalm’s taint analysis
ci/job-timeoutsinfoallrecommendedexprevery job sets a timeout (timeout-minutes; GitLab timeout:); one finding per job
ci/concurrency-cancelinfoallrecommendedexprpull-request pipelines cancel superseded runs (concurrency with cancel-in-progress; GitLab interruptible)

release: producing artifacts

The release rules apply once a repository releases: a release mechanism, a tag-triggered pipeline, a published artifact or version tags. Each rule’s page says which.

RuleSeverityTiersPresetKindChecks
release/tag-triggerederror1recommendedexprreleases come from a tag-triggered pipeline (Actions push: tags:, GitLab $CI_COMMIT_TAG)
release/signingerror1recommendedcapability by artifactevery published artifact is signed: with its ecosystem’s signature where there is one (APK signing, PGP for Maven Central, npm provenance, PyPI attestations, NuGet signing), otherwise with cosign or gpg
release/sbomwarning1recommendedcapability by artifactan SPDX or CycloneDX SBOM is generated in the release pipeline for each artifact that carries its own dependencies; packages a registry resolves from a manifest (npm, PyPI, crates.io, RubyGems, pub.dev) are not checked
release/provenancewarning1recommendedcapability by artifactbuild provenance is attested: by the registry where it does that (npm, PyPI, RubyGems), otherwise attest-build-provenance, the SLSA generator, cosign attest, BuildKit or GitLab artifact metadata
release/checksumswarning1recommendedoutcomea checksums file is produced (GoReleaser default, sha256sum, shasum -a 256); not needed for what a registry addresses by digest
release/trusted-publishingwarning1recommendedcapability by artifactpublishing to npm, PyPI, crates.io, RubyGems, NuGet or pub.dev uses OIDC trusted publishing, not a registry token from secrets (GitHub and GitLab)
release/semver-tagswarningallrecommendedexprexisting tags match v?MAJOR.MINOR.PATCH[-pre]; one finding per offending tag
release/signed-tagswarning1recommendedexprthe newest params.recent (3) version tags carry a PGP, SSH or X.509 signature
release/changelog-in-releaseinfo1recommendedoutcomerelease notes come from git-cliff, GoReleaser, release-please, changesets or the generated CHANGELOG.md, not hand-written
release/hosted-builderinfo1recommendedexprjobs of a tag-triggered GitHub workflow run on GitHub-hosted runners
release/reproducible-buildinfo1recommendedcapability by artifactrelease builds are reproducible: the stack’s build settings (-trimpath, --remap-path-prefix, outputTimestamp, ContinuousIntegrationBuild) or SOURCE_DATE_EPOCH in the release build
release/api-compatibilityinfo1recommendedcapabilitylibraries: the stack’s API check runs against the previous release (gorelease or apidiff, griffe, cargo-semver-checks, API Extractor, binary-compatibility-validator, japicmp or revapi, .NET package validation, dart_apitool)

public: open-source repositories (when: repo.public)

RuleSeverityTiersPresetKindChecks
public/licenseerrorallminimalexpra license file at the root (LICENSE*, LICENCE*, COPYING*, UNLICENSE) or a REUSE LICENSES/ directory
public/security-policywarning1recommendedexprSECURITY.md at the root or in .github/, docs/ or .gitea/
public/contributinginfo1recommendedexprCONTRIBUTING.md at the root or in .github/, docs/ or .gitea/
public/code-of-conductinfo1recommendedexprCODE_OF_CONDUCT.md at the root or in .github/, docs/ or .gitea/
public/manifest-licenseinfo1recommendedcapabilitya published package’s manifest declares its license (package.json, pyproject.toml, Cargo.toml, the Maven POM, a gemspec, composer.json, PackageLicenseExpression, vcpkg.json, conanfile.py)
public/issue-templatesinfo1recommendedexpran issue or pull-request template in .github/ or .gitea/
public/no-agent-fileserrorallslopexprno agent instruction files tracked (CLAUDE.md, CLAUDE.local.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursorrules, .windsurfrules, .clinerules, .aider*, .claude/, .agent/, .cursor/)
public/no-ai-attributionerrorallslopexprthe last params.commits (default 200) commits carry no AI tool’s address as author or co-author and no generated-with footer; names are not read

slop: traces of careless or generated code

Catalog and rationale: slop.md. slop/conflict-markers is in fleetlint:minimal and three more are in fleetlint:recommended; the others are heuristics in the add-on preset fleetlint:slop.

RuleSeverityTiersPresetKindChecks
slop/conflict-markerserrorallminimalexprno merge conflict markers in source
slop/focused-testserrorallrecommendedexprno .only, fit, fdescribe, solo: true, RSpec focus: true
slop/scratch-scriptswarningallrecommendedexprno fix_*, debug-*, tmp_* scripts at the root
slop/report-documentswarningallrecommendedexprno *_SUMMARY.md, *REPORT*.md, NEXT_STEPS.md and the like
slop/narration-comments, slop/placeholder-comments, slop/banner-comments, slop/todo-without-issue, slop/commented-out-codeinfoallslopexprcomment hygiene
slop/emoji-in-code, slop/typographic-chars, slop/emoji-headingsinfoallslopexprno emoji or typographic characters in code and headings
slop/marketing-wordsinfoallslopexprno marketing filler in Markdown documentation
slop/debug-output, slop/arbitrary-delays, slop/swallowed-errors, slop/escape-hatches, slop/forced-unwraps, slop/vague-errors, slop/placeholder-valuesinfoallslopexprcode smells outside tests
slop/insecure-patternswarningallslopexprno disabled TLS verification, eval(, chmod 777, wildcard CORS
slop/variant-names, slop/variant-files, slop/dumping-ground-filesinfoallslopexprno V2/New/Old variants, no utils dumping grounds
slop/skipped-tests, slop/trivial-assertsinfoallslopexprtest hygiene
slop/vague-commit-messages, slop/non-conventional-commits, slop/huge-commitsinfoallslopexprhistory of the last params.commits commits

Totals

Count
rules106
of which capabilities22
of which keyed by artifact5
implementations per stack (and any)170
implementations per artifact kind65

Templates are not rules

The rules check outcomes, not the shape of the files fleetlint fix writes: a repository with its own hooks, workflows or release pipeline passes when it produces the same results. fleetlint’s own tests check the other direction: a repository set up from each stack’s templates passes the hook, CI and release rules.