Make push_to_pull_request_branch cross-repo

[Corb3nik]

Summary

Today the docs state that Push to PR Branch is "same-repo only" (safe-outputs.md line 41). The handler already supports target-repo and allowed-repos in config and resolves the target repo for the GitHub API; the missing piece is patch generation and conclusion git operations both assume a single workspace root. When the workflow checks out the target repo under a path (e.g. ./proxy-frontend for caido/proxy-frontend), patch generation runs in the workspace root and finds no commits, and the conclusion job runs git fetch/checkout/apply in the wrong directory. This plan makes push_to_pull_request_branch work end-to-end for cross-repo and multi-checkout.

---

Analysis

Current behavior

• Config: compiler_types.go and safe_outputs_config_generation.go already pass target-repo (and allowed-repos) into the handler config. cross-repository.md already shows push-to-pull-request-branch: target-repo: "org/target-repo".
• MCP handler (safe_outputs_handlers.cjs pushToPullRequestBranchHandler): Resolves target repo via resolveAndValidateRepo(entry, defaultTargetRepo, allowedRepos) and gets baseBranch for that repo, but then calls getCurrentBranch() with no args and generateGitPatch(entry.branch, baseBranch, pushPatchOptions) without cwd or repoSlug. So patch generation always runs in GITHUB_WORKSPACE / process.cwd() (e.g. ai-ops root). If the agent committed in ./proxy-frontend, that repo’s branch/commits are invisible there → "No commits were found to push."
• Conclusion handler (push_to_pull_request_branch.cjs): Uses resolveAndValidateRepo and runs git fetch, git checkout, git apply via exec.exec with no cwd. So git runs in the job’s default cwd (workspace root), not in the target repo’s checkout.

Existing pattern to reuse

• create_pull_request in safe_outputs_handlers.cjs: When entry.repo is set, it calls findRepoCheckout(repoSlug), uses repoCwd = checkoutResult.path, passes getCurrentBranch(repoCwd) and patchOptions.cwd / patchOptions.repoSlug into generateGitPatch. So patch is generated from the correct repo directory.
• generate_git_patch.cjs already supports options.cwd and options.repoSlug (lines 91–95).
• get_current_branch.cjs accepts customCwd.
• find_repo_checkout.cjs returns { success, path, repoSlug } for a given owner/repo slug.

Gap

1. MCP handler: For push_to_pull_request_branch, after resolving repoResult (so we have itemRepo), we never call findRepoCheckout(itemRepo). We should: if we have a resolved target repo, find its checkout path; use that for getCurrentBranch(cwd) and for generateGitPatch(..., { cwd, repoSlug, ... }). If target repo is configured but not found in workspace, return a clear error (e.g. "Repository 'org/repo' not found in workspace. Check out the target repo with a path in checkout.").
2. Conclusion handler: Before running any git commands, resolve the target repo (already done) then resolve the path to that repo’s checkout (e.g. via findRepoCheckout(itemRepo)). Run all git operations (fetch, checkout, apply, push) with that directory as the working directory (e.g. exec.exec(..., { cwd: repoPath }) or a single process.chdir(repoPath) at the start of the push logic for that message).
3. Docs: Remove "same-repo only" for push-to-pull-request-branch and document cross-repo (target-repo, allowed-repos, checkout path requirement).
4. Tool schema (optional): Add optional repo parameter to safe_outputs_tools.json for push_to_pull_request_branch so when allowed-repos has multiple repos the agent can specify which one; align with create_pull_request. If scope is kept minimal, this can be a follow-up.

---

Implementation plan

1. MCP handler – patch generation in target repo directory

File: actions/setup/js/safe_outputs_handlers.cjs

