# kube-linter: Configure Checks with .kube-linter.yaml

> A .kube-linter.yaml selects which checks run, sets exclusions, and defines custom checks. Reference for the config schema and CI errors.

Source: https://latchkey.dev/learn/command-reference/kube-linter-config  
Updated: 2026-06-30

A .kube-linter.yaml file under the checks and customChecks keys controls exactly which built-in checks run and lets you define new ones.

The default check set is opinionated. A config file makes the linting policy explicit and version-controlled, so it is identical in CI and on every developer machine.

## What it does

The config has a `checks` block (with `addAllBuiltIn`, `doNotAutoAddDefaults`, `include`, `exclude`) and a `customChecks` block for templated checks. kube-linter reads it via `--config`, or finds `.kube-linter.yaml` in the working directory.

## Common usage

```.kube-linter.yaml
# .kube-linter.yaml
checks:
  addAllBuiltIn: true
  exclude:
    - "default-service-account"
    - "no-anti-affinity"
customChecks:
  - name: require-team-label
    template: required-label
    params:
      key: team
```

## Options

| Key | What it does |
| --- | --- |
| checks.addAllBuiltIn | Start from every built-in check |
| checks.doNotAutoAddDefaults | Do not auto-enable the default set |
| checks.include / exclude | Turn specific checks on or off |
| customChecks | Define checks from a template + params |
| template | Built-in template a custom check derives from |

## In CI

Pin the config in the repo and pass `--config .kube-linter.yaml` so a new built-in check in a tool upgrade does not suddenly break every build. Roll new checks out as warnings first, then promote to failing once the codebase is clean.

## Common errors in CI

`unknown check "<name>"` in include/exclude is a name mismatch; the canonical list is `kube-linter checks list`. `error unmarshaling configuration: ... field <x> not found` means a typo or wrong indentation in the YAML. A custom check with `template: <unknown>` fails with `invalid template`; valid templates are listed by `kube-linter templates list`.

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### kube-linter: Configure Checks with .kube-linter.yaml?

The default check set is opinionated. A config file makes the linting policy explicit and version-controlled, so it is identical in CI and on every developer machine.

### What it does?

The config has a checks block (with addAllBuiltIn, doNotAutoAddDefaults, include, exclude) and a customChecks block for templated checks. kube-linter reads it via --config, or finds .kube-linter.yaml in the working directory.

### In CI?

Pin the config in the repo and pass --config .kube-linter.yaml so a new built-in check in a tool upgrade does not suddenly break every build. Roll new checks out as warnings first, then promote to failing once the codebase is clean.

### Common errors in CI?

unknown check "<name>" in include/exclude is a name mismatch; the canonical list is kube-linter checks list. error unmarshaling configuration: ... field <x> not found means a typo or wrong indentation in the YAML. A custom check with template: <unknown> fails with invalid template; valid templates are listed by kube-linter templates list.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt