github

GitHub CLI 技能

快速开始

身份验证

# Interactive authentication (recommended)
gh auth login

# Check authentication status
gh auth status

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

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

配置

# Set default editor
gh config set editor "code --wait"

# Set default browser
gh config set browser "firefox"

# Set default git protocol
gh config set git_protocol ssh

# View all settings
gh config list

基本命令（按常用程度排序）

1. 问题

# Create issue
gh issue create --title "Bug: something broken" --body "Description here"

# Create with labels
gh issue create --title "Feature request" --label "enhancement,priority:high"

# List issues
gh issue list                    # Open issues
gh issue list --state all        # All issues
gh issue list --assignee @me     # Assigned to me
gh issue list --label "bug"      # By label

# View issue
gh issue view 123                # By number
gh issue view 123 --comments     # With comments

# Edit issue
gh issue edit 123 --title "New title"
gh issue edit 123 --add-label "in-progress"
gh issue edit 123 --assignee username

# Close/reopen
gh issue close 123
gh issue close 123 --comment "Fixed in PR #456"
gh issue reopen 123

# Comment
gh issue comment 123 --body "This is a comment"

2. 拉取请求

# Create PR
gh pr create --title "Feature: new thing" --body "Description"
gh pr create --draft                       # Create as draft
gh pr create --fill                        # Auto-fill from commits

# List PRs
gh pr list                        # Open PRs
gh pr list --state merged         # Merged PRs
gh pr list --author @me           # My PRs
gh pr list --search "review:required"

# View PR
gh pr view 123                    # By number
gh pr view                        # Current branch PR
gh pr diff 123                    # View diff
gh pr checks 123                  # View CI status

# Review PRs
gh pr review 123 --approve
gh pr review 123 --request-changes --body "Please fix X"
gh pr review 123 --comment --body "Looks good overall"

# Merge
gh pr merge 123                   # Interactive
gh pr merge 123 --squash          # Squash merge
gh pr merge 123 --rebase          # Rebase merge
gh pr merge 123 --auto            # Auto-merge when checks pass

# Mark ready
gh pr ready 123                   # Convert draft to ready

# Comment
gh pr comment 123 --body "Comment text"

# Close
gh pr close 123

3. 仓库

# Clone
gh repo clone owner/repo
gh repo clone owner/repo -- --depth 1   # Shallow clone

# Create
gh repo create my-repo --public
gh repo create my-repo --private --clone

# View
gh repo view                      # Current repo
gh repo view owner/repo           # Specific repo
gh repo view --web                # Open in browser

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

# Sync fork
gh repo sync                      # Sync fork with upstream

# List repos
gh repo list                      # Your repos
gh repo list owner                # Organization repos

4. 工作流（GitHub Actions）

# List workflows
gh workflow list

# View workflow runs
gh run list                       # Recent runs
gh run list --workflow ci.yml     # By workflow
gh run list --status failure      # Failed runs

# View run details
gh run view 123456                # By run ID
gh run view 123456 --log          # With logs
gh run view 123456 --log-failed   # Only failed logs

# Trigger workflow
gh workflow run ci.yml
gh workflow run ci.yml -f param=value

# Watch run
gh run watch                      # Watch current branch run
gh run watch 123456               # Watch specific run

# Cancel/rerun
gh run cancel 123456
gh run rerun 123456
gh run rerun 123456 --failed      # Rerun only failed jobs

5. 搜索

# Search issues/PRs
gh search issues "bug in:title"
gh search issues "label:bug state:open"
gh search prs "author:username is:merged"

# Search repos
gh search repos "language:python stars:>1000"

# Search code
gh search code "function handleError"
gh search code "filename:config.json org:myorg"

高级命令

发行版

# Create release
gh release create v1.0.0 --title "Version 1.0" --notes "Release notes"
gh release create v1.0.0 --generate-notes   # Auto-generate notes
gh release create v1.0.0 ./dist/*           # Upload assets

# List/view
gh release list
gh release view v1.0.0

# Download assets
gh release download v1.0.0
gh release download v1.0.0 --pattern "*.zip"

Gist

# Create gist
gh gist create file.txt
gh gist create --public file.txt
gh gist create -d "Description" file1.txt file2.txt

# List/view
gh gist list
gh gist view gist_id

# Edit
gh gist edit gist_id

API 访问

# GraphQL query
gh api graphql -f query='{ viewer { login } }'

# REST API
gh api repos/owner/repo/issues
gh api repos/owner/repo/issues --method POST -f title="Issue title"

# Paginate
gh api repos/owner/repo/issues --paginate

SSH 密钥和 GPG

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

# GPG keys
gh gpg-key add key.asc
gh gpg-key list

常见模式

从问题到拉取请求的工作流

# 1. Create issue
gh issue create --title "Feature: X" --label "enhancement"
# Returns issue #123

# 2. Create branch and work
git checkout -b feat/issue-123-x

# 3. Create PR linking to issue
gh pr create --title "Feature: X" --body "Closes #123"

代码审查流程

# Check out PR locally
gh pr checkout 456

# Run tests, review code...

# Approve or request changes
gh pr review 456 --approve --body "LGTM!"

CI 故障调查

# List failed runs
gh run list --status failure

# Get logs
gh run view RUN_ID --log-failed

# Rerun after fix
gh run rerun RUN_ID

重新启用 GitHub MCP 服务

如果需要完整的 GitHub MCP 服务来执行高级操作（例如，复杂的 GraphQL 查询、批量操作），可以提出请求：

“请使用 GitHub MCP 服务”或“重新启用 GitHub MCP”

手动重新启用：

1. 编辑 ~/.copilot/github-copilot/mcp.json
2. 移除 github-mcp-server，或将其 "disabled": false：

{
  "mcpServers": {
    "github-mcp-server": {
      "disabled": false
    }
  }
}

3. 重启 Copilot CLI 会话

何时使用 MCP，何时使用 gh CLI：

使用 gh CLI	使用 GitHub MCP
标准的问题/拉取请求操作	复杂的多步骤 GitHub 操作
CI/CD 工作流管理	跨多个仓库的批量操作
快速查询和状态检查	高级 GraphQL 查询
脚本自动化	需要持久状态的操作
大多数日常 GitHub 交互	少见的专用 GitHub 集成

故障排除

# Check auth
gh auth status

# Refresh token
gh auth refresh

# Clear cache
gh cache delete --all

# Debug mode
GH_DEBUG=api gh issue list

环境变量

GH_TOKEN           # Auth token (alternative to gh auth)
GH_HOST            # Default host (for enterprise)
GH_REPO            # Default repo (owner/repo format)
GH_EDITOR          # Editor for interactive commands
GH_BROWSER         # Browser for --web commands
GH_DEBUG           # Enable debug output (api, oauth)
NO_COLOR           # Disable colored output