Static linter for Kamal config/deploy.yml. Catches missing secrets, role/registry mismatches, and proxy footguns that Kamal silently allows.

# Gemfile
group :development, :test do
  gem "kamal-lint", require: false
end

bundle exec kamal-lint

Default: lint base + every destination override at once.

bundle exec kamal-lint

Auto-discovers config/deploy.*.yml files next to your base config/deploy.yml and lints each (base alone, then each destination merged onto base). Output groups findings by destination — bugs that live in a deploy.production.yml override show up only under [production]:

[base]       config/deploy.yml
  ✓ No issues found.

[production] config/deploy.production.yml
  ⚠ warning  ...
      `traefik:` block is Kamal 1.x legacy ...

[staging]    config/deploy.staging.yml
  ✓ No issues found.

Summary: 1 warning across 3 configs

Exits 1 if any findings are at or above --fail-on (default: warning), 0 otherwise.

Narrow to a single destination:

bundle exec kamal-lint -d production

Useful in CI matrix jobs or when debugging one destination. Skips auto-discovery; only lints deploy.yml + deploy.production.yml.

Other knobs:

bundle exec kamal-lint -c infra/deploy.yml      # non-default config path
bundle exec kamal-lint list-checks              # show every registered check
bundle exec kamal-lint --format=json            # machine-readable output
bundle exec kamal-lint --include-kamal-errors   # also surface Kamal's loader errors

In CI:

- uses: davafons/kamal-lint@v0.1.0
  with:
    fail-on: warning

--format=github is set automatically so findings show as inline annotations in the PR view. By default the action lints all destinations; set destination: production to narrow.

Reasoning behind each finding is also in the message text — paste a finding into search and you'll usually land on the relevant Kamal doc.

-c, --config-file PATH      config/deploy.yml
-d, --destination NAME      lint deploy.<name>.yml merged onto base
-f, --format FORMAT         human | json | github
    --fail-on LEVEL         error | warning | info
    --kamal-version VER     override detected Kamal version
    --include-kamal-errors  also surface Kamal's loader errors

Exit codes: 0 clean · 1 findings at/above --fail-on · 2 config missing.

kamal-lint reuses your installed Kamal's loader, so it auto-tracks whatever's in your Gemfile.lock. Older 2.x versions likely work but aren't covered by CI — if you hit a bug on an older Kamal, please open an issue. Override the detected version with --kamal-version 2.5.0 for matrix runs.

bin/setup     # install
bin/test      # run tests
bin/console   # IRB with kamal-lint loaded

Contributions: CONTRIBUTING.md · Security: SECURITY.md · License: MIT.