cli-gh

What this skill does

# 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 <number>`     | `--web`, `--comments`                      |
| Merge PR         | `gh pr merge <number>`    | `--squash`, `--rebase`, `--delete-branch`  |
| Revert PR        | `gh pr revert <number>`   | `--body`                                   |
| Create issue     | `gh issue create`         | `--title`, `--body`, `--label`             |
| List issues      | `gh issue list`           | `--assignee @me`, `--label`, `--search`    |
| Close issue      | `gh issue close <number>` | `--duplicate-of`, `--reason`               |
| View issue       | `gh issue view <number>`  | `--web`, `--comments`                      |
| Browse repo      | `gh browse`               | `--blame`, `--actions`, `--branch`