GitHub CLI (gh) Skill

This skill provides comprehensive guidance for using the GitHub CLI (gh) tool to retrieve and analyze information from GitHub repositories, pull requests, issues, and workflows.

Prerequisites

Ensure gh is installed and authenticated:

bash
1# Check if gh is installed
2gh --version
3
4# Authenticate with GitHub (if not already done)
5gh auth login
6
7# Check authentication status
8gh auth status

Repository Information

Viewing Repository Details

bash
1# View repository info
2gh repo view owner/repo
3
4# View repository README
5gh repo view owner/repo --web
6
7# Get repository metadata as JSON
8gh api repos/owner/repo
9
10# Get specific fields
11gh api repos/owner/repo --jq '.stargazers_count, .forks_count, .open_issues_count'
12
13# List repositories for an organization
14gh repo list orgname --limit 100
15
16# Search repositories
17gh search repos "language:go stars:>1000"

Repository Statistics

bash
1# Get contributor statistics
2gh api repos/owner/repo/contributors
3
4# Get commit activity
5gh api repos/owner/repo/stats/commit_activity
6
7# Get code frequency
8gh api repos/owner/repo/stats/code_frequency
9
10# Get language breakdown
11gh api repos/owner/repo/languages

Pull Request Analysis

Viewing PR Information

bash
1# List PRs with various filters
2gh pr list
3gh pr list --state all
4gh pr list --state merged --limit 100
5gh pr list --author username
6gh pr list --label "bug"
7gh pr list --search "fix memory leak"
8
9# View detailed PR info
10gh pr view 123
11gh pr view 123 --comments  # Include all comments
12gh pr view 123 --web       # Open in browser
13
14# Get PR data as JSON for analysis
15gh pr view 123 --json number,title,author,state,createdAt,closedAt,files
16
17# View PR diff
18gh pr diff 123
19gh pr diff 123 --patch  # Get as patch format

Analyzing PR Comments and Reviews

bash
1# Get all comments on a PR
2gh api repos/owner/repo/issues/123/comments
3
4# Get review comments (inline code comments)
5gh api repos/owner/repo/pulls/123/comments
6
7# Get PR reviews
8gh api repos/owner/repo/pulls/123/reviews
9
10# Get review comments with context
11gh api repos/owner/repo/pulls/123/comments --jq '.[] | {path: .path, line: .line, body: .body}'
12
13# Get conversation threads
14gh pr view 123 --json comments --jq '.comments[].body'

PR File Changes

bash
1# List files changed in a PR
2gh pr view 123 --json files --jq '.files[].path'
3
4# Get detailed file change info
5gh api repos/owner/repo/pulls/123/files
6
7# See additions/deletions per file
8gh api repos/owner/repo/pulls/123/files --jq '.[] | "\(.filename): +\(.additions) -\(.deletions)"'
9
10# Check if specific files were modified
11gh pr view 123 --json files --jq '.files[].path | select(test(".*\\.go$"))'

Issue Discovery and Analysis

Searching and Listing Issues

bash
1# List issues with filters
2gh issue list
3gh issue list --state all
4gh issue list --label "bug" --label "priority"
5gh issue list --assignee @me
6gh issue list --search "memory leak"
7gh issue list --milestone "v2.0"
8
9# Search issues across multiple repos
10gh search issues "org:myorg memory leak"
11gh search issues "is:open is:issue label:bug created:>2024-01-01"
12
13# Get issue details
14gh issue view 456
15gh issue view 456 --comments
16gh issue view 456 --json title,body,comments,labels,assignees

Issue Analytics

bash
1# Count issues by label
2gh issue list --label "bug" --json number --jq 'length'
3
4# Get issue timeline
5gh api repos/owner/repo/issues/456/timeline
6
7# Find issues created in date range
8gh issue list --search "created:2024-01-01..2024-01-31"
9
10# Get issue participants
11gh api repos/owner/repo/issues/456 --jq '.assignees[].login, .user.login'

GitHub Actions and Workflow Analysis

Viewing Workflow Runs

bash
1# List recent workflow runs
2gh run list
3gh run list --limit 50
4gh run list --workflow "CI"
5gh run list --status failure
6
7# View specific run details
8gh run view 12345
9gh run view 12345 --json conclusion,status,displayTitle,startedAt
10
11# Get run timing information
12gh run view 12345 --json name,startedAt,updatedAt --jq '"\(.name) took \(((.updatedAt | fromdateiso8601) - (.startedAt | fromdateiso8601)) / 60 | floor) minutes"'

Analyzing Workflow Logs

bash
1# View run logs
2gh run view 12345 --log
3gh run view 12345 --log-failed  # Only failed steps
4
5# Get logs for specific job
6gh run view 12345 --log --job 67890
7
8# Search logs for patterns
9gh run view 12345 --log | grep -i "error"
10gh run view 12345 --log | grep -A 5 -B 5 "test failed"
11
12# Download logs for offline analysis
13gh run download 12345 --name logs

Workflow Performance Analysis