• In pushToPullRequestBranchHandler, after resolveAndValidateRepo and getBaseBranch(repoParts):
  • Set itemRepo = repoResult.repo (the resolved slug, e.g. caido/proxy-frontend).
  • Call findRepoCheckout(itemRepo, undefined, { allowedRepos }). If !checkoutResult.success, return a JSON error with a clear message that the target repo must be checked out with a path (point to checkout path docs or cross-repository.md).
  • Set repoCwd = checkoutResult.path, repoSlug = itemRepo.
• When branch is not provided or equals base branch: call getCurrentBranch(repoCwd) instead of getCurrentBranch().
• When building pushPatchOptions: if repoCwd is set, add pushPatchOptions.cwd = repoCwd and pushPatchOptions.repoSlug = repoSlug.
• Pass pushPatchOptions into generateGitPatch(entry.branch, baseBranch, pushPatchOptions) (already done; only the contents of pushPatchOptions change).

This mirrors the create_pull_request branch/patch flow (lines 253–331) for push_to_pull_request_branch.

2. Conclusion handler – run git in target repo directory

File: actions/setup/js/push_to_pull_request_branch.cjs

• Require findRepoCheckout from ./find_repo_checkout.cjs.
• After resolving the target repo (repoResult / itemRepo) and before running any git commands (fetch, checkout, apply, push), resolve the checkout path:
  • If itemRepo differs from process.env.GITHUB_REPOSITORY (or whenever defaultTargetRepo is set), call findRepoCheckout(itemRepo, process.env.GITHUB_WORKSPACE, { allowedRepos }). If not found, return { success: false, error: "..." } with a message that the target repo must be checked out with a path.
  • Set repoCwd = checkoutResult.path.
• Run all git operations for this message in repoCwd: use exec.exec("git", [...], { cwd: repoCwd, env: { ...process.env, ...gitAuthEnv } }) (and equivalent for any other git calls) so that fetch, checkout, apply, and push run in the target repo. Alternatively, process.chdir(repoCwd) at the start of the push block and restore cwd in a finally block; prefer explicit cwd in exec to avoid global state.
• Ensure getGitAuthEnv is still applied for fetch/push in the target repo.

3. Tests

Files: actions/setup/js/safe_outputs_handlers.cjs (or a dedicated test file if handlers are tested elsewhere), actions/setup/js/push_to_pull_request_branch.test.cjs

• Add or extend tests for push_to_pull_request_branch when target-repo is set and the workspace contains the target repo at a subdirectory: mock or fixture with two checkouts (e.g. root = workflow repo, subdir = target repo); assert patch generation is called with cwd and repoSlug pointing at the target repo.
• Add a test for conclusion handler: when target repo is different from GITHUB_REPOSITORY, assert git commands are run with cwd set to the target repo path (or that findRepoCheckout is invoked and its path is used).
• Add a test for error path: target-repo configured but that repo is not found in workspace; assert a clear error is returned (MCP handler and, if feasible, conclusion handler).

4. Documentation

File: docs/src/content/docs/reference/safe-outputs.md

• Remove "same-repo only" from the Push to PR Branch bullet (line 41). Replace with wording that cross-repo is supported when target-repo is set and the target repository is checked out (e.g. with a path in checkout).

File: docs/src/content/docs/reference/safe-outputs-pull-requests.md (and cross-repository.md if needed)

• In the Push to PR Branch section, add a short "Cross-repo" subsection: when using target-repo (and optionally allowed-repos), the target repository must be checked out in the workspace (e.g. checkout: - repository: org/target-repo; path: ./target-repo). Link to cross-repository.md and the existing example that shows push-to-pull-request-branch: target-repo: "org/target-repo".

5. Go / validation (optional)

• pkg/workflow/safe_outputs_validation_config.go: push_to_pull_request_branch currently has "branch": {Required: true}. The tool schema treats branch as optional (defaulting to current branch). If the implementing agent finds that Required: true causes validation failures when branch is omitted in cross-repo flows, relax to optional or align with create_pull_request.
• No change to compiler or config generation is strictly required for the above; target-repo and allowed-repos are already passed through.

6. Tool schema (optional follow-up)

