Cli Gh

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"

# Use a Markdown issue template as interactive/editor starting body text
gh issue create --template "Bug Report"

# Create issue with labels
gh issue create --title "Bug" --label bug,critical

# Assign issue
gh issue create --title "Task" --assignee @me

# Set the issue type (GitHub.com and GHES 3.17+)
gh issue create --type Bug

--template cannot be combined with --body or --body-file; use it with prompts, --editor, or --web. For YAML issue forms, fetch and render the form fields yourself for non-interactive automation, or finish in the browser.

Viewing Issues

# List issues
gh issue list

# List my issues
gh issue list --assignee @me

# List by label
gh issue list --label bug

# Filter by issue type
gh issue list --type 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

Issue Types, Sub-Issues & Relationships

Issue types and sub-issues require GitHub.com or GHES 3.17+; blocking relationships require GHES 3.19+.

# Set or remove the issue type
gh issue edit 456 --type Bug
gh issue edit 456 --remove-type

# Create a sub-issue under a parent
gh issue create --parent 100

# Organize existing issues into a parent/child hierarchy
gh issue edit 100 --add-sub-issue 123,124
gh issue edit 100 --remove-sub-issue 123
gh issue edit 123 --parent 100
gh issue edit 123 --remove-parent

# Track blocked-by / blocking relationships
gh issue create --blocked-by 200,201 --blocking 300
gh issue edit 123 --add-blocked-by 200 --add-blocking 300,301
gh issue edit 123 --remove-blocked-by 200 --remove-blocking 301

Discussions

When the user asks to list, view, create, edit, or comment on GitHub Discussions, see references/discussions.md. The gh discussion command set is in preview and subject to change.

Copilot Agent Tasks

Delegate work to the Copilot coding agent and track its sessions. The gh agent-task command set (aliases gh agent, gh agents) is in preview.

# Create an agent task on the current repository
gh agent-task create "Improve the performance of the data processing pipeline"

# List your most recent agent tasks
gh agent-task list
gh agent-task list --json id,name,state

# View an agent task session (by PR number, session ID, or URL)
gh agent-task view 123
gh agent-task view <session-id> --json state --jq '.state'

Agent Skills

Discover, install, and publish agent skills from GitHub repositories. The gh skill command set (alias gh skills) is in preview.

# Search for skills across GitHub
gh skill search terraform

# Preview a skill before installing
gh skill preview github/awesome-copilot documentation-writer

# Install a skill (default scope: project)
gh skill install github/awesome-copilot documentation-writer
gh skill install owner/repo skill-name --scope user --pin v1.2.0

# Include skills in hidden dirs (.claude/skills/, .agents/skills/, .github/skills/)
gh skill install owner/repo skill-name --allow-hidden-dirs

# List installed skills and update them
gh skill list
gh skill update --all

# Validate and publish your own skills
gh skill publish --dry-run

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

# Configure the squash-merge commit message default
gh repo edit --squash-merge-commit-message COMMIT_MESSAGES

Reading Repo Contents

Read files and directories without cloning. The gh repo read-file and gh repo read-dir commands are in preview and subject to change.

# Read a file from the default branch (paged in a TTY, raw when piped)
gh repo read-file README.md --repo cli/cli

# Read from a specific branch, tag, or commit
gh repo read-file go.mod --ref v2.94.0 --repo cli/cli

# Write to disk instead of stdout (--clobber to overwrite)
gh repo read-file README.md --output ./README.md --clobber

# Refuse escape sequences by default; opt in for TTY/piped output
gh repo read-file script.sh --allow-escape-sequences

# List a directory (root when no path given)
gh repo read-dir script --repo cli/cli

# Inspect entries as JSON for scripting
gh repo read-dir docs --repo cli/cli --json name,path,type,size

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:

Additional Resources

Reference Guides

For detailed patterns and advanced usage, see:

