Execute GitHub operations (PRs, issues, milestones, labels, comments, merges) using Python scripts with structured output and error handling. Use when working with pull requests, issues, review comments, CI checks, or milestones instead of raw gh.
Use these scripts instead of raw gh commands for consistent error handling and structured output.
| Phrase | Operation |
|--------|-----------|
| create a PR | new_pr.py |
| respond to review comments | post_pr_comment_reply.py |
| check CI status | get_pr_checks.py / get_pr_check_logs.py |
| close issue | close_issue.py |
| add label to issue | set_issue_labels.py |
gh can be installed, hold a token, and still be refused for a whole session
(agent sandboxes that proxy egress do this). Decide the transport once, before
the first GitHub call:
# CLAUDE_PLUGIN_ROOT is set in a vendored install; falls back to .claude in-repo.
SCRIPTS_DIR="${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/utils"
python3 "$SCRIPTS_DIR/check_github_transport.py"
Non-POSIX hosts do not run the block above. The authoritative, per-harness
launcher for this one command is check_transport in the scripts map of
pr-review-config.yaml: the copilot entry runs it under PowerShell and
resolves the interpreter (python3, then py -3, then python), because a
Windows host may expose only the launcher. Read it from the map for the harness
you are on rather than transcribing a second copy here, which would drift.
Transport: gh (exit 0). Use the scripts below. This is CI and a normal
developer machine.Transport: gh_unusable (exit 0). gh cannot reach GitHub here. Route the
work through the GitHub MCP operations and do not re-try the scripts to
confirm. The verdict names only what was measured: confirm the operations you
need are exposed before relying on them. Tool spelling differs by harness
(mcp__github__<op> in Claude Code, github/<op> in Copilot CLI).Script-to-tool mapping, the operations with no MCP equivalent, and the rules
for reporting one: references/transport-routing.md.
A transport failure is an unknown, never a verdict. Do not report a PR as blocked, red, or unmergeable because the API was unreachable.
Which transport? → check_github_transport.py (run once, before the rest)
Need GitHub data?
├─ List PRs (filtered) → get_pull_requests.py
├─ PR info/diff → get_pr_context.py
├─ CI check status → get_pr_checks.py
├─ Failing check also red on main? → triage_red_check.py
├─ CI failure logs → get_pr_check_logs.py
├─ Review comments → get_pr_review_comments.py
├─ Review threads → get_pr_review_threads.py
├─ Review verdicts (approved / changes requested) → get_pr_reviews.py
├─ Unique reviewers → get_pr_reviewers.py
├─ Unaddressed bot comments → get_unaddressed_comments.py
├─ PR merged check → test_pr_merged.py
├─ Copilot follow-up PRs → detect_copilot_followup_pr.py
├─ Validate PR description → validate_pr_description.py
├─ Issue info → get_issue_context.py
├─ Merge readiness check → test_pr_merge_ready.py
├─ PR reports blocked/dirty and cause is unclear → why_pr_blocked.py
├─ Latest milestone → get_latest_semantic_milestone.py
├─ Actionable backlog → get_actionable_items.py
└─ Need to take action?
├─ Create issue → new_issue.py
├─ Create PR → new_pr.py
├─ Reply to review → post_pr_comment_reply.py
├─ Reply to thread (GraphQL) → add_pr_review_thread_reply.py
├─ Comment on issue → post_issue_comment.py
├─ Add reaction → add_comment_reaction.py
├─ Apply labels → set_issue_labels.py
├─ Set issue milestone → set_issue_milestone.py
├─ Set PR/issue milestone (auto-detect) → set_item_milestone.py
├─ Assign issue → set_issue_assignee.py
├─ Resolve threads → resolve_pr_review_thread.py
├─ Unresolve threads → unresolve_pr_review_thread.py
├─ Process AI triage → invoke_pr_comment_processing.py
├─ Assign Copilot → invoke_copilot_assignment.py
├─ Enable/disable auto-merge → set_pr_auto_merge.py
├─ Close PR → close_pr.py
└─ Merge PR → merge_pr.py
In a network-restricted sandbox (triage, PR status checks), run read-only PR
scripts under scripts/pr/ with bare python3, not uv run.
uv run <script> resolves the whole project environment first, which downloads
anthropic==0.116.0 (a core dependency in pyproject.toml) from PyPI and times
out with no network. The read-only PR scripts never import the anthropic SDK.
They import only github_core, which parses YAML with a vendored fallback when
PyYAML is absent (issue #1844), so no third-party import is required.
# No PyPI round trip. Runs read-only PR status offline.
# CLAUDE_PLUGIN_ROOT is set in a vendored install; falls back to .claude in-repo.
SCRIPTS_DIR="${COPILOT_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-.claude}}/skills/github/scripts/pr"
python3 "$SCRIPTS_DIR/get_pull_requests.py" --state open
python3 "$SCRIPTS_DIR/get_pr_context.py" --pr <N>
python3 "$SCRIPTS_DIR/get_pr_checks.py" --pr <N>
Any python3 works: github_core falls back to a vendored YAML parser when
PyYAML is absent (issue #1844), confirmed by running these scripts with both
PyYAML and the anthropic SDK blocked. The interpreter from
scripts/bootstrap-vm.sh and a project .venv/bin/python3 both ship PyYAML for
the faster path. Do not use uv run for read-only triage offline; it forces the
resolve that fetches anthropic.
The regression guard tests/test_pr_scripts_offline.py asserts the read-only PR
scripts and github_core import with the anthropic SDK blocked.
scripts/pr/)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| get_pull_requests.py | List PRs with filters | --state, --label, --author, --base, --head, --search, --limit |
| get_pr_context.py | PR metadata, diff, files | --pull-request, --include-changed-files, --include-diff |
| get_pr_checks.py | CI check status, polling | --pull-request, --wait, --timeout-seconds, --required-only, --output-format {json,human,auto} |
| get_pr_check_logs.py | Fetch logs from failing CI checks | --pull-request, --max-lines, --context-lines |
| triage_red_check.py | CI-failure triage step 1: is a failing PR check also red on main's latest run? Exit 0 green on main, exit 1 red on main (EvidenceUrl cites the main run), exit 3 cannot determine (never reported as green) | --check-name, --branch, --history-depth, --pull-request |
| get_pr_review_comments.py | Paginated review comments with stale detection | --pull-request, --include-issue-comments, --detect-stale, --exclude-stale, --only-stale |
| get_pr_review_threads.py | Thread-level review data | --pull-request, --unresolved-only |
| get_pr_reviews.py | Review submissions (verdict state and body) | --pull-request, --state, --output-format {json,human,auto} |
| get_pr_reviewers.py | Enumerate unique reviewers | --pull-request, --exclude-bots |
| get_unaddressed_comments.py | Bot comments needing attention | --pull-request |
| get_unresolved_review_threads.py | Unresolved thread IDs | --pull-request |
| wait_for_unresolved_zero.py | Settling gate: poll until unresolved count holds at zero across bot scans | --pull-request, --interval-seconds, --max-wait-seconds, --strict-pagination |
| test_pr_merged.py | Check if PR is merged | --pull-request |
| detect_copilot_followup_pr.py | Detect Copilot follow-up PRs | --pr-number, --owner, --repo |
| post_pr_comment_reply.py | Thread-preserving replies | --pull-request, --comment-id, --body |
| add_pr_review_thread_reply.py | Reply to thread by ID (GraphQL) | --pull-request, --thread-id, --body, --resolve |
| resolve_pr_review_thread.py | Mark threads resolved | --thread-id --expected-pull-request or --pull-request --all |
| unresolve_pr_review_thread.py | Mark threads unresolved | --thread-id or --pull-request --all |
| get_thread_by_id.py | Get single thread by ID | --thread-id |
| get_thread_conversation_history.py | Full thread comment history | --thread-id, --include-minimized |
| test_pr_merge_ready.py | Check merge readiness | --pull-request, --ignore-ci, --ignore-threads |
| why_pr_blocked.py | Diagnose a mergeable_state/mergeStateStatus: blocked PR: decomposes it into missing/failing/pending required checks, unresolved review threads, or merge conflicts, and says explicitly when none of those hold (the field can be stale) | --pull-request, --base-branch, --output-format {json,human,auto} |
| set_pr_auto_merge.py | Enable/disable auto-merge | --pull-request, --enable/--disable, --merge-method |
| invoke_pr_comment_processing.py | Process AI triage output | --pr-number, --verdict, --findings-json |
| new_pr.py | Create PR with validation | --title, --body, --base |
| validate_pr_description.py | Validate PR description | --title, --body, --body-file, --fail-on-violation |
| close_pr.py | Close PR with comment | --pull-request, --comment |
| merge_pr.py | Merge with strategy | --pull-request, --strategy, --delete-branch, --auto |
| audit_closing_claims.py | Fleet audit of open-PR closing claims: extracts closing keywords from PR bodies, commit messages, and auto-merge overrides; classifies Markdown context (body) and plain-text context (commits/overrides); flags a claim unsupported when it can reach the eventual squash commit without a matching active body claim (exit 1). Needs a token with administration read: reachability depends on the repository's squash_merge_commit_message setting, which GitHub omits for anyone else, and the audit exits 3 rather than reporting a clean fleet it cannot verify | --state open, --artifact, --resume-from, --output-format {json,human,auto} |
| edit_pr_body.py | Edit a PR body with a SHA-256 stale-write guard | --pull-request, --body/--body-file, --expected-hash, --dry-run |
scripts/issue/)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| get_issue_context.py | Issue metadata (no comments) | --issue |
| get_issue_comments.py | Issue comment thread (discourse) | --issue, --limit |
| new_issue.py | Create new issue | --title, --body, --labels |
| close_issue.py | Close with optional comment (--verify-claims aborts on a cited commit/PR the remote disproves, exit 1, and separately on one it could not check, exit 3 or 4) | --issue, --reason, --comment, --verify-claims |
| reopen_issue.py | Reopen with optional comment | --issue, --comment |
| set_issue_labels.py | Apply labels (auto-create) | --issue, --labels, --priority |
| set_issue_milestone.py | Assign milestone | --issue, --milestone |
| post_issue_comment.py | Comments with idempotency | --issue, --body, --marker |
| invoke_copilot_assignment.py | Synthesize context for Copilot | --issue-number, --what-if |
| set_issue_assignee.py | Assign users to issues | --issue, --assignees |
scripts/milestone/)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| get_latest_semantic_milestone.py | Detect latest semantic version milestone | --owner, --repo |
| set_item_milestone.py | Assign milestone to PR/issue (auto-detect) | --item-type, --item-number, --milestone-title |
repo/ scripts)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| manage_squash_merge_message.py | Read or update the squash_merge_commit_message repository setting with an expected-current-value guard; reports a real before/after re-read. Needs a token with administration read: GitHub omits merge settings for anyone else, and the script exits 3 rather than assuming a value | --set, --expected-current, --dry-run, --output-format {json,human,auto} |
scripts/reactions/)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| add_comment_reaction.py | Add emoji reactions (batch support) | --comment-id, --reaction, --comment-type, --pull-request |
scripts/notifications/)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| get_actionable_items.py | List actionable backlog (reviews, authored PRs, assigned issues) | --owner, --repo, --limit |
scripts/utils/)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| extract_github_context.py | Extract issue/PR references from text | --text, --require-pr, --require-issue |
| check_github_transport.py | Report whether this session should use gh or the MCP tools | --output-format |
scripts/)| Script | Purpose | Key Parameters |
|--------|---------|----------------|
| test_workflow_locally.py | Test GitHub Actions locally with act | --workflow, --event, --job, --dry-run |
All scripts output structured JSON wrapped in a standard envelope per ADR-051.
Success envelope:
{
"Success": true,
"Data": { "Number": 42, "Title": "..." },
"Error": null,
"Metadata": { "Script": "get_pr_checks.py", "Version": "1.0.0", "Timestamp": "..." }
}
Error envelope:
{
"Success": false,
"Data": null,
"Error": { "Message": "PR not found", "Code": 2, "Type": "NotFound" },
"Metadata": { "Script": "get_pr_checks.py", "Version": "1.0.0", "Timestamp": "..." }
}
Usage:
SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT:-.claude}/skills/github/scripts"
result=$(python3 "$SCRIPTS_DIR/pr/get_pr_context.py" --pull-request 50)
echo "$result" | jq '.Data'
Exit codes follow ADR-035: 0=success, 1=logic error, 2=config error, 3=external failure, 4=auth error.
This skill provides a toolkit of Python scripts for GitHub operations. Use scripts directly or compose them into workflows.
Basic Usage:
Example Flow:
SCRIPTS_DIR="${CLAUDE_PLUGIN_ROOT:-.claude}/skills/github/scripts"
# Get PR context
python3 "$SCRIPTS_DIR/pr/get_pr_context.py" --pull-request 123
# Check CI status
python3 "$SCRIPTS_DIR/pr/get_pr_checks.py" --pull-request 123
# Add comment if needed
python3 "$SCRIPTS_DIR/pr/post_pr_comment_reply.py" --pull-request 123 --comment-id 456 --body "CI failures detected"
GitHub automatically links and closes issues when PRs use specific keywords in PR descriptions, commit messages, or PR comments.
| Keyword | Variations | Example |
|---------|-----------|---------|
| Closes | close, closed | Closes #123 |
| Fixes | fix, fixed | Fixes #456 |
| Resolves | resolve, resolved | Resolves #789 |
In PR Descriptions:
## Summary
This PR adds feature X.
Closes #123
Fixes #456
In Commit Messages:
feat: Add feature X
Implements the new feature as specified.
Closes #123
Best Practices:
| Avoid | Why | Instead |
|-------|-----|---------|
| Raw gh pr view commands | No structured output | Use get_pr_context.py |
| Raw gh api for comments | Doesn't preserve threading | Use post_pr_comment_reply.py |
| Replying to thread expecting auto-resolve | Replies DON'T auto-resolve threads | Use resolve_pr_review_thread.py after reply |
| Inline issue creation | Missing validation | Use new_issue.py |
| Multiple individual reactions | 88% slower | Use batch mode in add_comment_reaction.py |
| Hardcoding owner/repo | Breaks in forks | Let scripts infer from git remote |
| Ignoring exit codes | Missing error handling | Check exit codes per ADR-035 |
| Skipping idempotency markers | Duplicate comments | Use --marker parameter |
| Raw gh notify or notifications API | 403 with app tokens | Use get_actionable_items.py |
| Retrying gh after a session refusal | The refusal has no reset; retries only burn the budget | Run the transport preflight, then use the GitHub MCP operations |
| Reporting a PR blocked because a call failed | An unreachable API is an unknown, not a verdict | Name the transport failure as the cause |
| Treating mergeable_state/mergeStateStatus: blocked as self-explanatory (e.g. guessing "pending approval" without checking) | It is a cached, frequently-stale field. why_pr_blocked.py decomposes it into required checks, review threads, and merge conflicts, but does not query reviewDecision or the required-approving-review count, so a repo that requires approvals can still be blocked on that even when the script reports no cause | Run why_pr_blocked.py first. GitHub's "A conversation must be resolved before this pull request can be merged" message means unresolved review threads: resolve them (resolve_pr_review_thread.py). If the script reports no cause but the PR is still blocked, also check get_pr_context.py's review_decision field against the target branch's required-approving-review count before reporting nothing to act on |
| Document | Content |
|----------|---------|
| examples.md | Complete script examples |
| patterns.md | Reusable workflow patterns |
| copilot-prompts.md | Creating @copilot directives |
| copilot-synthesis-guide.md | Copilot context synthesis |
| api-reference.md | Exit codes, API endpoints, troubleshooting |
| transport-routing.md | Picking gh or the MCP tools, and the script-to-tool map |
| scripts/github_core/ | Shared Python helper functions |
Before completing a GitHub operation:
Search for places (restaurants, cafes, etc.) via Google Places API proxy on localhost.
Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Start voice calls via the OpenClaw voice-call plugin.
Notion API for creating and managing pages, databases, and blocks.
Gemini CLI for one-shot Q&A, summaries, and generation.
Category:developer