[project]
repo = "org/project"

[gating]
human_merge_required = true      # If true: report ready-to-merge but do NOT merge
auto_merge_after_review = false  # If true: merge immediately when checks pass
require_human_review_for = ["*"] # Glob patterns requiring human sign-off

Step 1 — PR Status Check

gh pr view $PR_NUMBER --repo $REPO \
  --json number,title,state,mergeable,mergeStateStatus,labels,reviewDecision,statusCheckRollup

Check each gate in order, stopping at the first failure:

Gate	Check	Blocking?
PR open	`state == "OPEN"`	Yes
Not already labeled blocked	No `human/blocked` label	Yes
CI green	`mergeStateStatus == "CLEAN"` or all checks passed	Yes
No outstanding reviews	`reviewDecision != "CHANGES_REQUESTED"`	Yes
Mergeable	`mergeable == "MERGEABLE"`	Yes

Step 2 — Review Pending Comments

Fetch open review comments to check for unresolved threads:

gh api "repos/$REPO/pulls/$PR_NUMBER/comments" \
  --jq '[.[] | select(.user.login != "github-actions[bot]")] | length'

If there are unresolved comments and require_human_review_for patterns match files in this PR's diff, note them in the report but do NOT block the merge (they were already processed by /review-pr).

Step 3 — Decide: Merge or Report

If `human_merge_required = true`

Do NOT merge. Label the PR and report:

gh pr edit $PR_NUMBER --repo $REPO --add-label "human/review-merge"

PR #$PR_NUMBER is ready to merge.

  Title:  $TITLE
  Branch: $BRANCH → $BASE
  CI:     All checks passed
  Labels: human/review-merge applied

Merge when ready:
  gh pr merge $PR_NUMBER --repo $REPO --squash --delete-branch

If `human_merge_required = false` (auto-merge enabled)

Merge immediately:

gh pr merge $PR_NUMBER \
  --repo $REPO \
  --squash \
  --delete-branch \
  --subject "$PR_TITLE" \
  --body "Closes #$ISSUE_NUMBER"

Report:

Merged PR #$PR_NUMBER: $TITLE
  Merged as: squash commit
  Branch deleted: $BRANCH
  Issue closed: #$ISSUE_NUMBER (if referenced in PR body)

Clean up the local worktree if it still exists:

WORKTREE_PATH=".worktrees/issue-${ISSUE_NUMBER}-${SLUG}"
if git worktree list | grep -q "$WORKTREE_PATH"; then
  git worktree remove "$WORKTREE_PATH"
fi

Step 4 — Blocking Report (if any gate failed)

If any gate fails, report clearly what's blocking and what action is needed:

PR #$PR_NUMBER cannot be merged yet.

  Blocking:
    - CI: 2 checks failing
        test (ubuntu-latest): FAILURE — https://...
    - Review: 1 CHANGES_REQUESTED review pending

  Next steps:
    1. Fix failing tests — run /review-pr $PR_NUMBER to process the feedback
    2. Address CHANGES_REQUESTED from @reviewer
    3. Re-run /merge-pr $PR_NUMBER when resolved

Label with human/blocked if the blockage requires human judgment:

gh pr edit $PR_NUMBER --repo $REPO --add-label "human/blocked"

Guardrails

Never merge a PR with failing CI
Never merge if human_merge_required = true — only label
Never force-merge or bypass required reviews
Never delete the base branch
If merge fails due to conflict: report the conflict, do not attempt to resolve it automatically

merge-pr

Merge PR — Final Check and Merge

Input

Step 0 — Read Configuration