• [Discussions](references/discussions.md) - List, view, create, edit, and comment on GitHub Discussions (preview)
• [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.

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

Advanced Features

Advanced gh CLI capabilities for power users and automation.

Aliases

Create custom shortcuts for frequently used commands.

# Create alias
gh alias set pv "pr view"
gh alias set bugs "issue list --label bug"

# List aliases
gh alias list

# Use alias
gh pv 123

API Access

Direct access to GitHub's REST API through gh CLI.

# Make API call
gh api repos/:owner/:repo/issues

# With JSON data
gh api repos/:owner/:repo/issues -f title="Bug" -f body="Description"

# Paginated results
gh api --paginate repos/:owner/:repo/issues

Extensions

Extend gh CLI functionality with community extensions.

# List extensions
gh extension list

# Install extension
gh extension install owner/gh-extension

# Upgrade extensions
gh extension upgrade --all

Secrets and Variables

Manage GitHub Actions secrets and variables.

Secrets

# List secrets
gh secret list

# Set secret
gh secret set SECRET_NAME

# Set secret from file
gh secret set SECRET_NAME < secret.txt

Variables

# List variables
gh variable list

# Set variable
gh variable set VAR_NAME --body "value"

SSH and GPG Keys

SSH Keys

# List SSH keys
gh ssh-key list

# Add SSH key
gh ssh-key add ~/.ssh/id_ed25519.pub --title "My laptop"

GPG Keys

# List GPG keys
gh gpg-key list

# Add GPG key
gh gpg-key add <key-file>

Organizations

Manage organization settings and resources.

# List organizations
gh org list

# View organization info
gh org view <org-name>

Projects

Work with GitHub Projects.

# List projects
gh project list --owner <org-name>

# View project
gh project view <project-number>

# Create project
gh project create --owner <org-name> --title "Project Name"

# List project items with a filter query
gh project item-list <project-number> --query "status:Done"

Repository Rulesets

View information about repository rulesets.

# List rulesets
gh ruleset list

# View ruleset
gh ruleset view <ruleset-id>

Attestations

Work with artifact attestations for supply chain security.

# Verify release attestation
gh release verify <tag>

# Verify specific asset
gh release verify-asset <file> --repo owner/repo

Advanced Scripting Patterns

Using jq with gh

# Extract specific fields from JSON output
gh pr list --json number,title,author --jq '.[] | select(.author.login=="username")'

# Count open PRs
gh pr list --json state --jq 'length'

# Get PR numbers only
gh pr list --json number --jq '.[].number'

Error Handling in Scripts

# Check if PR exists before operating
if gh pr view 123 &>/dev/null; then
  gh pr merge 123
else
  echo "PR not found"
fi

Batch Operations

# Add label to multiple issues
gh issue list --assignee @me --json number --jq '.[].number' | xargs -I {} gh issue edit {} --add-label "in-progress"

Automation Workflows

Common workflow patterns and automation examples using gh CLI.

Common Workflows

Code Review Workflow

# List PRs assigned to you
gh pr list --assignee @me

# Checkout PR for testing
gh pr checkout 123

# Run tests, review code...

# Approve PR
gh pr review 123 --approve --body "LGTM!"

# Merge PR
gh pr merge 123 --squash

Quick PR Creation

# Create feature branch, make changes, commit
git checkout -b feature/new-feature
# ... make changes ...
git add .
git commit -m "Add new feature"
git push -u origin feature/new-feature

# Create PR from commits
gh pr create --fill

# View PR
gh pr view --web

Issue Triage

# List open issues
gh issue list

# Add labels to issues
gh issue edit 456 --add-label needs-triage
gh issue edit 456 --add-label bug

# Assign issue
gh issue edit 456 --add-assignee @developer

Advanced Automation Patterns

Daily Standup Report

#!/bin/bash
# Generate daily activity report

echo "## My GitHub Activity - $(date +%Y-%m-%d)"
echo ""
echo "### PRs Created"
gh pr list --author @me --search "created:$(date +%Y-%m-%d)"
echo ""
echo "### PRs Reviewed"
gh search prs "reviewed-by:@me created:$(date +%Y-%m-%d)"
echo ""
echo "### Issues Closed"
gh issue list --author @me --state closed --search "closed:$(date +%Y-%m-%d)"

Auto-label PRs by Files Changed

#!/bin/bash
# Auto-label PR based on changed files

PR_NUMBER=$1
FILES=$(gh pr diff $PR_NUMBER --name-only)

if echo "$FILES" | grep -q "^docs/"; then
  gh pr edit $PR_NUMBER --add-label "documentation"
fi

if echo "$FILES" | grep -q "\.test\."; then
  gh pr edit $PR_NUMBER --add-label "tests"
fi

if echo "$FILES" | grep -q "package\.json"; then
  gh pr edit $PR_NUMBER --add-label "dependencies"
fi

Sync Fork with Upstream

#!/bin/bash
# Keep fork in sync with upstream

gh repo sync owner/fork --source upstream/repo --branch main
git fetch origin main
git merge origin/main

Release Checklist Automation

#!/bin/bash
# Automated release checklist

VERSION=$1

# 1. Ensure on main branch
git checkout main && git pull

# 2. Run tests
npm test || exit 1

# 3. Create release tag
git tag -a "v$VERSION" -m "Release $VERSION"
git push origin "v$VERSION"

# 4. Create GitHub release
gh release create "v$VERSION" --generate-notes

# 5. Upload artifacts
gh release upload "v$VERSION" dist/*

Bulk PR Operations

#!/bin/bash
# Approve all PRs from dependabot

gh pr list --author app/dependabot --json number --jq '.[].number' | \
  xargs -I {} gh pr review {} --approve --body "Auto-approved dependency update"

Monitor CI Status

#!/bin/bash
# Monitor all active PRs for CI failures

gh pr list --json number,title,statusCheckRollup --jq '.[] |
  select(.statusCheckRollup.state == "FAILURE") |
  "\(.number): \(.title)"'

Notifications and Monitoring

Watch for PR Reviews

# Monitor PR for new reviews
while true; do
  REVIEWS=$(gh pr view 123 --json reviews --jq '.reviews | length')
  echo "Reviews: $REVIEWS"
  sleep 60
done

Get Notified on Workflow Completion

#!/bin/bash
# Wait for workflow and send notification

RUN_ID=$1
gh run watch $RUN_ID
STATUS=$(gh run view $RUN_ID --json conclusion --jq '.conclusion')

if [ "$STATUS" = "success" ]; then
  osascript -e 'display notification "Workflow passed!" with title "GitHub Actions"'
else
  osascript -e 'display notification "Workflow failed!" with title "GitHub Actions"'
fi

PR Staleness Check

#!/bin/bash
# Find stale PRs (no activity in 30 days)

gh pr list --json number,title,updatedAt --jq '.[] |
  select((now - (.updatedAt | fromdateiso8601)) > (30*86400)) |
  "\(.number): \(.title)"'

Team Collaboration Patterns

Assign PR Reviewers by Team

# Auto-assign team members as reviewers
gh pr create --reviewer team/backend,team/security --assignee @me

Bulk Issue Assignment

# Assign all bugs to triage team
gh issue list --label bug --json number --jq '.[].number' | \
  xargs -I {} gh issue edit {} --add-assignee @triager

Weekly Team Report

#!/bin/bash
# Generate weekly team activity summary

TEAM="myteam"
SINCE=$(date -v-7d +%Y-%m-%d)

echo "# Team Activity Report - Week of $(date +%Y-%m-%d)"
echo ""
echo "## PRs Merged"
gh search prs "team:$TEAM is:merged merged:>=$SINCE" --limit 100
echo ""
echo "## Issues Closed"
gh search issues "team:$TEAM is:closed closed:>=$SINCE" --limit 100

Repository Management

Batch Repository Creation

#!/bin/bash
# Create multiple repositories from template

TEMPLATE="org/template-repo"
REPOS=("project-a" "project-b" "project-c")

for repo in "${REPOS[@]}"; do
  gh repo create "org/$repo" --template "$TEMPLATE" --private
done

Clone All Organization Repos

#!/bin/bash
# Clone all repos from an organization

ORG="myorg"
gh repo list "$ORG" --limit 1000 --json name --jq '.[].name' | \
  xargs -I {} gh repo clone "$ORG/{}"

Sync Multiple Forks

#!/bin/bash
# Sync all your forks with upstream

gh repo list @me --fork --json name,parent --jq '.[] |
  "\(.name) \(.parent.owner.login)/\(.parent.name)"' | \
  while read fork upstream; do
    gh repo sync "$fork" --source "$upstream"
  done

Codespaces

When to read: Read when the user asks to list, create, connect to, or manage files within GitHub Codespaces from the terminal.

Manage GitHub Codespaces directly from the terminal.

List and Create Codespaces

# List codespaces
gh codespace list

# Create new codespace
gh codespace create --repo owner/repo

Connect to Codespaces

# SSH into codespace
gh codespace ssh

# Open in VS Code
gh codespace code

# Open in JupyterLab
gh codespace jupyter

Manage Codespace Files

# Copy files to/from codespace
gh codespace cp local-file.txt remote:~/path/
gh codespace cp remote:~/path/file.txt ./local-dir/

# View logs
gh codespace logs

Discussions

When to read: Read when the user asks to list, view, create, edit, or comment on GitHub Discussions.

The gh discussion command set is in preview and subject to change. A discussion is supplied by number (123) or URL.

# List discussions
gh discussion list
gh discussion list --answered
gh discussion list --sort created --order asc
gh discussion list --json number,title,category,answeredAt

# View a discussion, its comments, or replies to a comment
gh discussion view 123
gh discussion view 123 --comments
gh discussion view 123 --order oldest

# Create a discussion (interactive when flags omitted)
gh discussion create
gh discussion create --title "My question" --category "Q&A" --body "Details here"
gh discussion create --title "Notes" --category "General" --body-file notes.md --label question

# Edit a discussion
gh discussion edit 123 --title "New title"
gh discussion edit 123 --add-label answered --remove-label question

# Comment on a discussion, or reply to a comment using its URL
gh discussion comment 123 --body "Thanks!"
gh discussion comment <comment-url> --body "Reply text"

# Edit or delete a comment
gh discussion comment <comment-url> --edit --body "Updated"
gh discussion comment <comment-url> --delete --yes

Gists

When to read: Read when the user asks to create, list, view, or edit GitHub gists.

# Create gist
gh gist create file.txt

# Create gist from stdin
echo "content" | gh gist create -

# List gists
gh gist list

# View gist
gh gist view <gist-id>

# Edit gist
gh gist edit <gist-id>

JSON Output

When to read: Read when the user wants to use the --json flag for scriptable output, or needs to know the correct gh CLI JSON field names (which differ from GitHub API names).

Use --json flag for structured output. Always verify field names with `--help` as they differ from GitHub API names.

# Check available JSON fields for any command
gh repo view --help | grep -A 50 "JSON FIELDS"
gh pr list --help | grep -A 50 "JSON FIELDS"

Common JSON Field Corrections

Repository View Fields

# Common fields for gh repo view --json
gh repo view owner/repo --json name,description,stargazerCount,forkCount,updatedAt,url,readme

Labels

When to read: Read when the user asks to list, create, edit, or clone repository labels for issue and PR organization.

Manage repository labels for issue and PR organization.

List and View Labels

# List all labels in repository
gh label list

Create and Edit Labels

# Create new label
gh label create "priority: high" --color FF0000 --description "High priority items"

# Edit existing label
gh label edit "bug" --color FFAA00 --description "Something isn't working"

Clone Labels Between Repos

# Clone labels from another repository
gh label clone owner/source-repo

Releases

When to read: Read when the user asks to create, list, view, or download GitHub releases and their assets.

Creating Releases

# Create release
gh release create v1.0.0

# Create release with notes
gh release create v1.0.0 --notes "Release notes"

# Create release with files
gh release create v1.0.0 dist/*.tar.gz

# Create draft release
gh release create v1.0.0 --draft

# Generate release notes automatically
gh release create v1.0.0 --generate-notes

Managing Releases

# List releases
gh release list

# View release
gh release view v1.0.0

# Download release assets
gh release download v1.0.0

Search

When to read: Read when the user asks to search GitHub repositories, issues, or pull requests using the gh search family of commands.

Search across all of GitHub for repositories, issues, and pull requests.

Search Repositories

# Search for repositories
gh search repos "machine learning" --language=python

# Search with filters
gh search repos --stars=">1000" --topic=kubernetes

Search Issues

# Search issues across GitHub
gh search issues "bug" --label=critical --state=open

# Exclude results (note the -- to prevent flag interpretation)
gh search issues -- "memory leak -label:wontfix"

Scope to one repository

Two repo-scoped paths; pick by whether you want search-ranked results or a plain filtered list.

# Search API, scoped to a repo (relevance-ranked; repeat --repo for several)
gh search issues "panic" --repo cli/cli --state=open

# List a single repo's issues with a search filter (defaults to current repo)
gh issue list --repo cli/cli --search "is:open label:bug sort:created-desc"

gh search issues hits GitHub's search index (cross-repo, relevance-ranked, ~1000-result cap). gh issue list --search lists one repo's issues with the same is:/label:/sort: qualifiers and honors --limit.

Search Pull Requests

# Search PRs
gh search prs --author=@me --state=open

# Search with date filters
gh search prs "refactor" --created=">2024-01-01"

Troubleshooting

Common issues and solutions when using gh CLI.

Authentication Issues

Not Authenticated

Error: gh: To get started with GitHub CLI, please run: gh auth login

Solution:

# Login with web browser
gh auth login

# Login with token
gh auth login --with-token < token.txt

# Check auth status
gh auth status

Token Expired

Error: HTTP 401: Bad credentials (HTTP 401)

Solution:

# Refresh authentication
gh auth refresh

# Re-login if refresh fails
gh auth logout
gh auth login

Wrong Account

Problem: Authenticated as wrong user

Solution:

# Check current authentication
gh auth status

# Switch accounts
gh auth login --hostname github.com

# Use multiple accounts with different hosts
export GH_HOST=github.com
gh auth login

Missing Scopes

Error: HTTP 403: Resource not accessible by personal access token

Solution:

# Add required scopes (use --clipboard to auto-copy OAuth code)
gh auth refresh -h github.com -s repo,workflow,admin:org

# Common scopes needed:
# - repo: Full control of private repositories
# - workflow: Update GitHub Action workflows
# - admin:org: Full control of orgs and teams
# - write:packages: Upload packages to GitHub Package Registry

Permission Issues

Insufficient Permissions

Error: HTTP 403: Resource not accessible by personal access token

Solution:

• Ensure your token has required scopes (repo, workflow, admin:org, etc.)
• Re-run gh auth refresh -h github.com -s <scope> to add scopes
• Check if you're a member of the organization/repository

Repository Access Denied

Error: HTTP 404: Not Found (when repo exists)

Possible Causes:

1. Repository is private and you don't have access 2. Repository name is incorrect 3. You're authenticated with wrong account

Solution:

# Verify repository access
gh repo view owner/repo

# Check if you're using correct repo name
gh repo list owner --limit 100 | grep repo-name

# Verify authentication
gh auth status

Cannot Push to Repository

Error: Permission to owner/repo denied to user

Solution:

# Check if you have write access
gh api repos/owner/repo --jq '.permissions'

# Verify git remote uses correct authentication
gh auth setup-git

# Check remote URL
git remote -v

Rate Limiting

API Rate Limit Exceeded

Error: API rate limit exceeded for user

Solution:

# Check rate limit status
gh api rate_limit

# Use authenticated requests (higher limit: 5000/hr vs 60/hr)
gh auth login

# Wait for rate limit reset or use conditional requests
gh api rate_limit --jq '.rate.reset' | xargs -I {} date -r {}

Secondary Rate Limit

Error: You have exceeded a secondary rate limit

Solution:

• Slow down request rate
• Add delays between API calls
• Use --paginate carefully with large result sets

Common Command Errors

PR Already Exists

Error: pull request create failed: a pull request for branch "feature" into branch "main" already exists

Solution:

# Find existing PR
gh pr list --head feature

# Update existing PR instead
gh pr edit <number> --title "New title" --body "New description"

# Or checkout and update the branch
gh pr checkout <number>
git commit --amend
git push --force-with-lease

Cannot Merge PR

Error: GraphQL: Pull Request is not mergeable

Causes & Solutions:

• Merge conflicts:

  gh pr checkout <number>
  git merge main  # or base branch
  # Resolve conflicts
  git push

• Required checks failing:

  gh pr checks <number>  # View status
  # Wait for checks or fix failures

• Required reviews missing:

  gh pr view <number> --json reviewDecision
  # Get required approvals

• Branch protection:

  gh api repos/:owner/:repo/branches/main/protection
  # Ensure all rules are satisfied

Workflow Not Found

Error: could not resolve to a Workflow

Solution:

# List available workflows
gh workflow list

# Use exact workflow file name (not display name)
gh workflow run ci.yml  # not "CI" or "ci"

# Use workflow ID
gh api repos/:owner/:repo/actions/workflows --jq '.workflows[] | "\(.id): \(.name)"'
gh workflow run <workflow-id>

Cannot Checkout PR

Error: failed to check out PR: could not find a branch for this pull request

Solution:

# Fetch PR branch manually
gh pr view <number> --json headRefName,headRepository --jq '.headRefName'

# Checkout with fetch
git fetch origin pull/<number>/head:pr-<number>
git checkout pr-<number>

Issue/PR Not Found

Error: could not resolve to a PullRequest/Issue with the number of <number>

Solution:

# Verify you're in correct repository
gh repo view

# Set default repository
gh repo set-default owner/repo

# Specify repository explicitly
gh pr view <number> --repo owner/repo

Installation Issues

gh Command Not Found

Solutions:

# macOS with Homebrew
brew install gh

# Update Homebrew if gh is outdated
brew upgrade gh

# Update PATH (if installed but not in PATH)
export PATH="/opt/homebrew/bin:$PATH"

# Verify installation
which gh
gh --version

Extension Installation Fails

Error: failed to install extension

Solution:

# Check extension name is correct
gh extension search <keyword>

# Install with full repository path
gh extension install owner/gh-extension-name

# Update existing extension
gh extension upgrade extension-name

# Reinstall if corrupted
gh extension remove extension-name
gh extension install owner/gh-extension-name

Upgrade Issues

Error: failed to upgrade gh

Solution:

# macOS
brew upgrade gh

# Check for conflicts
brew doctor

# Reinstall if needed
brew reinstall gh

Configuration Issues

Default Repository Not Set

Error: no default repository has been set

Solution:

# Set default repository interactively
gh repo set-default

# Set default repository explicitly
gh repo set-default owner/repo

# Or use --repo flag
gh pr list --repo owner/repo

Editor Not Opening

Problem: gh pr create doesn't open editor

Solution:

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

# Or use EDITOR environment variable
export EDITOR=vim

Git Protocol Issues

Error: Issues with SSH/HTTPS

Solution:

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

# Setup git credentials
gh auth setup-git

Debugging Tips

Enable Verbose Output

# Debug mode - shows API calls
GH_DEBUG=api gh pr list

# Trace OAuth flow
GH_DEBUG=oauth gh auth login

# Full debugging
GH_DEBUG=api,oauth gh <command>

Check Configuration

# View current config
gh config list

# Check git remotes
git remote -v

# Verify default repository
gh repo view

# Check authentication
gh auth status

Inspect JSON Output

# Get full JSON response
gh pr view <number> --json

# Pretty print with jq
gh pr view <number> --json | jq .

# Inspect specific fields
gh pr view <number> --json state,title,number

Clear Cache

# If experiencing odd behavior, re-authenticate to refresh state
gh auth logout
gh auth login

# Or restart gh by closing all terminals and reopening
# Note: Cache will be automatically refreshed on next use

Network Issues

Connection Timeout

Error: dial tcp: i/o timeout

Solution:

# Check network connectivity
ping github.com

# Test GitHub API
curl -I https://api.github.com

# Use different network or VPN
# Check firewall/proxy settings

SSL Certificate Issues

Error: x509: certificate signed by unknown authority

Solution:

# Update ca-certificates
# macOS
brew install ca-certificates

# Set custom CA bundle if needed
export GH_CA_BUNDLE=/path/to/ca-bundle.crt

Getting Additional Help

Built-in Help

# Command-specific help
gh pr create --help
gh pr --help
gh --help

# View manual pages
man gh
man gh-pr

Check Version

# Current version
gh --version

# Check for updates
gh extension upgrade gh
brew upgrade gh  # macOS

Community Resources

• Official Manual: https://cli.github.com/manual
• GitHub CLI Repository: https://github.com/cli/cli
• Discussions: https://github.com/cli/cli/discussions
• Report Bugs: https://github.com/cli/cli/issues
• Stack Overflow: Tag github-cli

Common Error Codes

• 401: Authentication failed
• 403: Forbidden / insufficient permissions
• 404: Not found / no access
• 422: Validation failed / malformed request
• 500: GitHub server error

Workflows & Actions

Comprehensive guide for managing GitHub Actions workflows and runs using gh CLI.

Viewing Workflows

# List workflows
gh workflow list

# View workflow runs
gh run list

# View specific run
gh run view 789

# Watch run
gh run watch 789

# View run logs
gh run view 789 --log

Managing Workflows

# Trigger workflow
gh workflow run workflow.yml

# Cancel run
gh run cancel 789

# Rerun workflow
gh run rerun 789

# Download artifacts
gh run download 789

Workflow Runs

Advanced commands for managing workflow runs.

List and View Runs

# List recent workflow runs
gh run list

# List runs for specific workflow
gh run list --workflow=ci.yml

# List runs on specific branch
gh run list --branch=main

# List failed runs only
gh run list --status=failure

# Limit number of results
gh run list --limit=10

# View specific run details
gh run view 123456

# View run with logs
gh run view 123456 --log

# View run and open in browser
gh run view 123456 --web

# View specific job in a run
gh run view 123456 --job=123

# View run with exit status (also works with --log and --log-failed)
gh run view 123456 --exit-status
gh run view 123456 --log --exit-status
gh run view 123456 --log-failed --exit-status

Monitor and Control Runs

# Watch a run in real-time
gh run watch 123456

# Watch with interval (default 3s)
gh run watch 123456 --interval=5

# Cancel running workflow
gh run cancel 123456

# Force cancel (skip confirmation)
gh run cancel 123456 --force

# Rerun failed jobs only
gh run rerun 123456 --failed

# Rerun all jobs in a workflow run
gh run rerun 123456

# Rerun specific job
gh run rerun 123456 --job=123

Download Artifacts

# Download all artifacts from a run
gh run download 123456

# Download specific artifact by name
gh run download 123456 --name artifact-name

# Download to specific directory
gh run download 123456 --dir ./downloads

# Download artifacts from latest run
gh run download

# Download artifacts from specific workflow
gh run download --name=build-artifacts

Workflow Dispatch

Trigger workflows with custom inputs. Since v2.87, gh workflow run immediately returns the workflow run URL.

# Trigger workflow with inputs
gh workflow run deploy.yml -f environment=production -f version=v1.2.3

# Trigger workflow on specific branch
gh workflow run ci.yml --ref feature-branch

# Trigger workflow - the run URL is printed immediately
gh workflow run ci.yml

GitHub Actions Cache

Manage GitHub Actions cache to optimize workflow performance.

# List caches in repository
gh cache list

# List caches for specific branch
gh cache list --ref refs/heads/main

# List caches with specific key
gh cache list --key npm-cache

# Sort caches by size
gh cache list --sort size

# Limit number of results
gh cache list --limit 10

CI/CD Integration Patterns

Trigger Workflow and Wait

# Trigger workflow - the run URL is returned immediately (v2.87+)
gh workflow run ci.yml --ref main

# Trigger and watch in one go (extract run ID from the returned URL)
RUN_URL=$(gh workflow run ci.yml --ref main 2>&1 | grep -oE 'https://[^ ]+')
RUN_ID=$(echo "$RUN_URL" | grep -oE '[0-9]+$')
gh run watch "$RUN_ID"

Check CI Status Before Merge

# Check all checks pass before merging
gh pr checks 123 && gh pr merge 123 --squash

# Wait for checks to complete
gh pr checks 123 --watch && gh pr merge 123 --squash

# Check specific required checks
gh pr view 123 --json statusCheckRollup --jq '.statusCheckRollup[] | select(.conclusion != "SUCCESS")'

Auto-merge on Success

# Enable auto-merge when checks pass
gh pr merge 123 --auto --squash

# Enable auto-merge with specific merge method
gh pr merge 123 --auto --merge
gh pr merge 123 --auto --rebase

# Disable auto-merge
gh pr merge 123 --disable-auto

Monitor Multiple Workflows

# Watch all active workflow runs
gh run list --status=in_progress --json databaseId,name,headBranch | \
  jq -r '.[] | "\(.databaseId) - \(.name) on \(.headBranch)"'

# Check status of all workflows for current commit
COMMIT=$(git rev-parse HEAD)
gh run list --commit=$COMMIT --json status,conclusion,name

Workflow Run Analytics

# Get average duration for workflow
gh run list --workflow=ci.yml --limit=50 --json createdAt,updatedAt,conclusion | \
  jq '[.[] | select(.conclusion == "success") |
    ((.updatedAt | fromdateiso8601) - (.createdAt | fromdateiso8601))] |
    add / length / 60'

# Count failed runs in last 30 days
gh run list --created=">=$(date -v-30d +%Y-%m-%d)" --status=failure --json id | jq '. | length'

# List slowest workflow runs
gh run list --workflow=ci.yml --limit=20 --json databaseId,createdAt,updatedAt,conclusion | \
  jq 'sort_by((.updatedAt | fromdateiso8601) - (.createdAt | fromdateiso8601)) | reverse | .[:5]'

Conditional Workflow Execution

# Trigger workflow only if tests pass locally
npm test && gh workflow run deploy.yml -f environment=staging

# Chain workflows
gh workflow run build.yml && \
  sleep 10 && \
  gh run watch $(gh run list --workflow=build.yml --limit 1 -q '.[0].databaseId') && \
  gh workflow run deploy.yml

Retrieve Workflow Job Logs

# Download logs for a specific run
gh run view 123456 --log > workflow-logs.txt

# Download logs for failed jobs only
gh run view 123456 --log-failed > failed-jobs.txt

# View logs for specific job
gh api repos/:owner/:repo/actions/jobs/JOB_ID/logs > job.log

Advanced Workflow Management

Using JSON Output for Scripting

# Get workflow run details as JSON
gh run view 123456 --json status,conclusion,startedAt,url

# Parse specific fields
gh run view 123456 --json conclusion -q '.conclusion'

# List all failed runs with details
gh run list --status=failure --json databaseId,name,headBranch,conclusion,createdAt

# Get workflow run URL programmatically
gh run view 123456 --json url -q '.url'

Workflow Environment Secrets

# List repository secrets (requires admin access)
gh secret list

# Set a secret
gh secret set SECRET_NAME < secret.txt
gh secret set SECRET_NAME --body "secret-value"

# List organization secrets
gh secret list --org organization-name

Workflow Variables

# List repository variables
gh variable list

# Set a variable
gh variable set VAR_NAME --body "value"

Troubleshooting

Debug Failed Runs

# View failed run with logs
gh run view 123456 --log-failed

# List failed jobs in a run
gh run view 123456 --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name, conclusion}'

# Rerun failed jobs with debug logging
gh run rerun 123456 --failed --debug

Check Workflow File Syntax

# View workflow file
gh workflow view ci.yml

# Download workflow file
gh api repos/:owner/:repo/contents/.github/workflows/ci.yml --jq '.content' | base64 -d

# List all workflow files
gh api repos/:owner/:repo/contents/.github/workflows --jq '.[] | .name'

Best Practices

01. Use specific workflow names when triggering or listing runs to avoid ambiguity 02. Enable auto-merge for PRs to merge automatically when CI passes 03. Monitor workflow cache regularly to prevent cache bloat 04. Use JSON output for scripting and automation 05. Watch runs interactively during development to catch failures quickly 06. Clean up old workflow runs to keep repository tidy 07. Use workflow dispatch inputs for flexible, reusable workflows 08. Set appropriate timeouts to prevent workflows from running indefinitely 09. Use artifacts judiciously - they count against storage limits 10. Leverage caching to speed up workflows and reduce costs