feat: add ssh_signing_key input for SSH commit signing (#784)

* feat: add ssh_signing_key input for SSH commit signing

Add a new ssh_signing_key input that allows passing an SSH signing key
for commit signing, as an alternative to the existing use_commit_signing
(which uses GitHub API-based commits).

When ssh_signing_key is provided:
- Git is configured to use SSH signing (gpg.format=ssh, commit.gpgsign=true)
- The key is written to ~/.ssh/claude_signing_key with 0600 permissions
- Git CLI commands are used (not MCP file ops)
- The key is cleaned up in a post step for security

Behavior matrix:
| ssh_signing_key | use_commit_signing | Result |
|-----------------|-------------------|--------|
| not set         | false             | Regular git, no signing |
| not set         | true              | GitHub API (MCP), verified commits |
| set             | false             | Git CLI with SSH signing |
| set             | true              | Git CLI with SSH signing (ssh_signing_key takes precedence)

* docs: add SSH signing key documentation

- Update security.md with detailed setup instructions for both signing options
- Explain that ssh_signing_key enables full git CLI operations (rebasing, etc.)
- Add ssh_signing_key to inputs table in usage.md
- Update bot_id/bot_name descriptions to note they're needed for verified commits

* fix: address security review feedback for SSH signing

- Write SSH key atomically with mode 0o600 (fixes TOCTOU race condition)
- Create .ssh directory with mode 0o700 (SSH best practices)
- Add input validation for SSH key format
- Remove unused chmod import
- Add tests for validation logic

src/entrypoints/cleanup-ssh-signing.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env bun
+
+/**
+ * Cleanup SSH signing key after action completes
+ * This is run as a post step for security purposes
+ */
+
+import { cleanupSshSigning } from "../github/operations/git-config";
+
+async function run() {
+  try {
+    await cleanupSshSigning();
+  } catch (error) {
+    // Don't fail the action if cleanup fails, just log it
+    console.error("Failed to cleanup SSH signing key:", error);
+  }
+}
+
+if (import.meta.main) {
+  run();
+}

src/entrypoints/collect-inputs.ts

@@ -26,6 +26,7 @@ export function collectActionInputsPresence(): void {
     max_turns: "",
     use_sticky_comment: "false",
     use_commit_signing: "false",
+    ssh_signing_key: "",
   };
 
   const allInputsJson = process.env.ALL_INPUTS;

src/github/context.ts

@@ -90,6 +90,7 @@ type BaseContext = {
     branchPrefix: string;
     useStickyComment: boolean;
     useCommitSigning: boolean;
+    sshSigningKey: string;
     botId: string;
     botName: string;
     allowedBots: string;
@@ -146,6 +147,7 @@ export function parseGitHubContext(): GitHubContext {
       branchPrefix: process.env.BRANCH_PREFIX ?? "claude/",
       useStickyComment: process.env.USE_STICKY_COMMENT === "true",
       useCommitSigning: process.env.USE_COMMIT_SIGNING === "true",
+      sshSigningKey: process.env.SSH_SIGNING_KEY || "",
       botId: process.env.BOT_ID ?? String(CLAUDE_APP_BOT_ID),
       botName: process.env.BOT_NAME ?? CLAUDE_BOT_LOGIN,
       allowedBots: process.env.ALLOWED_BOTS ?? "",

src/github/operations/git-config.ts

@@ -6,9 +6,14 @@
  */
 
 import { $ } from "bun";
+import { mkdir, writeFile, rm } from "fs/promises";
+import { join } from "path";
+import { homedir } from "os";
 import type { GitHubContext } from "../context";
 import { GITHUB_SERVER_URL } from "../api/config";
 
+const SSH_SIGNING_KEY_PATH = join(homedir(), ".ssh", "claude_signing_key");
+
 type GitUser = {
   login: string;
   id: number;
@@ -54,3 +59,50 @@ export async function configureGitAuth(
 
   console.log("Git authentication configured successfully");
 }
+
+/**
+ * Configure git to use SSH signing for commits
+ * This is an alternative to GitHub API-based commit signing (use_commit_signing)
+ */
+export async function setupSshSigning(sshSigningKey: string): Promise<void> {
+  console.log("Configuring SSH signing for commits...");
+
+  // Validate SSH key format
+  if (!sshSigningKey.trim()) {
+    throw new Error("SSH signing key cannot be empty");
+  }
+  if (
+    !sshSigningKey.includes("BEGIN") ||
+    !sshSigningKey.includes("PRIVATE KEY")
+  ) {
+    throw new Error("Invalid SSH private key format");
+  }
+
+  // Create .ssh directory with secure permissions (700)
+  const sshDir = join(homedir(), ".ssh");
+  await mkdir(sshDir, { recursive: true, mode: 0o700 });
+
+  // Write the signing key atomically with secure permissions (600)
+  await writeFile(SSH_SIGNING_KEY_PATH, sshSigningKey, { mode: 0o600 });
+  console.log(`✓ SSH signing key written to ${SSH_SIGNING_KEY_PATH}`);
+
+  // Configure git to use SSH signing
+  await $`git config gpg.format ssh`;
+  await $`git config user.signingkey ${SSH_SIGNING_KEY_PATH}`;
+  await $`git config commit.gpgsign true`;
+
+  console.log("✓ Git configured to use SSH signing for commits");
+}
+
+/**
+ * Clean up the SSH signing key file
+ * Should be called in the post step for security
+ */
+export async function cleanupSshSigning(): Promise<void> {
+  try {
+    await rm(SSH_SIGNING_KEY_PATH, { force: true });
+    console.log("✓ SSH signing key cleaned up");
+  } catch (error) {
+    console.log("No SSH signing key to clean up");
+  }
+}

src/modes/agent/index.ts

@@ -4,7 +4,10 @@ import type { Mode, ModeOptions, ModeResult } from "../types";
 import type { PreparedContext } from "../../create-prompt/types";
 import { prepareMcpConfig } from "../../mcp/install-mcp-server";
 import { parseAllowedTools } from "./parse-tools";
-import { configureGitAuth } from "../../github/operations/git-config";
+import {
+  configureGitAuth,
+  setupSshSigning,
+} from "../../github/operations/git-config";
 import type { GitHubContext } from "../../github/context";
 import { isEntityContext } from "../../github/context";
 
@@ -79,7 +82,27 @@ export const agentMode: Mode = {
 
   async prepare({ context, githubToken }: ModeOptions): Promise<ModeResult> {
     // Configure git authentication for agent mode (same as tag mode)
-    if (!context.inputs.useCommitSigning) {
+    // SSH signing takes precedence if provided
+    const useSshSigning = !!context.inputs.sshSigningKey;
+    const useApiCommitSigning =
+      context.inputs.useCommitSigning && !useSshSigning;
+
+    if (useSshSigning) {
+      // Setup SSH signing for commits
+      await setupSshSigning(context.inputs.sshSigningKey);
+
+      // Still configure git auth for push operations (user/email and remote URL)
+      const user = {
+        login: context.inputs.botName,
+        id: parseInt(context.inputs.botId),
+      };
+      try {
+        await configureGitAuth(githubToken, context, user);
+      } catch (error) {
+        console.error("Failed to configure git authentication:", error);
+        // Continue anyway - git operations may still work with default config
+      }
+    } else if (!useApiCommitSigning) {
       // Use bot_id and bot_name from inputs directly
       const user = {
         login: context.inputs.botName,

src/modes/tag/index.ts

@@ -4,7 +4,10 @@ import { checkContainsTrigger } from "../../github/validation/trigger";
 import { checkHumanActor } from "../../github/validation/actor";
 import { createInitialComment } from "../../github/operations/comments/create-initial";
 import { setupBranch } from "../../github/operations/branch";
-import { configureGitAuth } from "../../github/operations/git-config";
+import {
+  configureGitAuth,
+  setupSshSigning,
+} from "../../github/operations/git-config";
 import { prepareMcpConfig } from "../../mcp/install-mcp-server";
 import {
   fetchGitHubData,
@@ -88,8 +91,28 @@ export const tagMode: Mode = {
     // Setup branch
     const branchInfo = await setupBranch(octokit, githubData, context);
 
-    // Configure git authentication if not using commit signing
-    if (!context.inputs.useCommitSigning) {
+    // Configure git authentication
+    // SSH signing takes precedence if provided
+    const useSshSigning = !!context.inputs.sshSigningKey;
+    const useApiCommitSigning =
+      context.inputs.useCommitSigning && !useSshSigning;
+
+    if (useSshSigning) {
+      // Setup SSH signing for commits
+      await setupSshSigning(context.inputs.sshSigningKey);
+
+      // Still configure git auth for push operations (user/email and remote URL)
+      const user = {
+        login: context.inputs.botName,
+        id: parseInt(context.inputs.botId),
+      };
+      try {
+        await configureGitAuth(githubToken, context, user);
+      } catch (error) {
+        console.error("Failed to configure git authentication:", error);
+        throw error;
+      }
+    } else if (!useApiCommitSigning) {
       // Use bot_id and bot_name from inputs directly
       const user = {
         login: context.inputs.botName,
@@ -135,8 +158,9 @@ export const tagMode: Mode = {
       ...userAllowedMCPTools,
     ];
 
-    // Add git commands when not using commit signing
-    if (!context.inputs.useCommitSigning) {
+    // Add git commands when using git CLI (no API commit signing, or SSH signing)
+    // SSH signing still uses git CLI, just with signing enabled
+    if (!useApiCommitSigning) {
       tagModeTools.push(
         "Bash(git add:*)",
         "Bash(git commit:*)",
@@ -147,7 +171,7 @@ export const tagMode: Mode = {
         "Bash(git rm:*)",
       );
     } else {
-      // When using commit signing, use MCP file ops tools
+      // When using API commit signing, use MCP file ops tools
       tagModeTools.push(
         "mcp__github_file_ops__commit_files",
         "mcp__github_file_ops__delete_files",