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

• Always check for existing gh before installing (system-wide, then /tmp)

• Binary persists in /tmp for entire session if installed there

• Use GH alias variable in scripts

• Parse with --json and --jq for programmatic access

• Download files to /tmp to avoid permissions issues

• 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/