GitHub PR Merge Operations
Overview
Merge pull requests, check merge status, verify readiness, and configure auto-merge via the GitHub GraphQL API. Always use GraphQL (not gh pr view --json state) as the authoritative merge state source.
Prerequisites
- GitHub CLI (
gh) installed and authenticated
- Python 3.8+ for automation scripts
- Repository write access for merge operations
- GraphQL API access (included with standard GitHub auth)
Instructions
- Check if the PR is already merged:
amia_test_pr_merged.py --pr <N> --repo <owner/repo>
- Verify merge readiness:
amia_test_pr_merge_ready.py --pr <N> --repo <owner/repo>
- Resolve any blockers indicated by exit codes (CI, conflicts, reviews, threads)
- Execute merge:
amia_merge_pr.py --pr <N> --repo <owner/repo> --strategy <merge|squash|rebase>
- Or enable auto-merge:
amia_set_auto_merge.py --pr <N> --repo <owner/repo> --enable --merge-method <MERGE|SQUASH|REBASE>
- Verify completion:
amia_test_pr_merged.py --pr <N> --repo <owner/repo>
Checklist
Copy this checklist and track your progress:
Output
| Output Type |
Format |
Key Fields |
| Merge status |
JSON |
merged (bool), state (OPEN/CLOSED/MERGED) |
| Readiness check |
JSON |
ready (bool), merge_state, blocking reasons |
| Merge result |
JSON |
success (bool), merged_at, sha |
| Auto-merge |
JSON |
auto_merge_enabled (bool), merge_method |
Exit codes: 0=success, 1=invalid params, 2=not found, 3=API error, 4=auth, 5=already merged, 6=not mergeable.
Output discipline: All scripts support --output-file <path>.
Error Handling
On failure, check exit code and stderr. Exit 1 = invalid params; Exit 2-4 = API errors. See the detailed guide in Resources.
Resources
- detailed-guide — Full reference
- Table of Contents
- GraphQL is the Source of Truth
- Decision Tree for PR Merge Operations
- Script Usage Details
- Common Workflows
- Exit Codes Reference
- Error Handling
- Safety Warning: Destructive Operations
- Script Locations
- Reference Documents Index
Examples
Example 1: Standard PR Merge
python scripts/amia_test_pr_merged.py --pr 123 --repo owner/repo
# {"merged": false, "state": "OPEN"} -> continue
python scripts/amia_test_pr_merge_ready.py --pr 123 --repo owner/repo
# {"ready": true, "merge_state": "MERGEABLE"} -> ready
python scripts/amia_merge_pr.py --pr 123 --repo owner/repo --strategy squash --delete-branch
# {"success": true, "merged_at": "2025-01-30T10:00:00Z"}
1---2name: amia-github-pr-merge3description: Use when merging pull requests, checking merge status, or configuring auto-merge. Trigger with merge, auto-merge, or readiness verification requests. Loaded by ai-maestro-integrator-agent-main-agent.4license: MIT5---67# GitHub PR Merge Operations89## Overview1011Merge pull requests, check merge status, verify readiness, and configure auto-merge via the GitHub GraphQL API. Always use GraphQL (not `gh pr view --json state`) as the authoritative merge state source.1213## Prerequisites1415- GitHub CLI (`gh`) installed and authenticated16- Python 3.8+ for automation scripts17- Repository write access for merge operations18- GraphQL API access (included with standard GitHub auth)1920## Instructions21221. Check if the PR is already merged: `amia_test_pr_merged.py --pr <N> --repo <owner/repo>`232. Verify merge readiness: `amia_test_pr_merge_ready.py --pr <N> --repo <owner/repo>`243. Resolve any blockers indicated by exit codes (CI, conflicts, reviews, threads)254. Execute merge: `amia_merge_pr.py --pr <N> --repo <owner/repo> --strategy <merge|squash|rebase>`265. Or enable auto-merge: `amia_set_auto_merge.py --pr <N> --repo <owner/repo> --enable --merge-method <MERGE|SQUASH|REBASE>`276. Verify completion: `amia_test_pr_merged.py --pr <N> --repo <owner/repo>`2829### Checklist3031Copy this checklist and track your progress:3233- [ ] Verify governance authorization via `team-governance` skill34- [ ] Check if PR is already merged (exit 5 = already merged)35- [ ] Verify merge readiness (exit 0 = ready)36- [ ] Resolve blocking conditions (CI, conflicts, reviews, threads)37- [ ] Select merge strategy (merge/squash/rebase)38- [ ] Execute merge or enable auto-merge39- [ ] Verify merge completion40- [ ] Handle errors based on exit codes4142## Output4344| Output Type | Format | Key Fields |45|-------------|--------|------------|46| Merge status | JSON | `merged` (bool), `state` (OPEN/CLOSED/MERGED) |47| Readiness check | JSON | `ready` (bool), `merge_state`, blocking reasons |48| Merge result | JSON | `success` (bool), `merged_at`, `sha` |49| Auto-merge | JSON | `auto_merge_enabled` (bool), `merge_method` |5051Exit codes: 0=success, 1=invalid params, 2=not found, 3=API error, 4=auth, 5=already merged, 6=not mergeable.5253> **Output discipline:** All scripts support `--output-file <path>`.5455## Error Handling5657On failure, check exit code and stderr. Exit 1 = invalid params; Exit 2-4 = API errors. See the detailed guide in Resources.5859## Resources6061- [detailed-guide](references/detailed-guide.md) — Full reference62 - Table of Contents63 - GraphQL is the Source of Truth64 - Decision Tree for PR Merge Operations65 - Script Usage Details66 - Common Workflows67 - Exit Codes Reference68 - Error Handling69 - Safety Warning: Destructive Operations70 - Script Locations71 - Reference Documents Index7273## Examples7475### Example 1: Standard PR Merge7677```bash78python scripts/amia_test_pr_merged.py --pr 123 --repo owner/repo79# {"merged": false, "state": "OPEN"} -> continue8081python scripts/amia_test_pr_merge_ready.py --pr 123 --repo owner/repo82# {"ready": true, "merge_state": "MERGEABLE"} -> ready8384python scripts/amia_merge_pr.py --pr 123 --repo owner/repo --strategy squash --delete-branch85# {"success": true, "merged_at": "2025-01-30T10:00:00Z"}86```
Emasoft