{
  "slug": "gh-programmatic-pull-request-merging-with-the-async-merge-api-6aa0f446ea95",
  "title": "gh programmatic pull request merging with the async merge API",
  "tools": [
    "gh"
  ],
  "tags": [
    "agent"
  ],
  "introduced_at": "2026-10-01T14:00:51.000Z",
  "announced_at": "2026-10-01T14:00:51.000Z",
  "effective_at": null,
  "date_basis": "source-publication",
  "status": "unknown",
  "how": {
    "incantation": "For individual or stacked PRs, submit a merge request with `PUT`; poll the result with `GET` using the returned UUID. Set `merge_action` for direct or queued merges, and set `bypass_rules` only when authorized.",
    "examples": [
      "curl -L -X PUT -H \"Accept: application/vnd.github+json\" -H \"Authorization: Bearer <TOKEN>\" -H \"X-GitHub-Api-Version: 2026-03-10\" \"https://api.github.com/repos/<OWNER>/<REPO>/pulls/<PULL_NUMBER>/merge-async\" -d '{\"merge_action\":\"default\"}'",
      "curl -L -H \"Accept: application/vnd.github+json\" -H \"Authorization: Bearer <TOKEN>\" -H \"X-GitHub-Api-Version: 2026-03-10\" \"https://api.github.com/repos/<OWNER>/<REPO>/pulls/<PULL_NUMBER>/merge-async/<UUID>\""
    ],
    "gotchas": [
      "Availability: generally available",
      "owner (required): Repository account owner.",
      "repo (required): Repository name without `.git`.",
      "pull_number (required): Pull request number.",
      "merge_action: `default` uses a queue if configured or merges directly; `direct_merge` skips the queue; `merge_queue` adds to a queue. Allowed values are mutually exclusive; omission defaults to `default`.",
      "merge_method: Direct merge method: `merge`, `squash`, or `rebase`; only for direct merges. Values are mutually exclusive.",
      "commit_title: Automatic commit title; only for direct merges.",
      "commit_message: Extra detail in automatic commit message; only for direct merges.",
      "sha: Expected PR head SHA; if omitted, current head is used and a later push before execution cancels the merge.",
      "bypass_rules: Bypass repository rules the authenticated actor may bypass; defaults to `false`.",
      "uuid (required): UUID returned by the merge request; identifies the result to fetch.",
      "Prerequisite: Fine-grained tokens must have `Contents` repository permission (write). Supported token types include GitHub App user and installation tokens, and fine-grained personal access tokens.",
      "Prerequisite: The async result endpoint also requires `Contents` repository permission (write) for fine-grained tokens.",
      "Bypassing rules requires permission."
    ]
  },
  "why_it_matters": "Programmatically merge individual or stacked pull requests, add pull requests to a merge queue, or merge pull requests directly in a busy repository.",
  "before": "Use the synchronous REST endpoint or GraphQL mutations to merge pull requests.",
  "sources": [
    "https://github.blog/changelog/2026-10-01-github-async-merge-api-generally-available",
    "https://docs.github.com/en/rest/pulls/pulls?apiVersion=2026-03-10#merge-a-pull-request-asynchronously",
    "https://docs.github.com/en/rest/pulls/pulls?apiVersion=2026-03-10#get-the-result-of-an-asynchronous-merge"
  ],
  "rank": 0.96049,
  "judge": {
    "publish": true,
    "judge_model": "codex-cli/gpt-6-luna+typesafe/jev-1.13.0",
    "prompt_version": "extract-v7+enrich-v1+judge-v2x3-rejudge+jev-publish-v1"
  },
  "review_state": "approved",
  "provenance": {
    "run_id": "recover-20261008",
    "verdict_id": "recover-20261008:recover-20261008-2a140c2fb3211d8e-0:rescue",
    "evidence_hash": "2ebaf7473920a0fe46f26001692a3f908b13ec92947262ed456d6154a739734c"
  },
  "review": {
    "draft_hash": "7e2ac53cfeb56f5572b3254a89a4cebb7f533bfc9b7a63d46daa55ee22ce8cac",
    "reviewer": "publication-gate",
    "reviewed_at": "2026-10-07T00:00:00.000Z",
    "decision": "recover-20261008:rescue",
    "reason": "Rescue path: first rejected only because the extracted card lacked usage; judged again on the enriched card, 3 of 3 judge runs approved with p_yes >= 0.9 (mean 0.96 >= 0.9; 2 needed) and Jev gave 0.68 (>= 0.6 needed)."
  }
}