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

# 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

# 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

# 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

# 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

# View PR checks

gh pr checks 123

# Watch PR checks

gh pr checks 123 --watch

Issues

Creating Issues

# 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

# 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

# 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

# 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

# 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.

Labels

When the user asks to list, create, edit, or clone repository labels, see references/labels.md.

Codespaces

When the user asks to list, create, connect to, or manage files within GitHub Codespaces, see references/codespaces.md.

Browse

Open repositories, files, and resources in the browser.

# 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.

Gists

When the user asks to create, list, view, or edit GitHub gists, see references/gists.md.

Configuration

# 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

Clone repo

gh repo clone <repo>

--no-upstream

Fork repo

gh repo fork

--clone, --remote

View repo

gh repo view

--web

Create release

gh release create <tag>

--title, --notes, --draft

Verify release

gh release verify <tag>

--repo

Run workflow

gh workflow run <name>

--ref, --field

Watch run

gh run watch <id>

--exit-status

Search repos

gh search repos <query>

--language, --stars

Create label

gh label create <name>

--color, --description

Create codespace

gh codespace create

--repo, --branch

Additional Resources

Reference Guides

For detailed patterns and advanced usage, see:

• Workflows & Actions - GitHub Actions workflows, runs, cache management, and CI/CD integration patterns

• Advanced Features - Aliases, API access, extensions, secrets, SSH/GPG keys, organizations, projects, and advanced scripting

• Automation Workflows - Common automation patterns, daily reports, release automation, and team collaboration workflows

• Troubleshooting - 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.

Tips

• Use --web flag to open items in browser for detailed view

• Leverage interactive prompts by omitting parameters - most commands support interactive mode

• Apply filters with --author, --label, --state to narrow down lists efficiently

• Add --json flag to enable scriptable output for automation

• **Always check --help for valid JSON field names** - they differ from GitHub API

• Use gh repo create --template to scaffold from template repositories

• Enable auto-merge with gh pr merge --auto for PRs that pass checks