bash
1# Get workflow run history
2gh api repos/owner/repo/actions/workflows/ci.yml/runs
3
4# Analyze success rate
5gh run list --workflow "CI" --limit 100 --json conclusion | \
6  jq 'group_by(.conclusion) | map({conclusion: .[0].conclusion, count: length})'
7
8# Get average run duration
9gh run list --workflow "CI" --status completed --limit 20 --json name,startedAt,updatedAt | \
10  jq '[.[] | ((.updatedAt | fromdateiso8601) - (.startedAt | fromdateiso8601)) / 60] | add / length'
11
12# Find flaky tests
13gh run list --workflow "tests" --limit 50 --json conclusion,headSha | \
14  jq 'group_by(.headSha) | map(select(length > 1) | {sha: .[0].headSha, results: map(.conclusion)})'

Artifact Analysis

bash
1# List artifacts for a run
2gh run view 12345 --json artifacts --jq '.artifacts[]'
3
4# Download artifacts
5gh run download 12345
6gh run download 12345 --name "test-results"
7
8# List artifacts for a repository
9gh api repos/owner/repo/actions/artifacts
10
11# Get artifact details
12gh api repos/owner/repo/actions/artifacts/98765

Code Search and Analysis

Searching Code Across Repositories

bash
1# Search code in organization
2gh search code "org:myorg function fetchUser"
3gh search code "org:myorg extension:js console.log"
4
5# Search with language filters
6gh search code "org:myorg language:python import pandas"
7
8# Search for specific patterns
9gh search code "org:myorg TODO"
10gh search code "org:myorg FIXME"
11gh search code "org:myorg /api/v[0-9]+"
12
13# Search in specific paths
14gh search code "org:myorg path:src/ database connection"

Code Navigation

bash
1# Get file contents
2gh api repos/owner/repo/contents/path/to/file.js
3
4# Get file contents at specific ref
5gh api repos/owner/repo/contents/path/to/file.js?ref=feature-branch
6
7# Browse directory structure
8gh api repos/owner/repo/contents/src
9
10# Get file history
11gh api repos/owner/repo/commits?path=src/main.js

Release Information

Viewing Releases

bash
1# List all releases
2gh release list
3gh release list --exclude-drafts
4gh release list --limit 10
5
6# View specific release
7gh release view v1.0.0
8gh release view latest
9
10# Get release data as JSON
11gh api repos/owner/repo/releases/latest
12
13# Get download statistics
14gh api repos/owner/repo/releases --jq '.[] | {tag: .tag_name, downloads: [.assets[].download_count] | add}'

Advanced Queries

GraphQL Queries for Complex Data

bash
1# Get PR review turnaround time
2gh api graphql -f query='
3  query($owner: String!, $repo: String!) {
4    repository(owner: $owner, name: $repo) {
5      pullRequests(last: 20, states: MERGED) {
6        nodes {
7          number
8          createdAt
9          mergedAt
10          reviews(first: 1) {
11            nodes {
12              createdAt
13            }
14          }
15        }
16      }
17    }
18  }
19' -f owner=myorg -f repo=myrepo
20
21# Get issue response times
22gh api graphql -f query='
23  query($owner: String!, $repo: String!) {
24    repository(owner: $owner, name: $repo) {
25      issues(last: 50, states: CLOSED) {
26        nodes {
27          number
28          createdAt
29          comments(first: 1) {
30            nodes {
31              createdAt
32              author {
33                login
34              }
35            }
36          }
37        }
38      }
39    }
40  }
41' -f owner=myorg -f repo=myrepo

Batch Data Retrieval

bash
1# Get all PRs for analysis (handles pagination)
2gh pr list --state all --limit 1000 --json number,title,createdAt,closedAt,author > prs.json
3
4# Get all issues with labels
5gh issue list --state all --limit 1000 --json number,title,labels,createdAt > issues.json
6
7# Export workflow runs
8gh run list --limit 200 --json displayTitle,conclusion,startedAt,updatedAt > runs.json

Monitoring and Dashboards

PR Review Queue

bash
1# Find PRs awaiting review
2gh pr list --json number,title,author,createdAt,reviewDecision | \
3  jq '.[] | select(.reviewDecision == null) | "PR #\(.number): \(.title) by @\(.author.login)"'
4
5# PRs awaiting your review
6gh search prs "is:open is:pr review-requested:@me"
7
8# Recently updated PRs
9gh pr list --sort updated --json number,title,updatedAt | \
10  jq '.[] | "PR #\(.number): \(.title) (updated \(.updatedAt))"'

Issue Triage

bash
1# Find unlabeled issues
2gh issue list --json number,title,labels | \
3  jq '.[] | select(.labels | length == 0) | "Issue #\(.number): \(.title)"'
4
5# Stale issues (no activity in 30 days)
6gh issue list --search "updated:<$(date -d '30 days ago' '+%Y-%m-%d')"
7
8# High priority issues
9gh issue list --label "priority:high" --label "bug"

Best Practices

1. Use JSON output for scripting: Add --json flag for machine-readable output
2. Leverage jq for data extraction: Parse JSON responses for specific fields
3. Use search syntax: GitHub's search syntax is powerful for filtering
4. Handle pagination: Use --limit or --paginate for large datasets
5. Cache API responses: Use gh api --cache 1h for frequently accessed data

Additional Resources

For more advanced topics:

• Complex GraphQL Queries: See references/graphql-queries.md
• Data Analysis Patterns: See references/data-analysis.md
• Monitoring Scripts: See references/monitoring.md