• In pkg/workflow/js/safe_outputs_tools.json, add an optional repo property to the push_to_pull_request_branch tool (type string, description: target repository in owner/repo format; when omitted, use the configured target repository; must be in allowed-repos if specified). This allows the agent to disambiguate when multiple repos are allowed. Implement only if the first iteration supports multiple allowed-repos and the agent needs to pass repo explicitly.

---

Guidelines for the implementing agent

• Follow scratchpad/code-organization.md and scratchpad/testing.md.
• Use existing helpers: findRepoCheckout, getCurrentBranch(customCwd), generateGitPatch(..., { cwd, repoSlug }), resolveAndValidateRepo, resolveTargetRepoConfig.
• Error messages: use the template [what's wrong]. [what's expected]. [example] per CONTRIBUTING.md.
• Run make agent-finish before completing (build, test, recompile, format, lint).
• After implementation, a workflow that runs in repo A with checkout: - repository: B; path: ./B and push-to-pull-request-branch: target-repo: "B" should generate the patch from ./B and apply/push in ./B, so commits made in ./B are pushed correctly.

---

Out of scope (for this issue)

• Adding an optional repo argument to the tool (can be a follow-up issue).
• Changing how the activation job checks out repos (no change to checkout_manager or compiler_activation_job for this issue).
• Fork PR handling (unchanged).

[pelikhan]

/scout review other push code handlers line create-repository and align plan.

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

Reviewed how create_pull_request handles cross-repo push code and compared both its MCP handler and conclusion handler patterns against the plan in this issue. The plan's approach (findRepoCheckout + cwd) is sound and consistent with the MCP handler pattern, but the conclusion handler in create_pull_request.cjs uses a different mechanism (dynamic_checkout.cjs / checkoutManager) worth understanding before implementing.

Detailed Findings

Cross-Repo Strategy Comparison

create_pull_request MCP handler (already cross-repo aware)

File: safe_outputs_handlers.cjs lines 247–276

Uses findRepoCheckout when entry.repo is set by the agent:

const checkoutResult = findRepoCheckout(repoSlug);          // find subdirectory
repoCwd = checkoutResult.path;
getCurrentBranch(repoCwd);
generateGitPatch(branch, baseBranch, { cwd: repoCwd, repoSlug });

This is the pattern the issue correctly says to copy into pushToPullRequestBranchHandler.

---

create_pull_request.cjs conclusion handler (different strategy!)

File: create_pull_request.cjs lines 192–288

Uses checkoutManager from dynamic_checkout.cjs — NOT findRepoCheckout:

const checkoutManager = createCheckoutManager(GITHUB_TOKEN);
await checkoutManager.switchTo(itemRepo, { baseBranch });
// Then runs exec.exec("git", [...]) with no cwd

switchTo works by changing remote.origin.url in the CURRENT workspace directory, fetching the target repo, and checking out its base branch. After that, all git fetch/checkout/am/push calls operate on the modified workspace (no cwd needed). Uses GITHUB_TOKEN — no extra PAT required.

---

push_to_pull_request_branch.cjs conclusion handler (current state — neither approach)

File: push_to_pull_request_branch.cjs lines 382–490

All git operations run without cwd:

exec.exec("git", ["fetch", "origin", `${branchName}:refs/remotes/...`], { env: gitAuthEnv });
exec.exec(`git checkout -B ${branchName} origin/${branchName}`);
exec.exec(`git am --3way ${patchFilePath}`);
exec.exec("git", ["push", "origin", branchName], { env: gitAuthEnv });

These all run in GITHUB_WORKSPACE root → wrong directory for cross-repo scenarios.

---

Plan Alignment Analysis

	MCP handler	Conclusion handler
create_pull_request	findRepoCheckout + cwd ✅	checkoutManager.switchTo() (changes remote URL)
Plan for push_to_pull_request_branch	findRepoCheckout + cwd ✅	findRepoCheckout + cwd (different from create_pull_request.cjs)
Current push_to_pull_request_branch	❌ no cwd	❌ no cwd

