--- disable-model-invocation: false name: cli-gh user-invocable: false description: This skill should be used when the user mentions "gh CLI", "gh command", asks to "view repository info", "trigger workflows", "search GitHub", "manage codespaces", "check PR status", "list issues", "browse repo", or asks about GitHub CLI usage and automation from the command line. --- # GitHub CLI (gh) ## Overview Expert guidance for GitHub CLI (gh) operations and workflows. Use this skill for command-line GitHub operations including pull request management, issue tracking, repository operations, workflow automation, and codespace management. **Key capabilities:** - Create and manage pull requests from the terminal - Track and organize issues efficiently - Search across all of GitHub (repos, issues, PRs) - Manage labels and project organization - Trigger and monitor GitHub Actions workflows - Work with codespaces - Automate repository operations and releases - Browse repositories, PRs, and files in the browser ## Safety Rules **CRITICAL: This skill NEVER uses destructive gh CLI operations.** This skill focuses exclusively on safe, read-only, or reversible GitHub operations. The following commands are **PROHIBITED** and must **NEVER** be used: **Permanently destructive commands:** - `gh repo delete` - Repository deletion - `gh repo archive` - Repository archival - `gh release delete` - Release deletion - `gh release delete-asset` - Asset deletion - `gh run delete` - Workflow run deletion - `gh cache delete` - Cache deletion - `gh secret delete` - Secret deletion - `gh variable delete` - Variable deletion - `gh label delete` - Label deletion - `gh ssh-key delete` - SSH key deletion (can lock out users) - `gh gpg-key delete` - GPG key deletion - `gh codespace delete` - Codespace deletion - `gh extension remove` - Extension removal - `gh gist delete` - Gist deletion - Bulk deletion operations using `xargs` with any destructive commands - Shell commands: `rm -rf` (except for temporary file cleanup) **Allowed operations:** - Creating resources (PRs, issues, releases, labels, repos) - Viewing and listing (status, logs, information, searches) - Updating and editing existing resources - Closing PRs/issues (reversible - can be reopened) - Reverting pull requests (creates a new revert PR) - Canceling workflow runs (stops execution without deleting data) - Merging pull requests (after proper review) - Read-only git operations (`git status`, `git log`, `git diff`) ## Installation & Setup ```bash # Login to GitHub gh auth login # Login and copy OAuth code to clipboard automatically gh auth login --clipboard # Check authentication status gh auth status # Check auth status with JSON output gh auth status --json # Configure git to use gh as credential helper gh auth setup-git ``` ## Pull Requests ### Creating PRs ```bash # Create PR interactively gh pr create # Create PR with title and body gh pr create --title "Add feature" --body "Description" # Create PR to specific branch gh pr create --base main --head feature-branch # Create draft PR gh pr create --draft # Create PR from current branch gh pr create --fill # Uses commit messages # Create PR with Copilot Code Review gh pr create --reviewer @copilot ``` ### Viewing PRs ```bash # List PRs gh pr list # List my PRs gh pr list --author @me # View PR details gh pr view 123 # View PR in browser gh pr view 123 --web # View PR diff gh pr diff 123 # View PR diff excluding specific files gh pr diff 123 --exclude "*.lock" # Check PR status gh pr status ``` ### Managing PRs ```bash # Checkout PR locally gh pr checkout 123 # Review PR gh pr review 123 --approve gh pr review 123 --comment --body "Looks good!" gh pr review 123 --request-changes --body "Please fix X" # Request Copilot Code Review gh pr edit 123 --add-reviewer @copilot # Merge PR gh pr merge 123 gh pr merge 123 --squash gh pr merge 123 --rebase gh pr merge 123 --merge # Close PR gh pr close 123 # Reopen PR gh pr reopen 123 # Ready draft PR gh pr ready 123 # Update PR branch with base branch gh pr update-branch 123 # Revert a merged PR (creates a new revert PR) gh pr revert 123 ``` ### PR Checks ```bash # View PR checks gh pr checks 123 # Watch PR checks gh pr checks 123 --watch ``` ## Issues ### Creating Issues ```bash # Create issue interactively gh issue create # Create issue with title and body gh issue create --title "Bug report" --body "Description" # Create issue with labels gh issue create --title "Bug" --label bug,critical # Assign issue gh issue create --title "Task" --assignee @me ``` ### Viewing Issues ```bash # List issues gh issue list # List my issues gh issue list --assignee @me # List by label gh issue list --label bug # Advanced issue search gh issue list --search "is:open label:bug sort:created-desc" # View issue details gh issue view 456 # View in browser gh issue view 456 --web ``` ### Managing Issues ```bash # Close issue gh issue close 456 # Close as duplicate, linking to the original issue gh issue close 123 --duplicate-of 456 # Reopen issue gh issue reopen 456 # Edit issue gh issue edit 456 --title "New title" gh issue edit 456 --add-label bug gh issue edit 456 --add-assignee @user # Comment on issue gh issue comment 456 --body "Update" # Create branch to work on issue gh issue develop 456 --checkout ``` ## Repository Operations ### Repository Info ```bash # View repository gh repo view # View in browser gh repo view --web # Clone repository gh repo clone owner/repo # Clone without adding upstream remote gh repo clone owner/repo --no-upstream # Fork repository gh repo fork owner/repo # List repositories gh repo list owner ``` ### Repository Management ```bash # Create repository gh repo create my-repo --public gh repo create my-repo --private # Sync fork gh repo sync owner/repo # Set default repository gh repo set-default ``` ## Search When the user asks to search GitHub repositories, issues, or pull requests, see [references/search.md](references/search.md). ## Labels When the user asks to list, create, edit, or clone repository labels, see [references/labels.md](references/labels.md). ## Codespaces When the user asks to list, create, connect to, or manage files within GitHub Codespaces, see [references/codespaces.md](references/codespaces.md). ## Browse Open repositories, files, and resources in the browser. ```bash # Open current repo in browser gh browse # Open specific file gh browse src/main.go # Open file at specific line gh browse src/main.go:42 # Open blame view for a file gh browse --blame src/main.go # Open Actions tab gh browse --actions # Open specific branch gh browse --branch feature ``` ## Releases When the user asks to create, list, view, or download GitHub releases, see [references/releases.md](references/releases.md). ## Gists When the user asks to create, list, view, or edit GitHub gists, see [references/gists.md](references/gists.md). ## Configuration ```bash # Set default editor gh config set editor vim # Set default git protocol gh config set git_protocol ssh # View configuration gh config list # Set browser gh config set browser firefox ``` ## Quick Reference Common gh operations at a glance: | Operation | Command | Common Flags | | ---------------- | ------------------------- | ------------------------------------------ | | Create PR | `gh pr create` | `--draft`, `--fill`, `--reviewer @copilot` | | List PRs | `gh pr list` | `--author @me`, `--label`, `--search` | | View PR | `gh pr view ` | `--web`, `--comments` | | Merge PR | `gh pr merge ` | `--squash`, `--rebase`, `--delete-branch` | | Revert PR | `gh pr revert ` | `--body` | | Create issue | `gh issue create` | `--title`, `--body`, `--label` | | List issues | `gh issue list` | `--assignee @me`, `--label`, `--search` | | Close issue | `gh issue close ` | `--duplicate-of`, `--reason` | | View issue | `gh issue view ` | `--web`, `--comments` | | Browse repo | `gh browse` | `--blame`, `--actions`, `--branch` | | Clone repo | `gh repo clone ` | `--no-upstream` | | Fork repo | `gh repo fork` | `--clone`, `--remote` | | View repo | `gh repo view` | `--web` | | Create release | `gh release create ` | `--title`, `--notes`, `--draft` | | Verify release | `gh release verify ` | `--repo` | | Run workflow | `gh workflow run ` | `--ref`, `--field` | | Watch run | `gh run watch ` | `--exit-status` | | Search repos | `gh search repos ` | `--language`, `--stars` | | Create label | `gh label create ` | `--color`, `--description` | | Create codespace | `gh codespace create` | `--repo`, `--branch` | ## Additional Resources ### Reference Guides For detailed patterns and advanced usage, see: - **[Workflows & Actions](references/workflows-actions.md)** - GitHub Actions workflows, runs, cache management, and CI/CD integration patterns - **[Advanced Features](references/advanced-features.md)** - Aliases, API access, extensions, secrets, SSH/GPG keys, organizations, projects, and advanced scripting - **[Automation Workflows](references/automation-workflows.md)** - Common automation patterns, daily reports, release automation, and team collaboration workflows - **[Troubleshooting](references/troubleshooting.md)** - Solutions for authentication, permissions, rate limiting, and common errors ### Example Scripts Practical automation scripts (see `examples/` directory): - `auto-pr-create.sh` - Automated PR creation workflow - `issue-triage.sh` - Bulk issue labeling and assignment - `workflow-monitor.sh` - Watch and notify on workflow completion - `release-automation.sh` - Complete release workflow automation ### External Documentation - **Official Manual**: https://cli.github.com/manual - **GitHub Community**: https://github.com/cli/cli/discussions - **API Documentation**: https://docs.github.com/en/rest - **Extension Marketplace**: https://github.com/topics/gh-extension ## JSON Output When the user wants to use `--json` flags or needs the correct gh CLI JSON field names, see [references/json-output.md](references/json-output.md). ## Tips 1. Use `--web` flag to open items in browser for detailed view 2. Leverage interactive prompts by omitting parameters - most commands support interactive mode 3. Apply filters with `--author`, `--label`, `--state` to narrow down lists efficiently 4. Add `--json` flag to enable scriptable output for automation 5. **Always check `--help` for valid JSON field names** - they differ from GitHub API 6. Use `gh repo create --template` to scaffold from template repositories 7. Enable auto-merge with `gh pr merge --auto` for PRs that pass checks