kamal-lint 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fbb47a4aa7557a495d992e752262116d9b3617baa4918f8926be85fa3263f2c1
+  data.tar.gz: 5ae854761838ac0bb597aa7318126d94c6cbe40a3ae6ae7e1c28da47eedbe499
+SHA512:
+  metadata.gz: f4651938af9157e4a519a4a76b03f57b126821b1d0849d7d240a2f018e446898570b50b85f208dc0238bbfede41340ba8000ba995dbfc51e3fddf5bb4273dcfe
+  data.tar.gz: 74dd99df9454c440074df74d3110c025eafc0b7f7b6e6917d8964b65363ab8ad69aff2c5fda62b4789c1cf9536e6ceca28bc04069a7d6c7532191ae6d08024f1

data/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- `--include-kamal-errors` flag to opt-in to surfacing errors from Kamal's own loader (off by default; use `kamal config` for parse-time checks).
+
+### Fixed
+- `image-registry-mismatch` no longer false-positives when `registry.server` is set to Docker Hub (`docker.io`, `index.docker.io`, `registry.hub.docker.com`) and the image lacks an explicit registry prefix — Docker Hub resolves unprefixed images automatically.
+
+### Internal
+- Renamed `LICENSE` → `MIT-LICENSE` to match Kamal's convention.
+- Added `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `.ruby-version`, `bin/release`.
+- Added `Release` GitHub Actions workflow for tag-triggered publishing via RubyGems trusted publishing (OIDC).
+- Added `actionlint` and `zizmor` workflow security audits in CI.
+- Added `dependabot.yml` for weekly bundler + GitHub Actions updates.
+- Added PR template and issue templates (bug report, new check proposal).
+
+## [0.1.0] - 2026-05-11
+
+### Added
+- Initial release.
+- 16 checks across reference integrity, coherence, and smells:
+  - `secret-not-declared`
+  - `accessory-role-undefined`
+  - `proxy-host-not-in-role`
+  - `image-registry-mismatch`
+  - `builder-registry-secret-undeclared`
+  - `ssl-without-host`
+  - `empty-web-role`
+  - `traefik-legacy-keys` (autofixable)
+  - `boot-limit-exceeds-hosts`
+  - `accessory-host-undefined`
+  - `missing-service-name` (autofixable)
+  - `kamal-secrets-not-gitignored` (autofixable)
+  - `secret-in-env-clear`
+  - `missing-proxy-healthcheck`
+  - `accessory-image-latest`
+  - `registry-without-explicit-server`
+- Three output formatters: `human`, `json`, `github` (GitHub Actions annotations).
+- `--fix` for the safe autofix subset.
+- `-d/--destination` for linting destination override files.
+- Auto-detection of installed Kamal version with version-gated checks.
+- `kamal-lint` GitHub Action (composite) for one-line CI integration.
+
+[Unreleased]: https://github.com/davafons/kamal-lint/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/davafons/kamal-lint/releases/tag/v0.1.0

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Afonso
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,190 @@
+<h1 align="center">kamal-lint</h1>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/kamal-lint"><img src="https://img.shields.io/gem/v/kamal-lint" alt="Gem Version"></a>
+  <a href="https://github.com/davafons/kamal-lint/actions/workflows/ci.yml"><img src="https://github.com/davafons/kamal-lint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://github.com/davafons/kamal-lint/blob/main/MIT-LICENSE"><img src="https://img.shields.io/github/license/davafons/kamal-lint" alt="License"></a>
+  <a href="https://rubygems.org/gems/kamal-lint"><img src="https://img.shields.io/gem/dt/kamal-lint" alt="Downloads"></a>
+</p>
+
+Static linter for [Kamal](https://kamal-deploy.org) `config/deploy.yml`. Catches cross-section bugs and smells that Kamal itself silently allows — undeclared secrets, accessory/role mismatches, registry inconsistencies, and more — before a single SSH connection happens.
+
+```
+$ bundle exec kamal-lint
+kamal-lint 0.1.0 · kamal 2.11.0 detected
+  config:      config/deploy.yml
+
+✖ error   config/deploy.yml:9
+    env.secret references `RAILS_MASTER_KEY` but it isn't declared in .kamal/secrets
+    [secret-not-declared]
+
+⚠ warning config/deploy.yml:18 (autofixable)
+    `traefik:` block is Kamal 1.x legacy and is ignored in Kamal 2+; use `proxy:` instead
+    [traefik-legacy-keys]
+
+Summary: 1 error, 1 warning, 1 autofixable
+```
+
+## Why
+
+Kamal's own loader only checks "does this YAML parse into my schema?" It happily accepts a config that references secrets you never declared, points at registries you don't use, names roles that don't exist, or still uses Kamal 1.x `traefik:` keys. By the time you find out, you've already shipped a broken deploy.
+
+`kamal-lint` runs in CI (or pre-commit) and catches these before they hit production.
+
+## Install
+
+Add to your project's `Gemfile`:
+
+```ruby
+group :development, :test do
+  gem "kamal-lint", require: false
+end
+```
+
+Then:
+
+```bash
+bundle install
+bundle exec kamal-lint
+```
+
+Or install globally:
+
+```bash
+gem install kamal-lint
+kamal-lint
+```
+
+## Usage
+
+```
+bundle exec kamal-lint [OPTIONS]
+
+  -c, --config-file PATH    Path to deploy.yml (default: config/deploy.yml)
+  -d, --destination NAME    Lint with destination override applied
+                              (e.g. -d production → config/deploy.production.yml)
+  -f, --format FORMAT       human (default) | json | github
+      --fail-on LEVEL       error | warning (default) | info
+      --fix                 Apply safe autofixes in-place
+      --kamal-version VER   Override detected Kamal version
+      --include-kamal-errors  Also surface errors from Kamal's own loader
+                                (off by default; use `kamal config` for that)
+      --no-color            Disable colored output
+      --list-checks         Print all registered checks
+      --version             Print kamal-lint version
+```
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0`  | No findings at or above `--fail-on` severity |
+| `1`  | Findings present at or above `--fail-on` severity |
+| `2`  | Config file not found / unreadable |
+
+## Checks
+
+| ID | Severity | Autofixable | What it catches |
+|---|---|---|---|
+| `secret-not-declared` | error | | `env.secret` references a key absent from `.kamal/secrets` |
+| `accessory-role-undefined` | error | | accessory `roles:` lists a role not in `servers` |
+| `role-hosts-empty` | error | | a role under `servers:` has no hosts (silent no-op deploy) |
+| `image-registry-mismatch` | error | | `image:` registry prefix ≠ `builder.registry.server` |
+| `builder-registry-secret-undeclared` | error | | registry username/password references undeclared secret |
+| `ssl-without-host` | error | | `proxy.ssl: true` without `host:` (Let's Encrypt won't work) |
+| `empty-web-role` | error | | `servers:` empty or has no hosts in any role |
+| `accessory-placement-missing` | error | | accessory has no `host`/`hosts`/`roles` declared |
+| `missing-service-name` | error | ✓ | `service:` not set |
+| `traefik-legacy-keys` | warning | ✓ | Kamal 1.x `traefik:` block (silently ignored by Kamal 2+) |
+| `boot-limit-exceeds-hosts` | warning | | `boot.limit` greater than the number of hosts |
+| `kamal-secrets-not-gitignored` | warning | ✓ | `.kamal/secrets` exists but isn't gitignored |
+| `secret-in-env-clear` | warning | | `env.clear` value looks like a secret (`*_KEY`/`*_TOKEN`/`*_SECRET`/etc.) |
+| `missing-proxy-healthcheck` | warning | | `proxy:` block with no `healthcheck:` (no zero-downtime guarantee) |
+| `accessory-image-latest` | warning | | accessory pinned to `:latest` or unpinned |
+| `registry-without-explicit-server` | warning | | `registry.server` missing; image silently defaults to Docker Hub |
+
+Run `kamal-lint list-checks` for the same table in your terminal, including the Kamal version range each check applies to.
+
+## Autofix
+
+`--fix` rewrites your config in-place for the safe subset:
+
+- `traefik-legacy-keys` → translates `traefik:` to a `proxy:` block (host, ssl, app_port)
+- `missing-service-name` → infers `service:` from the project directory name
+- `kamal-secrets-not-gitignored` → appends `.kamal/secrets` to `.gitignore`
+
+```bash
+bundle exec kamal-lint --fix
+```
+
+> **Heads-up:** autofixes re-serialize your YAML, which means comments and exact formatting are not preserved. Run on a clean working tree so you can review the diff. Anything riskier (e.g. moving env.clear values to env.secret) stays manual on purpose.
+
+## Destination overrides
+
+```bash
+bundle exec kamal-lint -d production
+```
+
+Loads `config/deploy.yml`, deep-merges `config/deploy.production.yml` on top, then runs the full check suite against the merged config. Lets you catch staging/production-only issues without running `kamal deploy`.
+
+## CI / GitHub Actions
+
+Drop this into `.github/workflows/lint.yml`:
+
+```yaml
+name: kamal-lint
+on: [push, pull_request]
+jobs:
+  kamal-lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+      - run: bundle exec kamal-lint --format=github
+```
+
+The `--format=github` emits GitHub Actions workflow commands so findings show up as inline annotations on the changed file.
+
+A composite Action wrapper is also published in this repo at `action.yml`:
+
+```yaml
+- uses: davafons/kamal-lint@v0
+  with:
+    config-file: config/deploy.yml
+    destination: production
+    fail-on: warning
+```
+
+## Kamal version support
+
+`kamal-lint` reuses your installed Kamal's loader for the parse layer — it auto-tracks whatever Kamal version is in your `Gemfile.lock`. Each check declares a `since:` / `until_version:` range so the registry filters checks to those applicable to your version.
+
+| kamal-lint | supported kamal |
+|---|---|
+| `0.1.x` | `>= 2.0`, `< 3.0` |
+
+Override detection with `--kamal-version 2.5.0` when needed (e.g. for CI matrix runs).
+
+## Development
+
+```bash
+bin/setup     # bundle install
+bin/test      # run the test suite
+bin/console   # IRB with kamal-lint loaded
+```
+
+To lint the gem's own source:
+
+```bash
+BUNDLE_ONLY=rubocop bundle exec rubocop
+```
+
+## Contributing
+
+Bug reports and pull requests welcome at [github.com/davafons/kamal-lint](https://github.com/davafons/kamal-lint).
+
+## License
+
+MIT. See [MIT-LICENSE](./MIT-LICENSE).

data/action.yml

@@ -0,0 +1,61 @@
+name: kamal-lint
+description: Lint Kamal config/deploy.yml in GitHub Actions
+author: David Afonso
+branding:
+  icon: anchor
+  color: blue
+
+inputs:
+  config-file:
+    description: Path to the Kamal deploy.yml
+    required: false
+    default: config/deploy.yml
+  destination:
+    description: Destination override (e.g. production, staging)
+    required: false
+    default: ""
+  fail-on:
+    description: Minimum severity that causes a non-zero exit code (error, warning, info)
+    required: false
+    default: warning
+  fix:
+    description: Apply safe autofixes in-place (true/false)
+    required: false
+    default: "false"
+  kamal-version:
+    description: Override detected Kamal version
+    required: false
+    default: ""
+  working-directory:
+    description: Working directory to run from
+    required: false
+    default: "."
+
+runs:
+  using: composite
+  steps:
+    - name: Run kamal-lint
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      env:
+        KL_CONFIG_FILE: ${{ inputs.config-file }}
+        KL_DESTINATION: ${{ inputs.destination }}
+        KL_FAIL_ON: ${{ inputs.fail-on }}
+        KL_FIX: ${{ inputs.fix }}
+        KL_KAMAL_VERSION: ${{ inputs.kamal-version }}
+      run: |
+        set -euo pipefail
+        ARGS=(--format=github --fail-on "$KL_FAIL_ON")
+        if [ -n "$KL_CONFIG_FILE" ]; then
+          ARGS+=(--config-file "$KL_CONFIG_FILE")
+        fi
+        if [ -n "$KL_DESTINATION" ]; then
+          ARGS+=(--destination "$KL_DESTINATION")
+        fi
+        if [ -n "$KL_KAMAL_VERSION" ]; then
+          ARGS+=(--kamal-version "$KL_KAMAL_VERSION")
+        fi
+        if [ "$KL_FIX" = "true" ]; then
+          ARGS+=(--fix)
+        fi
+        bundle exec kamal-lint "${ARGS[@]}"

data/bin/kamal-lint

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "kamal/lint"
+require "kamal/lint/cli"
+
+Kamal::Lint::CLI.start(ARGV)

data/lib/kamal/lint/check.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    # Base class for all checks.
+    #
+    # Subclasses declare their identity and applicable Kamal version range with
+    # the DSL methods below and implement `#call(context)` returning an Array of
+    # Findings (possibly empty).
+    class Check
+      class << self
+        def id(value = nil)
+          @id = value if value
+          @id
+        end
+
+        def severity(value = nil)
+          @severity = value if value
+          @severity || :warning
+        end
+
+        def title(value = nil)
+          @title = value if value
+          @title
+        end
+
+        def since(value = nil)
+          @since = value if value
+          @since
+        end
+
+        def until_version(value = nil)
+          @until_version = value if value
+          @until_version
+        end
+
+        # Mark this check as autofix-capable in the registry listing.
+        def autofixable(value = nil)
+          @autofixable = value unless value.nil?
+          @autofixable || false
+        end
+
+        def applies_to?(kamal_version)
+          return true if kamal_version.nil?
+
+          if @since && Gem::Version.new(kamal_version) < Gem::Version.new(@since)
+            return false
+          end
+          if @until_version && Gem::Version.new(kamal_version) >= Gem::Version.new(@until_version)
+            return false
+          end
+
+          true
+        end
+      end
+
+      def initialize(context)
+        @context = context
+      end
+
+      attr_reader :context
+
+      def call
+        raise NotImplementedError
+      end
+
+      private
+
+      def finding(message:, line: nil, column: nil, autofix: nil)
+        Finding.new(
+          check_id: self.class.id,
+          severity: self.class.severity,
+          message: message,
+          file: context.file_for_finding,
+          line: line,
+          column: column,
+          autofix: autofix
+        )
+      end
+
+      def parsed
+        context.parsed
+      end
+
+      def secrets
+        context.secrets
+      end
+    end
+  end
+end

data/lib/kamal/lint/checks/accessory_image_latest.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class AccessoryImageLatest < Check
+        id "accessory-image-latest"
+        severity :warning
+        since "2.0.0"
+        title "Accessory image pinned to `:latest` (or unpinned)"
+
+        def call
+          accessories = parsed["accessories"]
+          return [] unless accessories.is_a?(Hash)
+
+          findings = []
+          accessories.each do |name, accessory|
+            next unless accessory.is_a?(Hash)
+
+            image = accessory["image"]
+            next unless image.is_a?(String) && !image.empty?
+
+            tag = image.split(":", 2)[1]
+            if tag.nil?
+              findings << finding(
+                message: "accessory `#{name}` image `#{image}` has no tag; defaults to `:latest` and updates unexpectedly",
+                line: context.line_for([ "accessories", name, "image" ])
+              )
+            elsif tag == "latest"
+              findings << finding(
+                message: "accessory `#{name}` image pinned to `:latest`; pin to a specific version to keep deploys reproducible",
+                line: context.line_for([ "accessories", name, "image" ])
+              )
+            end
+          end
+          findings
+        end
+      end
+
+      Lint.registry.register(AccessoryImageLatest)
+    end
+  end
+end

data/lib/kamal/lint/checks/accessory_placement_missing.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      # Accessories must declare placement via at least one of:
+      #   - host: <single host>
+      #   - hosts: [<host>, ...]
+      #   - roles: [<role>, ...]
+      # An accessory with none of these has no defined target and Kamal won't
+      # deploy it.
+      class AccessoryPlacementMissing < Check
+        id "accessory-placement-missing"
+        severity :error
+        since "2.0.0"
+        title "Accessory has no `host`, `hosts`, or `roles` declared"
+
+        def call
+          accessories = parsed["accessories"]
+          return [] unless accessories.is_a?(Hash)
+
+          findings = []
+          accessories.each do |name, accessory|
+            next unless accessory.is_a?(Hash)
+
+            has_placement = %w[host hosts roles].any? do |k|
+              value = accessory[k]
+              case value
+              when String then !value.empty?
+              when Array then value.any?
+              else !value.nil?
+              end
+            end
+
+            next if has_placement
+
+            findings << finding(
+              message: "accessory `#{name}` has no `host`, `hosts`, or `roles` declared; it will not be deployed anywhere",
+              line: context.line_for([ "accessories", name ])
+            )
+          end
+          findings
+        end
+      end
+
+      Lint.registry.register(AccessoryPlacementMissing)
+    end
+  end
+end

data/lib/kamal/lint/checks/accessory_role_undefined.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class AccessoryRoleUndefined < Check
+        id "accessory-role-undefined"
+        severity :error
+        since "2.0.0"
+        title "Accessory `roles:` lists a role not defined under `servers`"
+
+        def call
+          findings = []
+          accessories = parsed["accessories"]
+          return findings unless accessories.is_a?(Hash)
+
+          defined_roles = ServersHelper.role_names(parsed["servers"])
+
+          accessories.each do |name, accessory|
+            next unless accessory.is_a?(Hash)
+
+            roles = accessory["roles"]
+            next unless roles.is_a?(Array)
+
+            roles.each_with_index do |role, idx|
+              next unless role.is_a?(String)
+              next if defined_roles.include?(role)
+
+              findings << finding(
+                message: "accessory `#{name}` references role `#{role}` which is not defined under `servers`",
+                line: context.line_for([ "accessories", name, "roles", idx.to_s ])
+              )
+            end
+          end
+
+          findings
+        end
+      end
+
+      Lint.registry.register(AccessoryRoleUndefined)
+    end
+  end
+end

data/lib/kamal/lint/checks/boot_limit_exceeds_hosts.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "../servers_helper"
+
+module Kamal
+  module Lint
+    module Checks
+      class BootLimitExceedsHosts < Check
+        id "boot-limit-exceeds-hosts"
+        severity :warning
+        since "2.0.0"
+        title "`boot.limit` exceeds the number of hosts (no rolling effect)"
+
+        def call
+          boot = parsed["boot"]
+          return [] unless boot.is_a?(Hash)
+
+          limit = boot["limit"]
+          return [] unless limit.is_a?(Integer) && limit > 0
+
+          host_count = ServersHelper.all_hosts(parsed["servers"]).uniq.size
+          return [] if host_count == 0 || limit <= host_count
+
+          [ finding(
+            message: "boot.limit is #{limit} but only #{host_count} host(s) are configured; the limit has no effect",
+            line: context.line_for([ "boot", "limit" ])
+          ) ]
+        end
+      end
+
+      Lint.registry.register(BootLimitExceedsHosts)
+    end
+  end
+end

data/lib/kamal/lint/checks/builder_registry_secret_undeclared.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kamal
+  module Lint
+    module Checks
+      class BuilderRegistrySecretUndeclared < Check
+        id "builder-registry-secret-undeclared"
+        severity :error
+        since "2.0.0"
+        title "registry username/password references a secret not declared in .kamal/secrets"
+
+        def call
+          registry = parsed["registry"] || parsed.dig("builder", "registry")
+          return [] unless registry.is_a?(Hash)
+
+          declared = context.secrets
+          findings = []
+
+          %w[username password].each do |key|
+            value = registry[key]
+            next unless value.is_a?(Array)
+
+            value.each_with_index do |name, idx|
+              next unless name.is_a?(String)
+              next if declared.include?(name)
+
+              findings << finding(
+                message: "registry #{key} references secret `#{name}` but it isn't declared in .kamal/secrets",
+                line: context.line_for([ "registry", key, idx.to_s ]) ||
+                      context.line_for([ "builder", "registry", key, idx.to_s ])
+              )
+            end
+          end
+
+          findings
+        end
+      end
+
+      Lint.registry.register(BuilderRegistrySecretUndeclared)
+    end
+  end
+end

data/lib/kamal/lint/checks/empty_web_role.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "../servers_helper"
+
+module Kamal
+  module Lint
+    module Checks
+      class EmptyWebRole < Check
+        id "empty-web-role"
+        severity :error
+        since "2.0.0"
+        title "No web role / no hosts to deploy to"
+
+        def call
+          servers = parsed["servers"]
+
+          all_hosts = ServersHelper.all_hosts(servers)
+          if servers.nil? || (servers.is_a?(Enumerable) && servers.empty?)
+            return [ finding(
+              message: "`servers:` is missing or empty; nothing will be deployed",
+              line: context.line_for([ "servers" ]) || 1
+            ) ]
+          end
+
+          return [] unless all_hosts.empty?
+
+          [ finding(
+            message: "no hosts declared under any role in `servers:`; nothing will be deployed",
+            line: context.line_for([ "servers" ]) || 1
+          ) ]
+        end
+      end
+
+      Lint.registry.register(EmptyWebRole)
+    end
+  end
+end