SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场gh-cli-setup

gh-cli-setup

编程与开发

查看项目

更新于 10-15 08:07

技能介绍

用途

本技能用于诊断和修复 GitHub CLI（gh）在安装、配置和认证方面的问题。适用场景包括：gh 命令未找到、出现认证错误、gh CLI 行为异常、需要检查 gh CLI 配置以及首次设置 gh CLI。

快速诊断

可运行以下命令检查状态：

# 检查 gh 是否已安装
which gh

# 检查 gh 版本
gh --version

# 检查认证状态
gh auth status

# 列出已认证账号
gh auth status --show-token

安装

按平台提供以下安装命令。

macOS：

  • 使用 Homebrew（推荐）：brew install gh
  • 使用 MacPorts：sudo port install gh
  • 使用 Conda：conda install gh --channel conda-forge

Linux：

  • Debian/Ubuntu/Raspbian：
# 添加 GitHub CLI 软件源
type -p curl >/dev/null || (sudo apt update && sudo apt install curl -y)
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/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
  • Fedora/CentOS/RHEL：sudo dnf install gh
  • Arch Linux：sudo pacman -S github-cli
  • 使用 Snap：sudo snap install gh
  • 使用 Conda：conda install gh --channel conda-forge

Windows：

  • 使用 WinGet：winget install --id GitHub.cli
  • 使用 Scoop：scoop install gh
  • 使用 Chocolatey：choco install gh
  • 使用 Conda：conda install gh --channel conda-forge
  • 手动下载：从 https://cli.github.com/ 下载 MSI 安装程序

认证

交互式认证（推荐）：

gh auth login

该命令将提示你选择 GitHub.com 或 GitHub Enterprise Server、选择认证方式（Web 浏览器或 Token）并完成认证流程。

Token 认证：

# 在以下地址创建 token：https://github.com/settings/tokens
# 所需 scope：repo、read:org、workflow

# 使用 token 认证
gh auth login --with-token < token.txt

# 或在提示时粘贴 token
gh auth login

检查认证：

# 验证认证状态
gh auth status

# 查看已认证用户
gh api user --jq '.login'

# 测试 API 访问
gh api rate_limit

常见错误与解决方案

  • "gh: command not found"：原因 gh CLI 未安装或不在 PATH 中。检查 which gh；若未找到则按上文安装；若已安装但不在 PATH，可加入 ~/.bashrc 或 ~/.zshrc：export PATH="/path/to/gh/bin:$PATH"。
  • "authentication required"：原因未登录 GitHub。解决：gh auth login 或 gh auth status。
  • "HTTP 403: Resource not accessible by integration"：原因 token 权限不足。解决：gh auth login --scopes repo,read:org,workflow，或在 https://github.com/settings/tokens 创建具有所需 scope 的新 token。
  • "HTTP 401: Bad credentials"：原因 token 过期或无效。解决：gh auth logout 然后 gh auth login。
  • "API rate limit exceeded"：原因 API 请求过多（未认证 60 次/小时，已认证 5000 次/小时）。解决：gh api rate_limit 查看、gh auth login 提高限额、等待重置或换账号。
  • "Could not resolve host: github.com"：原因网络连接问题。解决：ping github.com；若处于企业防火墙后，可设置代理 gh config set http_proxy http://proxy.example.com:8080；检查 DNS nslookup github.com。

配置

查看配置：

# 查看所有配置
gh config list

# 查看特定设置
gh config get git_protocol

常见设置：

# 设置默认协议（https 或 ssh）
gh config set git_protocol https

# 设置默认编辑器
gh config set editor vim

# 设置默认浏览器
gh config set browser firefox

# 设置代理
gh config set http_proxy http://proxy.example.com:8080

# 设置 GitHub Enterprise 主机
gh config set host github.enterprise.com

配置文件位置：

  • Linux/macOS：~/.config/gh/config.yml
  • Windows：%AppData%\GitHub CLI\config.yml

多账号：

# 登录多个主机
gh auth login --hostname github.com
gh auth login --hostname github.enterprise.com

# 在账号间切换
gh auth switch

# 检查当前活动账号
gh auth status

调试

启用调试模式：

# 带调试输出运行命令
GH_DEBUG=api gh search repos "test"

# 或对所有命令启用
export GH_DEBUG=api

查看请求/响应：

gh api repos/owner/repo --verbose

检查版本：

# 查看 gh 版本
gh --version

# 检查更新
gh extension upgrade --all

排查检查清单

当 gh CLI 无法工作时，按顺序检查：

  1. gh 是否已安装？（which gh）
  2. gh 是否在 PATH 中？（echo $PATH | grep gh）
  3. gh 是否已认证？（gh auth status）
  4. token 是否具有所需 scope？
  5. 网络连接是否正常？（ping github.com）
  6. 是否超出速率限制？（gh api rate_limit）
  7. gh 版本是否为最新？（gh --version）
  8. 配置是否正确？（gh config list）

获取帮助

# 获取任意命令的帮助
gh help
gh search --help
gh search repos --help

# 在线查看手册
# https://cli.github.com/manual/

搜索所需权限

不同搜索类型需要不同权限：

  • 公开仓库/issue/PR：无需认证（但受速率限制）
  • 私有仓库：需要 repo scope
  • 组织仓库：需要 read:org scope
  • 工作流文件：需要 workflow scope

Token Scope： 在 https://github.com/settings/tokens 创建 token。 搜索所需最小 scope：

  • public_repo：搜索公开仓库
  • repo：搜索私有仓库
  • read:org：搜索组织仓库

推荐 scope：

  • repo：完整仓库访问
  • read:org：组织访问
  • workflow：工作流访问
  • gist：Gist 访问

卸载

macOS：brew uninstall gh

Linux：

# Debian/Ubuntu
sudo apt remove gh

# Fedora/CentOS/RHEL
sudo dnf remove gh

# Arch
sudo pacman -R github-cli

Windows：

# WinGet
winget uninstall GitHub.cli

# Scoop
scoop uninstall gh

# Chocolatey
choco uninstall gh

相关

官方文档：https://cli.github.com/manual/ 安装指南：https://github.com/cli/cli#installation 认证指南：https://cli.github.com/manual/gh_auth_login 使用 gh search：gh-search-code、gh-search-commits、gh-search-issues、gh-search-prs、gh-search-repos