github-auth

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

github-auth

Authenticate to GitHub and diagnose auth failures. This is a verify and troubleshoot skill — the bundled

create_github_issues.py

already implements both auth methods, so you are not writing new auth code here. You are confirming a token works and the owner/repo point where the user expects, then unblocking the create/query skills ([[github-create-issues]], [[findings-to-github-issues]]).

GitHub accepts two credential styles. Pick A unless the user has a reason to use a PAT.

登录GitHub并诊断认证失败问题。这是一项验证与故障排查技能——配套的

create_github_issues.py

已实现两种认证方式，因此无需编写新的认证代码。你只需确认令牌可用、所有者/仓库指向用户预期的位置，即可解锁创建/查询类技能（[[github-create-issues]]、[[findings-to-github-issues]]）。

GitHub支持两种凭证方式。除非用户有使用PAT的理由，否则优先选择方式A。

Method A — gh CLI (recommended)

方式A——gh CLI（推荐）

Why preferred: no long-lived secret to store, and it rides the user's existing

gh

session.

gh auth token

returns a ready-to-use token.

powershell

gh auth login          # one-time setup
$token = gh auth token # get the current token

Use it as a bearer header:

Authorization: Bearer <token>

推荐理由：无需存储长期密钥，且可沿用用户现有的

gh

会话。

gh auth token

会返回可直接使用的令牌。

powershell

gh auth login          # 一次性设置
$token = gh auth token # 获取当前令牌

将其用作Bearer头：

Authorization: Bearer <token>

。

Method B — Personal Access Token (PAT)

方式B——个人访问令牌（PAT）

Use when

gh

CLI isn't available (e.g. a service context) or the user has an existing PAT. Scope must include Issues (Read & Write) on the target repo. Classic PAT or fine-grained PAT both work.

powershell

$env:GH_TOKEN = "<your-pat>"

create_github_issues.py

reads

GH_TOKEN

automatically; if unset it shells out to

gh auth token

. So setting (or unsetting)

GH_TOKEN

is how you switch methods.

当gh CLI不可用时（如服务环境）或用户已有PAT时使用。令牌权限范围必须包含目标仓库的**Issues（读&写）**权限。经典PAT和细粒度PAT均适用。

powershell

$env:GH_TOKEN = "<your-pat>"

create_github_issues.py

会自动读取

GH_TOKEN

；若未设置，则会调用

gh auth token

获取令牌。因此，设置（或取消设置）

GH_TOKEN

是切换认证方式的方法。

Set target repo

设置目标仓库

powershell

$env:GH_OWNER = "Cartagena365"   # org or user name — NOT a URL
$env:GH_REPO  = "GlassHull"     # repo name — NOT a URL

powershell

$env:GH_OWNER = "Cartagena365"   # 组织或用户名——请勿使用URL
$env:GH_REPO  = "GlassHull"     # 仓库名——请勿使用URL

Verify the credential works

验证凭证是否有效

powershell

gh api "repos/$env:GH_OWNER/$env:GH_REPO" --jq '.full_name'

A clean result (e.g.

Cartagena365/GlassHull

) proves the token is valid AND the repo exists and is reachable. Anything else, see the troubleshooting table below.

For a broader prereq sweep (gh CLI, Python, requests, openpyxl, env vars) run the bundled checker — it is read-only and changes nothing:

powershell

powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check_github.ps1"

powershell

gh api "repos/$env:GH_OWNER/$env:GH_REPO" --jq '.full_name'

返回清晰的结果（如

Cartagena365/GlassHull

）即证明令牌有效，且仓库存在并可访问。若出现其他情况，请查看下方的故障排查表。

如需全面检查前置条件（gh CLI、Python、requests、openpyxl、环境变量），可运行配套的检查器——该工具为只读模式，不会修改任何内容：

powershell

powershell -ExecutionPolicy Bypass -File "${CLAUDE_PLUGIN_ROOT}/scripts/setup_check_github.ps1"

Troubleshooting

故障排查

Symptom	Cause	Fix
HTTP 401 Unauthorized	No token, or it expired	`gh auth login` , then re-run `gh auth token` . For PAT: check it hasn't expired or been revoked.
HTTP 403 Forbidden	Token is valid but lacks rights	PAT scope missing Issues (Read & Write) — reissue with that scope. For fine-grained PAT: confirm the repo is included in the token's access list.
repo not found / 404	Wrong owner/repo name, or private repo the token can't see	Check `GH_OWNER` / `GH_REPO` spelling. For private repos: confirm the token/PAT has repo access.
"gh: command not found"	gh CLI not installed	Install from https://cli.github.com, then `gh auth login` . Or fall back to Method B ( `GH_TOKEN` ).
200 but wrong repo	Env vars point at the wrong place	Re-check `GH_OWNER` / `GH_REPO` — exact casing, exact repo name.

症状	原因	修复方案
HTTP 401 未授权	无令牌或令牌已过期	执行 `gh auth login` ，然后重新运行 `gh auth token` 。若使用PAT：检查令牌是否已过期或被撤销。
HTTP 403 禁止访问	令牌有效但权限不足	PAT缺少Issues（读&写）权限——重新生成包含该权限的令牌。若使用细粒度PAT：确认仓库已纳入令牌的访问列表。
仓库未找到 / 404	所有者/仓库名称错误，或令牌无法访问私有仓库	检查 `GH_OWNER` / `GH_REPO` 的拼写。若为私有仓库：确认令牌/PAT拥有仓库访问权限。
"gh: command not found"	未安装gh CLI	从https://cli.github.com安装，然后执行`gh auth login `。或改用方式B（` GH_TOKEN`）。
返回200但仓库错误	环境变量指向错误位置	重新检查 `GH_OWNER` / `GH_REPO` ——确保大小写准确、仓库名称完全匹配。

Hand-off

交接

Once

gh api repos/...

returns the full_name cleanly, auth is good — continue with [[github-create-issues]] or [[findings-to-github-issues]]. Leave

GH_OWNER

GH_REPO

set in the shell; they carry straight into all downstream skills.

当

gh api repos/...

清晰返回full_name后，即表示认证成功——可继续使用[[github-create-issues]]或[[findings-to-github-issues]]技能。保持

GH_OWNER

GH_REPO

在Shell中处于设置状态；它们会直接传递给所有下游技能。