GitHub CLI (gh)

--- name: GitHub CLI (gh) description: Use when you need to interact with GitHub repositories, issues, pull requests, and workflows directly from the command line. Essential for automated workflows, CI/CD pipelines, and efficient Git-based development processes. metadata: author: skynet version: 1.0.0 category: dev --- # GitHub CLI (gh) Skill ## Authentication & Setup ```bash # Login to GitHub gh auth login # Check authentication status gh auth status # Set up Git protocol preference gh config set git_protocol ssh gh config set git_protocol https ``` ## Repository Operations ### Creating & Cloning ```bash # Create new repository gh repo create my-project --public --clone gh repo create my-project --private --description "My project description" # Clone repository gh repo clone owner/repository gh repo clone owner/repository ./custom-directory # Fork repository gh repo fork owner/repository --clone gh repo fork owner/repository --remote ``` ### Repository Management ```bash # View repository info gh repo view gh repo view owner/repository # List repositories gh repo list gh repo list owner --limit 50 # Delete repository gh repo delete owner/repository --confirm ``` ## Issue Management ### Creating & Listing Issues ```bash # Create new issue gh issue create --title "Bug report" --body "Description of the bug" gh issue create --title "Feature request" --assignee @me --label enhancement # List issues gh issue list gh issue list --state open --assignee @me gh issue list --label bug --limit 10 # View issue details gh issue view 123 gh issue view 123 --comments ``` ### Issue Operations ```bash # Close issue gh issue close 123 --comment "Fixed in latest commit" # Reopen issue gh issue reopen 123 # Edit issue gh issue edit 123 --title "New title" --add-label priority gh issue edit 123 --remove-assignee @user # Pin/unpin issue gh issue pin 123 gh issue unpin 123 ``` ## Pull Request Workflows ### Creating Pull Requests ```bash # Create PR from current branch gh pr create --title "Add new feature" --body "Description of changes" gh pr create --draft --assignee @me --reviewer @teammate # Create PR with template gh pr create --template bug_report.md # Create PR to specific branch gh pr create --base develop --head feature-branch ``` ### PR Management ```bash # List pull requests gh pr list gh pr list --state merged --limit 20 gh pr list --author @me --label "needs review" # View PR details gh pr view 456 gh pr view 456 --comments # Checkout PR locally gh pr checkout 456 # Review PR gh pr review 456 --approve gh pr review 456 --request-changes --body "Please fix the tests" gh pr review 456 --comment --body "LGTM!" ``` ### PR Operations ```bash # Merge pull request gh pr merge 456 --merge --delete-branch gh pr merge 456 --squash --body "Summary of changes" gh pr merge 456 --rebase # Close PR without merging gh pr close 456 --comment "No longer needed" # Mark PR as ready for review gh pr ready 456 # Convert to draft gh pr edit 456 --draft ``` ## GitHub Actions & Workflows ```bash # List workflow runs gh run list gh run list --workflow ci.yml --limit 10 # View workflow run details gh run view 123456789 # Re-run failed workflow gh run rerun 123456789 --failed # Cancel running workflow gh run cancel 123456789 # Watch workflow run in real-time gh run watch 123456789 # Download workflow artifacts gh run download 123456789 ``` ## Release Management ```bash # Create release gh release create v1.0.0 --title "Version 1.0.0" --notes "Release notes" gh release create v1.0.0 ./dist/* --prerelease # List releases gh release list --limit 10 # View release details gh release view v1.0.0 # Upload additional assets gh release upload v1.0.0 ./binary.tar.gz # Delete release gh release delete v1.0.0 --yes ``` ## Decision Tree: When to Use Which Command ``` Need to work with GitHub? ├─ Repository tasks? │ ├─ Creating new repo → gh repo create │ ├─ Forking existing → gh repo fork │ └─ Getting info → gh repo view ├─ Issue tracking? │ ├─ Reporting bug → gh issue create --label bug │ ├─ Feature request → gh issue create --label enhancement │ └─ Managing existing → gh issue list/edit/close ├─ Code review process? │ ├─ Submitting changes → gh pr create │ ├─ Reviewing code → gh pr review │ └─ Merging approved → gh pr merge └─ CI/CD monitoring? ├─ Check workflow status → gh run list ├─ Debug failures → gh run view └─ Re-run builds → gh run rerun ``` ## Advanced Workflows ### Bulk Operations ```bash # Close multiple issues gh issue list --state open --json number --jq '.[].number' | \ xargs -I {} gh issue close {} # Approve multiple PRs from trusted contributor gh pr list --author trusted-dev --json number --jq '.[].number' | \ xargs -I {} gh pr review {} --approve ``` ### Scripting with gh ```bash #!/bin/bash # Auto-create PR when pushing to feature branch if [[ $(git branch --show-current) == feature/* ]]; then gh pr create --draft --title "WIP: $(git branch --show-current)" \ --body "Auto-created PR for feature branch" fi ``` ### API Integration ```bash # Make custom API calls gh api repos/:owner/:repo/issues --field state=open gh api user --jq '.login' # Pagination gh api repos/:owner/:repo/issues --paginate --field state=all ``` ## Troubleshooting ### Authentication Issues ``` Error: HTTP 401: Bad credentials ``` **Fix:** Re-authenticate with `gh auth login` and ensure token has correct scopes ### Permission Errors ``` Error: HTTP 403: Resource not accessible by integration ``` **Fix:** Check repository permissions and token scopes: ```bash gh auth status gh repo view owner/repo # Verify access ``` ### Network/API Issues ``` Error: failed to run git: exit status 128 ``` **Fix:** Verify Git configuration and repository URL: ```bash gh auth setup-git git remote -v ``` ### Large File Uploads ``` Error: file too large ``` **Fix:** Use release assets for large files: ```bash gh release create v1.0.0 gh release upload v1.0.0 large-file.zip ``` ### Workflow Run Failures ```bash # Debug workflow issues gh run view 123456789 --log gh run list --workflow broken.yml --json conclusion ``` ## Configuration & Customization ```bash # Set default editor gh config set editor vim # Configure default repository visibility gh config set prompt disabled # Set aliases gh alias set co 'pr checkout' gh alias set pv 'pr view' # List all configuration gh config list ``` ## Integration Examples ### Git Hooks Integration ```bash # In .git/hooks/post-push #!/bin/bash gh pr create --draft 2>/dev/null || echo "PR might already exist" ``` ### CI/CD Pipeline Usage ```bash # In GitHub Actions workflow - name: Create release run: gh release create ${{ github.ref_name }} --generate-notes env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ```