--- name: github-cli description: "Comprehensive GitHub CLI (gh) reference. Covers repos, issues, PRs, Actions, releases, gists, search, projects v2, API, secrets/variables, labels, codespaces, extensions, auth, and advanced GraphQL patterns." metadata: { "openclaw": { "emoji": "🐙", "requires": { "bins": ["gh"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "gh", "bins": ["gh"], "label": "Install GitHub CLI (brew)", }, { "id": "apt", "kind": "apt", "package": "gh", "bins": ["gh"], "label": "Install GitHub CLI (apt)", }, ], }, } ---

GitHub CLI (gh) — Comprehensive Skill

Version: gh 2.66.1+ Auth: gh auth login or set GH_TOKEN env var Always use --repo OWNER/REPO (or -R) when not inside a git repo directory.

---

Table of Contents

1. Authentication & Config
2. Repositories
3. Issues
4. Pull Requests
5. GitHub Actions (Runs & Workflows)
6. Releases
7. Gists
8. Search
9. Labels
10. Secrets & Variables
11. Caches
12. Projects V2
13. API (REST & GraphQL)
14. Extensions
15. Codespaces
16. Copilot
17. Other Commands
18. JSON Output & Formatting
19. Environment Variables
20. Advanced Patterns
21. Tips & Gotchas

---

1. Authentication & Config

Auth

# Interactive login (browser-based OAuth)
gh auth login

# Login with a PAT from stdin
echo "$MY_TOKEN" | gh auth login --with-token

# Login to GitHub Enterprise
gh auth login --hostname enterprise.example.com

# Add extra scopes (e.g., project scope for Projects V2)
gh auth refresh -s project

# Add delete_repo scope
gh auth refresh -s delete_repo

# Check auth status (shows active account, scopes, token validity)
gh auth status
gh auth status --show-token

# Switch active account (when multiple accounts configured)
gh auth switch

# Print the active token (useful for piping to other tools)
gh auth token

# Logout
gh auth logout

Required scopes by feature: | Feature | Scope needed | |---------|-------------| | Basic repo/PR/issue ops | repo | | Gists | gist | | Read org membership | read:org | | Projects V2 | project | | Delete repos | delete_repo | | Actions workflows | workflow | | Read user profile | user |

Config

# List all config
gh config list

# Get/set individual values
gh config get git_protocol        # https or ssh
gh config set git_protocol ssh
gh config set editor "code --wait"
gh config set pager "less -R"
gh config set prompt disabled     # disable interactive prompts (good for scripts)
gh config set browser "firefox"

# Clear CLI cache
gh config clear-cache

Git credential setup

# Configure git to use gh for HTTPS auth
gh auth setup-git

---

2. Repositories

Create

# Interactive
gh repo create

# Public repo, clone locally
gh repo create my-project --public --clone

# In an org
gh repo create my-org/my-project --private

# From local directory
gh repo create my-project --private --source=. --remote=upstream --push

# From template
gh repo create my-project --template owner/template-repo --clone

# With options
gh repo create my-project --public --description "My project" \
  --license mit --gitignore Node --add-readme

Clone

gh repo clone owner/repo
gh repo clone owner/repo my-dir
gh repo clone owner/repo -- --depth=1    # shallow clone

# Clone your own repo (owner defaults to you)
gh repo clone my-repo

Fork

# Fork current repo
gh repo fork

# Fork and clone
gh repo fork owner/repo --clone

# Fork into an org
gh repo fork owner/repo --org my-org --fork-name new-name

# Fork default branch only
gh repo fork owner/repo --default-branch-only

View

# View current repo (README + description)
gh repo view
gh repo view owner/repo

# Open in browser
gh repo view --web

# JSON output
gh repo view --json name,description,stargazerCount,url
gh repo view --json name,stargazerCount --jq '.stargazerCount'

JSON fields for repo: archivedAt, assignableUsers, codeOfConduct, createdAt, defaultBranchRef, deleteBranchOnMerge, description, diskUsage, forkCount, hasDiscussionsEnabled, hasIssuesEnabled, hasProjectsEnabled, hasWikiEnabled, homepageUrl, id, isArchived, isEmpty, isFork, isPrivate, isTemplate, languages, latestRelease, licenseInfo, name, nameWithOwner, owner, parent, primaryLanguage, pullRequests, pushedAt, sshUrl, stargazerCount, updatedAt, url, visibility, watchers

List

# Your repos
gh repo list
gh repo list --limit 100

# Another user/org's repos
gh repo list my-org

# Filter
gh repo list --language go --visibility public
gh repo list --topic cli --no-archived
gh repo list --fork        # only forks
gh repo list --source      # only non-forks

# JSON output
gh repo list --json name,stargazerCount --jq '.[] | "\(.name): \(.stargazerCount) stars"'

Edit

# Edit settings
gh repo edit --description "New description"
gh repo edit --homepage "https://example.com"
gh repo edit --enable-issues --enable-wiki
gh repo edit --enable-projects=false
gh repo edit --default-branch main
gh repo edit --enable-auto-merge
gh repo edit --delete-branch-on-merge
gh repo edit --add-topic "cli,automation"
gh repo edit --remove-topic "old-topic"
gh repo edit --template    # make it a template repo

# Change visibility (DANGEROUS — requires acknowledgment)
gh repo edit --visibility public --accept-visibility-change-consequences

Delete / Archive

gh repo delete owner/repo --yes          # requires delete_repo scope
gh repo archive owner/repo --yes
gh repo unarchive owner/repo --yes

Rename

gh repo rename new-name                  # renames current repo
gh repo rename new-name -R owner/repo

Set Default

# Set which remote is used for gh commands in this local clone
gh repo set-default owner/repo
gh repo set-default --view     # see current default
gh repo set-default --unset

Sync (Fork ↔ Upstream)

# Sync local repo from remote parent
gh repo sync

# Sync specific branch
gh repo sync --branch v1

# Sync remote fork from its parent
gh repo sync owner/my-fork

# Sync from a specific source
gh repo sync owner/repo --source owner2/repo2

# Force sync (hard reset)
gh repo sync --force

---

3. Issues

Create

gh issue create --title "Bug report" --body "Description here"
gh issue create --title "Bug" --label "bug,urgent" --assignee "@me"
gh issue create --title "Feature" --project "Roadmap" --milestone "v2.0"
gh issue create --template "Bug Report"       # use issue template
gh issue create --body-file description.md    # body from file
gh issue create -R owner/repo --title "Bug"   # different repo

List

gh issue list
gh issue list --state closed
gh issue list --state all --limit 100
gh issue list --label "bug" --assignee "@me"
gh issue list --author monalisa
gh issue list --milestone "v2.0"
gh issue list --search "error no:assignee sort:created-asc"

# JSON output
gh issue list --json number,title,labels,state --jq '.[] | "#\(.number) \(.title)"'

JSON fields for issues: assignees, author, body, closed, closedAt, comments, createdAt, id, isPinned, labels, milestone, number, projectCards, projectItems, reactionGroups, state, stateReason, title, updatedAt, url

View

...