Why findRepoCheckout + cwd is Preferred for the Conclusion Handler

The plan's choice of findRepoCheckout + explicit cwd (rather than checkoutManager) is appropriate because:

1. No side effects – checkoutManager.switchTo() mutates remote.origin.url in the workspace, which could interfere with other git operations in the same job. cwd-based approach is clean.
2. Auth consistency – push_to_pull_request_branch.cjs already uses gitAuthEnv (GIT_CONFIG_* env vars) for all push/fetch operations. The checkoutManager uses a different token-embedding approach. These two auth mechanisms don't compose cleanly.
3. Workspace pre-checkout is already documented – cross-repository.md already requires actions/checkout path: for target repos, so findRepoCheckout reliably finds the subdirectory.
4. cwd scoping – Many exec calls in the conclusion handler already have { env: gitAuthEnv } options; adding cwd: repoCwd to those same options blocks is minimal and surgical.

MCP Handler Condition Difference (important nuance)

• create_pull_request MCP handler triggers findRepoCheckout when entry.repo is explicitly set by the agent.
• For push_to_pull_request_branch, there is no repo parameter in the tool schema yet (step 6 is optional). The plan correctly says to trigger findRepoCheckout when defaultTargetRepo is set AND itemRepo !== process.env.GITHUB_REPOSITORY.

Exec calls that need cwd in the conclusion handler

All of these in push_to_pull_request_branch.cjs need { cwd: repoCwd, env: gitAuthEnv } (for fetch/push) or { cwd: repoCwd } (for read-only ops):

Line	Operation
384	git fetch origin ${branchName}:refs/remotes/origin/${branchName}
393	git rev-parse --verify origin/${branchName}
400	git checkout -B ${branchName} origin/${branchName}
441	git rev-parse HEAD (pre-patch SHA)
449	git am --3way ${patchFilePath}
458–470	git status / log / diff / am investigation
486	git push origin ${branchName}
504	git rev-list --count ${remoteHeadBeforePatch}..HEAD
531	git rev-parse HEAD (post-push SHA)

Plan Step 2 Condition Clarification

The plan says: "if itemRepo differs from process.env.GITHUB_REPOSITORY (or whenever defaultTargetRepo is set)". In practice, the cleanest implementation is:

// After: const { repo: itemRepo, repoParts } = repoResult;
let repoCwd = null;
if (itemRepo !== process.env.GITHUB_REPOSITORY) {
  const checkoutResult = findRepoCheckout(itemRepo, process.env.GITHUB_WORKSPACE, { allowedRepos });
  if (!checkoutResult.success) {
    return { success: false, error: `Repository '${itemRepo}' not found in workspace. Check it out with a 'path:' parameter in actions/checkout.` };
  }
  repoCwd = checkoutResult.path;
}
// Then pass repoCwd to all exec.exec calls

This is also consistent with push_to_pull_request_branch.cjs not importing findRepoCheckout today — it needs to be added as a require.

Recommendations

1. Plan is correct – the findRepoCheckout + cwd approach for both MCP handler and conclusion handler is the right choice. No change needed to the overall strategy.

2. Note the divergence from create_pull_request.cjs – document in the implementation that this handler intentionally uses findRepoCheckout + cwd (not checkoutManager) because it already uses gitAuthEnv for auth and requires the target repo to be pre-checked-out.

3. Don't forget to require findRepoCheckout in push_to_pull_request_branch.cjs (it's not currently imported there).

4. MCP handler condition: trigger findRepoCheckout when defaultTargetRepo is configured and itemRepo !== GITHUB_REPOSITORY, not just when entry.repo is set (since the tool has no repo parameter yet).

5. All 9 exec operations in the conclusion handler need cwd added — see table above.

References:

• §23175624188

🔭 Intelligence gathered by Scout · ◷