Auto-merge

Auto-merge lets a blocked pull request wait for its base’s protection to be met, then merges it. Turn auto-merge on for a blocked pull request and meet its requirements to watch it land:

H='Authorization: Bearer ghp_anything'
R="$RYSTIC_URL/repos/tb-owner/tb-repo"
curl -s "$RYSTIC_URL/_rystic/inspect" | jq '{state_repository: {"tb-owner/tb-repo": (.state_repository["tb-owner/tb-repo"] | .allow_auto_merge = true)}}' > "$PWD/allow-auto-merge.json"
curl -s -X POST "$RYSTIC_URL/_rystic/seed" -d @"$PWD/allow-auto-merge.json" -o /dev/null -w '%{http_code}\n'
# -> 204
curl -s -X PUT "$R/branches/tb-base-branch/protection" -H "$H" -d '{"required_status_checks":{"strict":false,"contexts":["unit"]},"enforce_admins":false,"required_pull_request_reviews":{"required_approving_review_count":1},"restrictions":null}' -o /dev/null -w '%{http_code}\n'
# -> 200
curl -s -X POST "$RYSTIC_URL/graphql" -H "$H" -d '{"query":"mutation { enablePullRequestAutoMerge(input: {pullRequestId: \"tb-pr-41-node-id\", mergeMethod: SQUASH}) { pullRequest { number autoMergeRequest { mergeMethod enabledBy { login } } } } }"}' | jq -c '.data.enablePullRequestAutoMerge.pullRequest.autoMergeRequest'
# -> {"enabledBy":{"login":"tb-owner"},"mergeMethod":"SQUASH"}
curl -s "$R/pulls/41" -H "$H" | jq -c '{state, merged, auto_merge: (.auto_merge | {merge_method, enabled_by: .enabled_by.login})}'
# -> {"state":"open","merged":false,"auto_merge":{"merge_method":"squash","enabled_by":"tb-owner"}}
curl -s -X POST "$R/statuses/517a4bbdfb525691b11db3e28f466eb3d7598d19" -H "$H" -d '{"state":"success","context":"unit"}' -o /dev/null -w '%{http_code}\n'
# -> 201
curl -s -X POST "$R/pulls/41/reviews" -H "$H" -H 'X-Rystic-Actor: tb-reviewer-login' -d '{"event":"APPROVE"}' | jq -c '{state}'
# -> {"state":"APPROVED"}
curl -s "$R/pulls/41" -H "$H" | jq -c '{state, merged, merged_by: .merged_by.login}'
# -> {"state":"closed","merged":true,"merged_by":"tb-owner"}
curl -s "$R/issues/41/events" -H "$H" | jq -c '[.[].event]'
# -> ["auto_merge_enabled","merged","closed"]

“Unconfirmed” marks behavior not yet checked against GitHub. Into a base that holds a merge queue, auto-merge joins the queue instead: see Merge queues.

Enabling auto-merge

gh pr merge --auto on a blocked pull request sends enablePullRequestAutoMerge. The simulator records the request as the pull request’s auto_merge, which GraphQL reads as autoMergeRequest. Enabling it logs auto_merge_enabled and sends the pull_request auto_merge_enabled webhook.

The repository must allow auto-merge (allow_auto_merge) unless the base holds a merge queue. Every authored scenario seeds it off. Off a queue base, a pull request reading anything but blocked, behind or unknown is refused Pull request is in <mergeable_state> status. A draft is refused Pull request is in draft status.

Enabling auto-merge with a merge method the repository or a ruleset doesn’t allow is accepted (unconfirmed). Off a merge queue, such a request never lands while the method stays disallowed.

When auto-merge lands

The simulator lands an auto-merge request on the enabler’s behalf as soon as the base’s protection is met. It checks again after each status, check run, protection or ruleset write, and after submitting or dismissing a review. It also checks after creating a review comment through POST .../pulls/{n}/comments or deleting one. A push, an update-branch, a reopen or a base change makes it check too. It merges through the merge route with the recorded method:

• The pull request reads merged, with the enabler as merged_by.
• Its log gains merged and closed.
• The pull_request closed webhook goes out.
• auto_merge stays on the merged record.

After a push to the head, a request the new head’s results meet lands after the push’s own synchronize.

A request stays on a pull request that closes (unconfirmed). A reopen that finds the base’s protection met lands it after the reopened event.

Disabling auto-merge

gh pr merge --disable-auto sends disablePullRequestAutoMerge, which clears the request, logs auto_merge_disabled and sends auto_merge_disabled. With no request standing it changes nothing. On a closed pull request it is refused Can't disable auto-merge for this pull request..