---
name: github-cli
description: Install and configure GitHub CLI (gh) — authentication, repo management, PRs, issues, releases, and automation workflows
license: MIT
compatibility: opencode
metadata:
  platform: macos,linux
  category: devops
---

## What I do

Guide the installation, authentication, and everyday usage of the GitHub CLI (`gh`) — the official command-line tool for GitHub.

## When to use me

Use this skill when the user wants to:
- Install and authenticate `gh` for the first time
- Create, clone, or manage GitHub repositories from the terminal
- Create and manage pull requests and issues
- Set up GitHub Actions secrets and workflows
- Create releases and manage tags
- Configure GitHub repo settings (visibility, topics, branch protection)
- Troubleshoot `gh` authentication errors

## Workflow

### Step 1: Install gh

**macOS:**
```bash
brew install gh
```

**Linux (Debian/Ubuntu):**
```bash
(type -p wget >/dev/null || sudo apt-get install wget -y) \
&& sudo mkdir -p -m 755 /etc/apt/keyrings \
&& wget -qO- https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y
```

**Linux (Fedora/RHEL):**
```bash
sudo dnf install gh
```

Verify:
```bash
gh --version
```

### Step 2: Authenticate

```bash
gh auth login
```

Follow the interactive prompts:
1. Select **GitHub.com** (or GitHub Enterprise Server if applicable)
2. Select **HTTPS** (recommended for most users)
3. Choose authentication method:
   - **Login with a web browser** (easiest) — opens browser, enter one-time code
   - **Paste an authentication token** — if you have a personal access token

**For CI/CD or headless environments:**
```bash
echo "$GITHUB_TOKEN" | gh auth login --with-token
```

**Verify authentication:**
```bash
gh auth status
```

### Step 3: Configure defaults

```bash
# Set default editor
gh config set editor "code --wait"    # VS Code
# gh config set editor vim

# Set default protocol
gh config set git_protocol ssh        # or https

# Set default pager
gh config set pager less
```

### Step 4: Repository management

**Create a new repo:**
```bash
# From current directory
gh repo create my-project --public --source=. --push

# From scratch
gh repo create my-project --public --clone

# Flags: --public | --private | --internal
#         --push   (add remote and push)
#         --clone   (clone after creating)
```

**Clone an existing repo:**
```bash
gh repo clone owner/repo
```

**View repo in browser:**
```bash
gh repo view --web
```

**Fork a repo:**
```bash
gh repo fork owner/repo --clone
```

**List your repos:**
```bash
gh repo list
```

### Step 5: Pull request workflow

**Create a PR:**
```bash
# Simple, auto-fills title from branch name
gh pr create --base main

# With title and body
gh pr create --title "Add new feature" --body "This adds..."

# Mark as draft
gh pr create --draft

# Auto-fill from commit message
gh pr create --fill

# Assign reviewers, labels
gh pr create --reviewer @user1,@user2 --label bug,urgent
```

**List and view PRs:**
```bash
gh pr list                    # Open PRs in current repo
gh pr list --state merged     # Merged PRs
gh pr view                    # Current branch's PR
gh pr view 42 --web           # Open PR #42 in browser
```

**Check out a PR locally:**
```bash
gh pr checkout 42
```

**Review a PR:**
```bash
gh pr review 42 --approve
gh pr review 42 --comment -b "Looks good, just one nit"
gh pr review 42 --request-changes -b "Needs tests"
```

**Merge a PR:**
```bash
gh pr merge 42 --squash
gh pr merge 42 --rebase
gh pr merge 42 --merge       # Standard merge commit
```

### Step 6: Issue management

**Create an issue:**
```bash
gh issue create --title "Bug: login broken" --body "Steps to reproduce..."
gh issue create --label bug,high-priority --assignee @me
```

**List and view issues:**
```bash
gh issue list
gh issue list --label bug --state open
gh issue view 15 --web
```

**Comment on an issue:**
```bash
gh issue comment 15 --body "I'm working on this"
```

**Close/reopen:**
```bash
gh issue close 15
gh issue reopen 15
```

### Step 7: Releases

```bash
# Create a release from a tag
gh release create v1.0.0 --title "First release" --notes "Changelog here..."

# Generate notes from merged PRs
gh release create v1.0.0 --generate-notes

# Create and push tag + release in one step
gh release create v1.0.0 --target main --generate-notes
```

### Step 8: GitHub Actions

```bash
# List workflows
gh workflow list

# Run a workflow
gh workflow run "CI" --ref main

# View workflow runs
gh run list --workflow "CI"

# View a specific run
gh run view <run-id>

# Watch a run in progress
gh run watch <run-id>
```

### Step 9: Secrets and variables

```bash
# Set a repository secret
gh secret set MY_SECRET --body "secret-value"

# Set from file
gh secret set ENV_FILE < .env.production

# Set an environment variable
gh variable set DEPLOY_URL --body "https://example.com"

# List secrets
gh secret list
```

### Step 10: Gist management

```bash
# Create a gist
gh gist create file.go --public --desc "Useful Go snippet"

# Edit a gist
gh gist edit <gist-id>
```

### Step 11: Useful shortcuts and tips

**Alias for common operations (add to ~/.config/gh/config.yml):**
```yaml
aliases:
  prs: pr list
  pv: pr view
  co: pr checkout
  rv: repo view --web
  wf: workflow list
```

**Search repos:**
```bash
gh search repos "topic:dev-setup language:javascript"
```

**Check GitHub status:**
```bash
gh status
```

**Get PR diff locally:**
```bash
gh pr diff 42 | bat            # with bat for syntax highlighting
```

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `gh: command not found` | Install gh: `brew install gh` |
| `authentication failed` | Re-authenticate: `gh auth login` |
| `could not resolve host: github.com` | Check network / VPN / DNS |
| `GitHub CLI token expired` | Run `gh auth refresh -h github.com -s repo` |
| `You must be on a branch` | Create a branch first: `git checkout -b my-branch` |
| SSH authentication fails after `gh auth` | Set protocol: `gh config set git_protocol https` |
| Rate limit exceeded (API) | Use authenticated requests vs. unauthenticated |
| `gh auth login` stuck in loop | Try `gh auth login --hostname github.com --with-token` and paste a PAT |

## Key notes for the agent

- **gh is the standard tool for GitHub CLI**. Don't suggest curl or raw API unless gh is unavailable or the task requires it.
- **Use gh over manual git remote commands** — it's simpler and handles auth automatically.
- **For SSH users**: `gh auth login` sets up git credentials. If user prefers SSH, suggest `gh config set git_protocol ssh`.
- **Token scope**: For full functionality, a token with `repo`, `read:org`, `workflow` scopes is needed. Guide user to create one at https://github.com/settings/tokens if needed.
- **Enterprise**: For GitHub Enterprise Server, use `gh auth login --hostname github.mycompany.com`.
- gh can handle most GitHub operations — repos, PRs, issues, releases, actions, gists, search.