github

GitHub Skill

Use the gh CLI to interact with GitHub. Always pass --repo owner/repo when not inside a cloned git directory.

Pull Requests

List open PRs:

gh pr list --repo owner/repo

View a specific PR (summary, checks, comments):

gh pr view 55 --repo owner/repo

Check CI status on a PR:

gh pr checks 55 --repo owner/repo

CI / Workflow Runs

List recent runs:

gh run list --repo owner/repo --limit 10

View a run summary (steps, status):

gh run view <run-id> --repo owner/repo

View logs for failed steps only:

gh run view <run-id> --repo owner/repo --log-failed

Re-run failed jobs:

gh run rerun <run-id> --repo owner/repo --failed

Issues

List open issues (optionally filter by label):

gh issue list --repo owner/repo
gh issue list --repo owner/repo --label bug

View a specific issue:

gh issue view 42 --repo owner/repo

Create an issue:

gh issue create --repo owner/repo --title "Title" --body "Description" --label bug

JSON Output & Filtering

Most commands support --json with --jq for structured output:

# List PR numbers and titles
gh pr list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'

# List issues with assignees
gh issue list --repo owner/repo --json number,title,assignees \
  --jq '.[] | "\(.number): \(.title) → \(.assignees[].login // "unassigned")"'

Advanced: gh api

Use gh api for data or actions not covered by other subcommands.

Fetch a PR with specific fields:

gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'

List check runs for a commit:

gh api repos/owner/repo/commits/<sha>/check-runs \
  --jq '.check_runs[] | "\(.name): \(.conclusion)"'

Paginate results (e.g., all issues):

gh api --paginate repos/owner/repo/issues --jq '.[].title'

Steps

1. Check if gh is installed by running gh --version.
   • If the command is not found, install it (see Installation below).
2. Check if gh is authenticated by running gh auth status.
   • If not authenticated, run gh auth login.
3. If owner/repo is not provided, check if there is a .git directory and infer the remote via gh repo view --json nameWithOwner. Otherwise ask the user for the repo.
4. Choose the appropriate subcommand (pr, issue, run, api) based on the user's request.
5. Prefer structured subcommands (gh pr, gh issue, gh run) over raw gh api when they cover the use case.
6. Use --json + --jq when the user needs specific fields or wants to pipe output into further processing.
7. If a workflow run is failing, start with gh pr checks for a quick overview, then gh run view --log-failed for detailed output.
8. Report results clearly; if output is large, summarize and highlight the relevant parts.