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/