Github

GitHub Skill

Use these scripts instead of raw gh commands for consistent error handling and structured output.

Triggers

Transport Preflight

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).
• Exit 3 or 4. Not a transport problem: a quota window or a fixable token.

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.

Decision Tree

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

Offline Invocation

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 Operations (scripts/pr/)

Issue Operations (scripts/issue/)

Milestone Operations (scripts/milestone/)

Reactions (scripts/reactions/)

Notifications (scripts/notifications/)

Utilities (scripts/utils/)

Workflow Testing (scripts/)

Output Format

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.

Process

This skill provides a toolkit of Python scripts for GitHub operations. Use scripts directly or compose them into workflows.

Basic Usage:

1. Identify the operation needed using the Decision Tree
2. Find the corresponding script in the Script Reference
3. Call the script with required parameters
4. Parse the JSON output

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 Keywords for Issue Linking

GitHub automatically links and closes issues when PRs use specific keywords in PR descriptions, commit messages, or PR comments.

Supported Keywords

Usage Patterns

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:

• Use keywords in PR description for primary issue
• Use keywords in commit bodies for related issues
• One keyword per line for clarity
• Place keywords in dedicated section or at end of description

Anti-Patterns

See Also

Verification

Before completing a GitHub operation:

• Correct script selected from Decision Tree
• Required parameters provided (PR/issue number)
• Response JSON parsed successfully
• Exit code is 0 (success)
• State change verified (for mutating operations)