Feature request: merge-pull-request safe-output

[microsasa]

Summary

Agents can create PRs (create-pull-request), close PRs (close-pull-request), push to PR branches (push-to-pull-request-branch), and submit reviews (submit-pull-request-review) — but they cannot merge PRs. merge-pull-request would complete the PR lifecycle coverage.

Motivation

1. Autonomous merge pipelines

A common pattern for autonomous pipelines:

• Agent creates a PR → CI passes → code review agent evaluates quality and blast radius → agent merges low-risk changes

Today this requires auto-merge: true on PR creation, relying on GitHub's auto-merge to fire when branch protection conditions are met. This works but removes agent control — the merge happens automatically as soon as conditions align, not when the agent explicitly decides to merge.

2. Race condition with enforce_admins and auto-merge

Repos with enforce_admins: true and branch protection (e.g., required approvals) cannot safely use auto-merge alongside admin merges. The pattern for admin merges:

DELETE /repos/{owner}/{repo}/branches/main/protection/enforce_admins
gh pr merge <PR> --merge --admin
POST /repos/{owner}/{repo}/branches/main/protection/enforce_admins

Between the DELETE and POST, enforce_admins is disabled. During this window, GitHub's auto-merge on other PRs can fire — because admins can now bypass the approval requirement. This causes PRs to merge without required approvals.

A merge-pull-request safe-output would let agents merge explicitly, eliminating the dependency on auto-merge and this race condition entirely.

3. Consistency with PR lifecycle safe-outputs

Action	Safe-output	Available
Create PR	create-pull-request	✅
Push to PR branch	push-to-pull-request-branch	✅
Submit review	submit-pull-request-review	✅
Close PR	close-pull-request	✅
Merge PR	—	❌

Merge is the only missing PR lifecycle action.

Example Usage

safe-outputs:
  merge-pull-request:
    max: 1
    github-token: ${{ secrets.GH_AW_WRITE_TOKEN }}

Guardrail Considerations

Merge is a higher-stakes action than close or review. Some guardrail ideas worth exploring — not all of these may be appropriate, but they are patterns that could help users adopt this safely:

• require-passing-checks: true — Refuse to merge if any required status checks are failing. This is already enforced by branch protection, but an explicit safe-output-level check would provide defense in depth and a clearer error message to the agent.

• require-approval: true — Only merge if the PR has at least one approving review. Prevents agents from both approving and merging in the same workflow (separation of concerns). Could default to true.

• allowed-merge-methods: [merge, squash, rebase] — Let workflow authors restrict which merge strategies agents can use. Some repos enforce merge commits for auditability; others require squash for clean history.

• delete-branch: true|false — Whether to delete the head branch after merge. Follows the same pattern as gh pr merge --delete-branch.

• Existing guardrails — max, required-labels, required-title-prefix, target, and staged from other safe-outputs would apply naturally here. max: 1 per workflow run seems like a sensible default for merge.

The right set of guardrails is ultimately a design decision for the gh-aw team — these are just patterns we have seen a need for in practice.