--- name: github description: Work with GitHub issues, pull requests, workflows, and repositories using the gh CLI. Use when managing GitHub projects. metadata: author: odyssey4me version: "0.1.0" license: MIT --- # GitHub Skill This skill provides guidance for working with GitHub using the official `gh` CLI tool. All GitHub operations (issues, PRs, workflows, repositories) are performed using `gh` commands. ## Prerequisites **Install gh CLI**: Quick install: ```bash # macOS brew install gh # Linux (Debian/Ubuntu) sudo apt install gh # Fedora/RHEL/CentOS sudo dnf install gh # Windows winget install --id GitHub.cli ``` ## Authentication ```bash # Authenticate with GitHub gh auth login # Verify authentication gh auth status ``` See [GitHub CLI Authentication](https://cli.github.com/manual/gh_auth_login) for details. ## Commands ### Issues ```bash gh issue list # List issues gh issue view 123 # View issue details gh issue create # Create new issue gh issue comment 123 # Add comment gh issue close 123 # Close issue gh issue edit 123 --add-label bug # Edit issue ``` Full reference: [gh issue](https://cli.github.com/manual/gh_issue) ### Pull Requests ```bash gh pr list # List PRs gh pr view 456 # View PR details gh pr create # Create new PR gh pr review 456 --approve # Approve PR gh pr merge 456 --squash # Merge PR gh pr checkout 456 # Checkout PR branch gh pr diff 456 # View PR diff gh pr checks 456 # View CI status ``` Full reference: [gh pr](https://cli.github.com/manual/gh_pr) ### Workflows & Actions ```bash gh workflow list # List workflows gh workflow run "CI" # Trigger workflow gh run list # List workflow runs gh run view 123456 # View run details gh run watch 123456 # Watch run progress gh run download 123456 # Download artifacts gh run rerun 123456 --failed # Rerun failed jobs ``` Full references: - [gh workflow](https://cli.github.com/manual/gh_workflow) - [gh run](https://cli.github.com/manual/gh_run) ### Repositories ```bash gh repo list # List repositories gh repo view OWNER/REPO # View repository gh repo create # Create repository gh repo clone OWNER/REPO # Clone repository gh repo fork OWNER/REPO # Fork repository ``` Full reference: [gh repo](https://cli.github.com/manual/gh_repo) ### Search ```bash gh search repos "machine learning" # Search repositories gh search issues "is:open label:bug" # Search issues gh search prs "is:open" # Search pull requests gh search code "function auth" # Search code ``` Full reference: [gh search](https://cli.github.com/manual/gh_search) ## Examples ### Daily PR Review ```bash # List PRs waiting for your review gh pr list --search "review-requested:@me" # Review a specific PR gh pr view 456 gh pr checks 456 gh pr diff 456 gh pr review 456 --approve ``` ### Create Issue and Link PR ```bash # Create issue gh issue create --title "Bug: Login fails" --body "Description" --label bug # Create PR that fixes it (use issue number in title/body) gh pr create --title "Fix login bug (#123)" --body "Fixes #123" ``` ### Monitor CI Pipeline ```bash # Watch latest workflow run gh run watch $(gh run list --limit 1 --json databaseId --jq '.[0].databaseId') # Check failed runs gh run list --status failure # Rerun failed jobs gh run rerun RUNID --failed ``` See [common-workflows.md](references/common-workflows.md) for more examples. ## Advanced Usage ### JSON Output for Scripting ```bash # Get specific fields gh issue list --json number,title,author # Process with jq gh pr list --json number,title | jq '.[] | "\(.number): \(.title)"' # Export to CSV gh issue list --json number,title,author | jq -r '.[] | @csv' ``` ### GitHub API Access For operations not covered by gh commands: ```bash # Make authenticated API request gh api repos/OWNER/REPO/issues # POST request gh api repos/OWNER/REPO/issues -X POST -f title="Issue" -f body="Text" # Process response gh api repos/OWNER/REPO | jq '.stargazers_count' ``` Full reference: [gh api](https://cli.github.com/manual/gh_api) ### Aliases for Frequent Operations ```bash # Create shortcuts gh alias set prs 'pr list --author @me' gh alias set issues 'issue list --assignee @me' gh alias set review 'pr list --search "review-requested:@me"' # Use them gh prs gh issues gh review ``` ## Rate Limits GitHub enforces rate limits for API requests: - **Core API**: 5,000 requests/hour - **Search API**: 30 requests/minute Check current status: ```bash gh api rate_limit --jq '.rate' ``` **Best practices for bulk operations:** - Check rate limit before starting - Use specific filters to reduce result sets - Prefer `--limit` flag to control results - Use exact issue/PR numbers when known ## Configuration ```bash # View configuration gh config list # Set default editor gh config set editor vim # Set git protocol gh config set git_protocol ssh ``` Configuration stored in `~/.config/gh/config.yml` ## Troubleshooting ```bash # Check authentication gh auth status # Re-authenticate gh auth login # Enable debug logging GH_DEBUG=1 gh issue list # Check gh version gh --version ``` ## Official Documentation - **GitHub CLI Manual**: - **GitHub CLI Repository**: - **GitHub API Documentation**: - **GitHub Actions**: ## Summary The GitHub skill uses the official `gh` CLI exclusively. No custom scripts are needed - `gh` provides comprehensive functionality for all GitHub operations. **Quick start:** 1. Install: `brew install gh` (or equivalent for your OS) 2. Authenticate: `gh auth login` 3. Verify: `gh auth status` 4. Use: `gh issue list`, `gh pr create`, etc. For detailed command reference, use `gh --help` or visit .