GitHub API Access

Access GitHub's API in sandboxed environment using GitHub CLI binary.

Core principle: Use existing gh if available (global or /tmp), install only if needed.

Environment: Requires GITHUB_TOKEN environment variable.

When to Use

PR status/reviews, workflow runs/logs, issues, repository info, Actions data, artifacts, remote file contents.

Quick Setup

Check for gh and set alias:

if command -v gh &> /dev/null; then
  GH="gh"
elif [ -f "/tmp/gh-install/gh_2.62.0_linux_amd64/bin/gh" ]; then
  GH="/tmp/gh-install/gh_2.62.0_linux_amd64/bin/gh"
else
  echo "gh not found. See INSTALL.md for installation instructions"
  exit 1
fi
$GH --version
$GH auth status

If gh not found: See INSTALL.md for installation instructions.

Essential Commands

After setup, use $GH alias:

$GH pr list --repo OWNER/REPO
$GH pr view <NUM> --repo OWNER/REPO
$GH pr checks <NUM> --repo OWNER/REPO
$GH issue list --repo OWNER/REPO
$GH run list --repo OWNER/REPO --status failure
$GH run view <RUN_ID> --repo OWNER/REPO
$GH api repos/OWNER/REPO/actions/runs/<RUN_ID>/jobs --jq '.jobs[] | select(.conclusion=="failure")'
$GH api repos/OWNER/REPO/actions/runs/<RUN_ID>/logs --paginate > /tmp/logs.zip
$GH repo view OWNER/REPO --json name,description,url
$GH api repos/OWNER/REPO/contents/path/to/file --jq -r '.content' | base64 -d
$GH api rate_limit

Critical Constraints

Works: Binary install to /tmp, GITHUB_TOKEN auth, full path commands, file downloads, jq parsing, all REST endpoints

Doesn't work: gh without full path, export env vars, interactive commands, git credential helper

Rate limits: Authenticated 5000/hr, unauthenticated 60/hr

Token must pre-exist as GITHUB_TOKEN - cannot be set in session.

Reference Documentation

Detailed guides in skill directory:

• •reference/pull-requests.md - PR operations
• •reference/issues.md - Issue operations
• •reference/workflow-runs.md - CI/CD operations
• •reference/repository-info.md - Repository data
• •reference/raw-api-access.md - Direct REST API
• •reference/pagination.md - Pagination strategies
• •reference/searching.md - Search syntax
• •reference/jq-patterns.md - JSON parsing patterns
• •EXAMPLES.md - Real-world workflows
• •ENDPOINTS.md - Complete API endpoint reference

Token Permissions

Read-only: Contents, Pull requests, Actions, Issues (Read) Write ops: Add Write permissions for respective resources

Troubleshooting

• •"command not found" → Use full path /tmp/gh-install/gh_2.62.0_linux_amd64/bin/gh
• •"authentication failed" → printenv GITHUB_TOKEN | head -c 30
• •"rate limit exceeded" → $GH api rate_limit
• •"404 Not Found" → Verify OWNER/REPO format
• •"Empty response" → Add --paginate

Best Practices

1. •Always check for existing gh before installing (system-wide, then /tmp)
2. •Binary persists in /tmp for entire session if installed there
3. •Use GH alias variable in scripts
4. •Parse with --json and --jq for programmatic access
5. •Download files to /tmp to avoid permissions issues
6. •Test with small queries before bulk operations

Related Skills

starwards-ci-debugging, starwards-verification, starwards-workflow, using-superpowers

Docs: https://docs.github.com/en/rest | https://cli.github.com/manual/