SSH 設定に forward_agent オプションを追加

Kamal の SSH 設定に forward_agent が指定できるようになり、エージェント転送が不要な環境でも安全にデプロイできるようになりました。

背景

SSHKit は内部で forward_agent: true をハードコードしており、ジャンプホストやトンネル（例: Cloudflare Access for Infrastructure with SSH）を経由するデプロイではエージェント転送が失敗することがありました。Kamal の ssh: 設定は SSHKit のオプションを上書きする手段を提供していなかったため、ユーザーは正しい接続を確保できませんでした。さらに設定は docs/ssh.yml に基づくバリデーションを通過しなければ受け付けられず、未知のキーはエラーとなっていました。これらの制約を解消することが今回の変更の主目的です。

技術的な変更

lib/kamal/configuration/docs/ssh.yml に forward_agent キーのドキュメントが追記され、デフォルトは true（SSHKit の既定）として記述されています。ユーザーは ssh:
forward_agent: false のように YAML に明示するだけでオプションを無効化できます。

+  # Forward agent
+  #
+  # Whether to forward the local SSH agent to the remote host. Defaults to
+  # true (sshkit's default). Set to false when connecting through a jump
+  # host or tunnel that does not support agent forwarding (for example,
+  # Cloudflare Access for Infrastructure with SSH).
+  forward_agent: false

lib/kamal/configuration/ssh.rb では forward_agent メソッドが新規に追加され、ssh_config["forward_agent"] を返すようになりました。さらに options ハッシュに forward_agent: forward_agent が組み込まれ、SSH 接続時にこの値が SSHKit に渡されます。

@@
   def forward_agent
     ssh_config["forward_agent"]
   end

   def options
-    { user: user, port: port, proxy: proxy, logger: logger, keepalive: true, keepalive_interval: 30, keys_only: keys_only, keys: keys, key_data: key_data, config: config  }.compact
+    { user: user, port: port, proxy: proxy, logger: logger, keepalive: true, keepalive_interval: 30, keys_only: keys_only, keys: keys, key_data: key_data, config: config, forward_agent: forward_agent }.compact
   end

テスト test/configuration/ssh_test.rb も更新され、forward_agent が未設定の場合は nil、false と true がそれぞれ期待通りにオプションに反映されることを検証しています。

@@
   assert_nil @config.ssh.options[:forward_agent]

   config = Kamal::Configuration.new(@deploy.tap { |c| c.merge!(ssh: { "forward_agent" => false }) })
   assert_equal false, config.ssh.options[:forward_agent]

   config = Kamal::Configuration.new(@deploy.tap { |c| c.merge!(ssh: { "forward_agent" => true }) })
   assert_equal true, config.ssh.options[:forward_agent]

設計判断

Kamal は 既存の ssh: キーを拡張 して forward_agent を露出させる方針を採用しました。新たに ssh_forward_agent など別キーを導入する案もあったものの、既存キーの拡張は後方互換性を保ちつつ SSHKit のデフォルト挙動（true）をそのまま継承できるため最小限の変更で済みました。options ハッシュへの追加は compact による nil 削除だけで完結し、既存コードへの影響は実質なしです。

まとめ

この PR により Kamal の SSH 設定で forward_agent オプションを明示的に制御できるようになり、ジャンプホストやトンネル環境でも安全にデプロイが可能になります。設定項目は文書化され、テストで動作が保証されたため、既存ユーザーへの影術的リスクは最小限です。