feat: defer remote branch creation until first commit (#244)

* feat: defer remote branch creation until first commit

- For commit signing: branches are created remotely by github-file-ops-server on first commit
- For non-signing: branches are created locally with 'git checkout -b' and pushed when needed
- Consolidated duplicate branch creation logic in github-file-ops-server into a shared helper function
- Claude is unaware of these implementation details and simply sees it's on the correct branch
- No branch links are shown in initial comments since branches don't exist remotely yet

* fix: prevent broken branch links in final comment update

- Check if branch exists remotely before adding branch link
- Only add branch links for branches that actually exist on GitHub
- Add test coverage for non-existent remote branches
- Fixes issue where users would see broken branch links for local-only branches

* fix: don't show branch name in comment header when branch doesn't exist remotely

- Only pass branchName to updateCommentBody when branchLink exists
- Prevents showing branch names for branches that only exist locally
- Add test to verify branch name is not shown when branch doesn't exist

* tmp

src/entrypoints/prepare.ts

@@ -12,7 +12,6 @@ import { checkHumanActor } from "../github/validation/actor";
 import { checkWritePermissions } from "../github/validation/permissions";
 import { createInitialComment } from "../github/operations/comments/create-initial";
 import { setupBranch } from "../github/operations/branch";
-import { updateTrackingComment } from "../github/operations/comments/update-with-branch";
 import { configureGitAuth } from "../github/operations/git-config";
 import { prepareMcpConfig } from "../mcp/install-mcp-server";
 import { createPrompt } from "../create-prompt";
@@ -67,17 +66,7 @@ async function run() {
     // Step 8: Setup branch
     const branchInfo = await setupBranch(octokit, githubData, context);
 
-    // Step 9: Update initial comment with branch link (only for issues that created a new branch)
+    // Step 9: Configure git authentication if not using commit signing
-    if (branchInfo.claudeBranch) {
-      await updateTrackingComment(
-        octokit,
-        context,
-        commentId,
-        branchInfo.claudeBranch,
-      );
-    }
-
-    // Step 10: Configure git authentication if not using commit signing
     if (!context.inputs.useCommitSigning) {
       try {
         await configureGitAuth(githubToken, context, commentData.user);
@@ -87,7 +76,7 @@ async function run() {
       }
     }
 
-    // Step 11: Create prompt file
+    // Step 10: Create prompt file
     await createPrompt(
       commentId,
       branchInfo.baseBranch,
@@ -96,7 +85,7 @@ async function run() {
       context,
     );
 
-    // Step 12: Get MCP configuration
+    // Step 11: Get MCP configuration
     const additionalMcpConfig = process.env.MCP_CONFIG || "";
     const mcpConfig = await prepareMcpConfig({
       githubToken,

src/entrypoints/update-comment-link.ts

@@ -201,7 +201,7 @@ async function run() {
       jobUrl,
       branchLink,
       prLink,
-      branchName: shouldDeleteBranch ? undefined : claudeBranch,
+      branchName: shouldDeleteBranch || !branchLink ? undefined : claudeBranch,
       triggerUsername,
       errorDetails,
     };

src/github/operations/branch-cleanup.ts

@@ -14,6 +14,31 @@ export async function checkAndCommitOrDeleteBranch(
   let shouldDeleteBranch = false;
 
   if (claudeBranch) {
+    // First check if the branch exists remotely
+    let branchExistsRemotely = false;
+    try {
+      await octokit.rest.repos.getBranch({
+        owner,
+        repo,
+        branch: claudeBranch,
+      });
+      branchExistsRemotely = true;
+    } catch (error: any) {
+      if (error.status === 404) {
+        console.log(`Branch ${claudeBranch} does not exist remotely`);
+      } else {
+        console.error("Error checking if branch exists:", error);
+      }
+    }
+
+    // Only proceed if branch exists remotely
+    if (!branchExistsRemotely) {
+      console.log(
+        `Branch ${claudeBranch} does not exist remotely, no branch link will be added`,
+      );
+      return { shouldDeleteBranch: false, branchLink: "" };
+    }
+
     // Check if Claude made any commits to the branch
     try {
       const { data: comparison } =
@@ -81,8 +106,8 @@ export async function checkAndCommitOrDeleteBranch(
         branchLink = `\n[View branch](${branchUrl})`;
       }
     } catch (error) {
-      console.error("Error checking for commits on Claude branch:", error);
+      console.error("Error comparing commits on Claude branch:", error);
-      // If we can't check, assume the branch has commits to be safe
+      // If we can't compare but the branch exists remotely, include the branch link
       const branchUrl = `${GITHUB_SERVER_URL}/${owner}/${repo}/tree/${claudeBranch}`;
       branchLink = `\n[View branch](${branchUrl})`;
     }

src/github/operations/branch.ts

@@ -84,12 +84,8 @@ export async function setupBranch(
     sourceBranch = repoResponse.data.default_branch;
   }
 
-  // Creating a new branch for either an issue or closed/merged PR
+  // Generate branch name for either an issue or closed/merged PR
   const entityType = isPR ? "pr" : "issue";
-  console.log(
-    `Creating new branch for ${entityType} #${entityNumber} from source branch: ${sourceBranch}...`,
-  );
-
   const timestamp = new Date()
     .toISOString()
     .replace(/[:-]/g, "")
@@ -100,7 +96,7 @@ export async function setupBranch(
   const newBranch = `${branchPrefix}${entityType}-${entityNumber}-${timestamp}`;
 
   try {
-    // Get the SHA of the source branch
+    // Get the SHA of the source branch to verify it exists
     const sourceBranchRef = await octokits.rest.git.getRef({
       owner,
       repo,
@@ -108,23 +104,34 @@ export async function setupBranch(
     });
 
     const currentSHA = sourceBranchRef.data.object.sha;
+    console.log(`Source branch SHA: ${currentSHA}`);
 
-    console.log(`Current SHA: ${currentSHA}`);
+    // For commit signing, defer branch creation to the file ops server
+    if (context.inputs.useCommitSigning) {
+      console.log(
+        `Branch name generated: ${newBranch} (will be created by file ops server on first commit)`,
+      );
 
-    // Create branch using GitHub API
+      // Set outputs for GitHub Actions
-    await octokits.rest.git.createRef({
+      core.setOutput("CLAUDE_BRANCH", newBranch);
-      owner,
+      core.setOutput("BASE_BRANCH", sourceBranch);
-      repo,
+      return {
-      ref: `refs/heads/${newBranch}`,
+        baseBranch: sourceBranch,
-      sha: currentSHA,
+        claudeBranch: newBranch,
-    });
+        currentBranch: sourceBranch, // Stay on source branch for now
+      };
+    }
 
-    // Checkout the new branch (shallow fetch for performance)
+    // For non-signing case, create and checkout the branch locally only
-    await $`git fetch origin --depth=1 ${newBranch}`;
+    console.log(
-    await $`git checkout ${newBranch}`;
+      `Creating local branch ${newBranch} for ${entityType} #${entityNumber} from source branch: ${sourceBranch}...`,
+    );
+
+    // Create and checkout the new branch locally
+    await $`git checkout -b ${newBranch}`;
 
     console.log(
-      `Successfully created and checked out new branch: ${newBranch}`,
+      `Successfully created and checked out local branch: ${newBranch}`,
     );
 
     // Set outputs for GitHub Actions
@@ -136,7 +143,7 @@ export async function setupBranch(
       currentBranch: newBranch,
     };
   } catch (error) {
-    console.error("Error creating branch:", error);
+    console.error("Error in branch setup:", error);
     process.exit(1);
   }
 }

src/mcp/github-file-ops-server.ts

@@ -52,6 +52,120 @@ const server = new McpServer({
   version: "0.0.1",
 });
 
+// Helper function to get or create branch reference
+async function getOrCreateBranchRef(
+  owner: string,
+  repo: string,
+  branch: string,
+  githubToken: string,
+): Promise<string> {
+  // Try to get the branch reference
+  const refUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/refs/heads/${branch}`;
+  const refResponse = await fetch(refUrl, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${githubToken}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+  });
+
+  if (refResponse.ok) {
+    const refData = (await refResponse.json()) as GitHubRef;
+    return refData.object.sha;
+  }
+
+  if (refResponse.status !== 404) {
+    throw new Error(`Failed to get branch reference: ${refResponse.status}`);
+  }
+
+  // Branch doesn't exist, need to create it
+  console.log(`Branch ${branch} does not exist, creating it...`);
+
+  // Get base branch from environment or determine it
+  const baseBranch = process.env.BASE_BRANCH || "main";
+
+  // Get the SHA of the base branch
+  const baseRefUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/refs/heads/${baseBranch}`;
+  const baseRefResponse = await fetch(baseRefUrl, {
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${githubToken}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+    },
+  });
+
+  let baseSha: string;
+
+  if (!baseRefResponse.ok) {
+    // If base branch doesn't exist, try default branch
+    const repoUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}`;
+    const repoResponse = await fetch(repoUrl, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${githubToken}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+    });
+
+    if (!repoResponse.ok) {
+      throw new Error(`Failed to get repository info: ${repoResponse.status}`);
+    }
+
+    const repoData = (await repoResponse.json()) as {
+      default_branch: string;
+    };
+    const defaultBranch = repoData.default_branch;
+
+    // Try default branch
+    const defaultRefUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/refs/heads/${defaultBranch}`;
+    const defaultRefResponse = await fetch(defaultRefUrl, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${githubToken}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+    });
+
+    if (!defaultRefResponse.ok) {
+      throw new Error(
+        `Failed to get default branch reference: ${defaultRefResponse.status}`,
+      );
+    }
+
+    const defaultRefData = (await defaultRefResponse.json()) as GitHubRef;
+    baseSha = defaultRefData.object.sha;
+  } else {
+    const baseRefData = (await baseRefResponse.json()) as GitHubRef;
+    baseSha = baseRefData.object.sha;
+  }
+
+  // Create the new branch
+  const createRefUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/refs`;
+  const createRefResponse = await fetch(createRefUrl, {
+    method: "POST",
+    headers: {
+      Accept: "application/vnd.github+json",
+      Authorization: `Bearer ${githubToken}`,
+      "X-GitHub-Api-Version": "2022-11-28",
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      ref: `refs/heads/${branch}`,
+      sha: baseSha,
+    }),
+  });
+
+  if (!createRefResponse.ok) {
+    const errorText = await createRefResponse.text();
+    throw new Error(
+      `Failed to create branch: ${createRefResponse.status} - ${errorText}`,
+    );
+  }
+
+  console.log(`Successfully created branch ${branch}`);
+  return baseSha;
+}
+
 // Commit files tool
 server.tool(
   "commit_files",
@@ -81,24 +195,13 @@ server.tool(
         return filePath;
       });
 
-      // 1. Get the branch reference
+      // 1. Get the branch reference (create if doesn't exist)
-      const refUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/refs/heads/${branch}`;
+      const baseSha = await getOrCreateBranchRef(
-      const refResponse = await fetch(refUrl, {
+        owner,
-        headers: {
+        repo,
-          Accept: "application/vnd.github+json",
+        branch,
-          Authorization: `Bearer ${githubToken}`,
+        githubToken,
-          "X-GitHub-Api-Version": "2022-11-28",
-        },
-      });
-
-      if (!refResponse.ok) {
-        throw new Error(
-          `Failed to get branch reference: ${refResponse.status}`,
       );
-      }
-
-      const refData = (await refResponse.json()) as GitHubRef;
-      const baseSha = refData.object.sha;
 
       // 2. Get the base commit
       const commitUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/commits/${baseSha}`;
@@ -260,7 +363,6 @@ server.tool(
 
             // Only retry on 403 errors - these are the intermittent failures we're targeting
             if (updateRefResponse.status === 403) {
-              console.log("Received 403 error, will retry...");
               throw error;
             }
 
@@ -353,24 +455,13 @@ server.tool(
         return filePath;
       });
 
-      // 1. Get the branch reference
+      // 1. Get the branch reference (create if doesn't exist)
-      const refUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/refs/heads/${branch}`;
+      const baseSha = await getOrCreateBranchRef(
-      const refResponse = await fetch(refUrl, {
+        owner,
-        headers: {
+        repo,
-          Accept: "application/vnd.github+json",
+        branch,
-          Authorization: `Bearer ${githubToken}`,
+        githubToken,
-          "X-GitHub-Api-Version": "2022-11-28",
-        },
-      });
-
-      if (!refResponse.ok) {
-        throw new Error(
-          `Failed to get branch reference: ${refResponse.status}`,
       );
-      }
-
-      const refData = (await refResponse.json()) as GitHubRef;
-      const baseSha = refData.object.sha;
 
       // 2. Get the base commit
       const commitUrl = `${GITHUB_API_URL}/repos/${owner}/${repo}/git/commits/${baseSha}`;

src/mcp/install-mcp-server.ts

@@ -100,6 +100,7 @@ export async function prepareMcpConfig(
           REPO_OWNER: owner,
           REPO_NAME: repo,
           BRANCH_NAME: branch,
+          BASE_BRANCH: process.env.BASE_BRANCH || "",
           REPO_DIR: process.env.GITHUB_WORKSPACE || process.cwd(),
           GITHUB_EVENT_NAME: process.env.GITHUB_EVENT_NAME || "",
           IS_PR: process.env.IS_PR || "false",

test/branch-cleanup.test.ts

@@ -21,6 +21,7 @@ describe("checkAndCommitOrDeleteBranch", () => {
   const createMockOctokit = (
     compareResponse?: any,
     deleteRefError?: Error,
+    branchExists: boolean = true,
   ): Octokits => {
     return {
       rest: {
@@ -28,6 +29,14 @@ describe("checkAndCommitOrDeleteBranch", () => {
           compareCommitsWithBasehead: async () => ({
             data: compareResponse || { total_commits: 0 },
           }),
+          getBranch: async () => {
+            if (!branchExists) {
+              const error: any = new Error("Not Found");
+              error.status = 404;
+              throw error;
+            }
+            return { data: {} };
+          },
         },
         git: {
           deleteRef: async () => {
@@ -102,6 +111,7 @@ describe("checkAndCommitOrDeleteBranch", () => {
           compareCommitsWithBasehead: async () => {
             throw new Error("API error");
           },
+          getBranch: async () => ({ data: {} }), // Branch exists
         },
         git: {
           deleteRef: async () => ({ data: {} }),
@@ -123,7 +133,7 @@ describe("checkAndCommitOrDeleteBranch", () => {
       `\n[View branch](${GITHUB_SERVER_URL}/owner/repo/tree/claude/issue-123-20240101_123456)`,
     );
     expect(consoleErrorSpy).toHaveBeenCalledWith(
-      "Error checking for commits on Claude branch:",
+      "Error comparing commits on Claude branch:",
       expect.any(Error),
     );
   });
@@ -148,4 +158,30 @@ describe("checkAndCommitOrDeleteBranch", () => {
       deleteError,
     );
   });
+
+  test("should return no branch link when branch doesn't exist remotely", async () => {
+    const mockOctokit = createMockOctokit(
+      { total_commits: 0 },
+      undefined,
+      false, // branch doesn't exist
+    );
+
+    const result = await checkAndCommitOrDeleteBranch(
+      mockOctokit,
+      "owner",
+      "repo",
+      "claude/issue-123-20240101_123456",
+      "main",
+      false,
+    );
+
+    expect(result.shouldDeleteBranch).toBe(false);
+    expect(result.branchLink).toBe("");
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      "Branch claude/issue-123-20240101_123456 does not exist remotely",
+    );
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      "Branch claude/issue-123-20240101_123456 does not exist remotely, no branch link will be added",
+    );
+  });
 });

test/comment-logic.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect } from "bun:test";
-import { updateCommentBody } from "../src/github/operations/comment-logic";
+import {
+  updateCommentBody,
+  type CommentUpdateInput,
+} from "../src/github/operations/comment-logic";
 
 describe("updateCommentBody", () => {
   const baseInput = {
@@ -417,5 +420,27 @@ describe("updateCommentBody", () => {
         "• [Create PR ➔](https://github.com/owner/repo/compare/main...claude/issue-123-20240101_120000)",
       );
     });
+
+    it("should not show branch name when branch doesn't exist remotely", () => {
+      const input: CommentUpdateInput = {
+        currentBody: "@claude can you help with this?",
+        actionFailed: false,
+        executionDetails: { duration_ms: 90000 },
+        jobUrl: "https://github.com/owner/repo/actions/runs/123",
+        branchLink: "", // Empty branch link means branch doesn't exist remotely
+        branchName: undefined, // Should be undefined when branchLink is empty
+        triggerUsername: "claude",
+        prLink: "",
+      };
+
+      const result = updateCommentBody(input);
+
+      expect(result).toContain("Claude finished @claude's task in 1m 30s");
+      expect(result).toContain(
+        "[View job](https://github.com/owner/repo/actions/runs/123)",
+      );
+      expect(result).not.toContain("claude/issue-123");
+      expect(result).not.toContain("tree/claude/issue-123");
+    });
   });
 });