"Checkout PR branch" step hard-fails on merged `pull_request_target: closed` runs (deleted head branch)

[nihal467]

Summary

The generated Checkout PR branch step (from checkout_pr_branch.cjs) calls core.setFailed when it can't resolve the PR's head ref, which happens routinely on workflows triggered by pull_request_target: closed — because GitHub deletes the head branch on merge in most repos. It also fails for any fork PR, since fork branches never exist as refs in the base repo.

This causes the entire agent job to abort before posting any output, defeating the purpose of workflows like thank-you-note generators, PR-closed summarizers, etc.

Reproduction

Minimal workflow frontmatter:

on:
  pull_request_target:
    types: [closed]
tools:
  github:
    toolsets: [default]
safe-outputs:
  add-comment:
    max: 1
    target: "*"

Merge any PR whose branch gets deleted on merge → the Checkout PR branch step fails with:

fatal: couldn't find remote ref refs/heads/<branch>
failed to run git: exit status 128
Error: Process completed with exit code 128.

Example real-world run: https://github.com/ohcnetwork/care_fe/actions/runs/29501202990/job/87630447297

Current workaround

Manually patch the generated .lock.yml to add continue-on-error: true on the checkout step. This works because checkout_pr_success already has a || 'true' fallback, so downstream steps aren't misled. But every gh aw compile re-adds a bare (failing) checkout step, so the patch is fragile.

See downstream fix PR: ohcnetwork/care_fe#16576

Notes on existing frontmatter options

• checkout: false (per Repository Checkout docs) only disables the default actions/checkout step at job start. It has no effect on the PR-specific Checkout PR branch step (which uses actions/github-script + checkout_pr_branch.cjs).
• There does not appear to be any frontmatter flag to skip or soften this step.

Proposed fixes (any one would suffice)

1. Make the step continue-on-error: true by default on pull_request_target: closed (or whenever github.event.pull_request.merged may be true). The existing checkout_pr_success output correctly signals "checkout skipped, proceed anyway" to downstream steps.
2. Add a frontmatter flag such as pr-checkout: false (or on.pull_request_target.checkout: false) to opt out entirely — ideal for API-only workflows (e.g. safe-outputs.add-comment) that never read the working tree.
3. Fall back to refs/pull/<num>/head (or github.event.pull_request.merge_commit_sha) inside checkout_pr_branch.cjs when the branch ref is missing. These refs survive both branch deletion and fork PRs.

Option 1 is the smallest change and fixes the most common failure mode without any user-facing API surface. Option 2 is the cleanest for workflows that provably don't need the working tree.

Security note

If option 2 is adopted, it also removes a latent pwn_request risk — pull_request_target runs with base-repo secrets, and checking out PR head code (from forks) is generally discouraged unless followed only by read-only inspection.

Thanks for the great project.

[pelikhan]

@copilot checkout should be false by default for pull_request_target.