用途:帮助在编写、调试或配置对 GitHub 的认证时,选择合适的凭证类型,并读懂认证失败信息。不同凭证的权限模型、影响范围和报错各不相同,选错是脚本在 CI 中失败的常见原因。
主要能力:梳理并对比各类凭证——经典 PAT、细粒度 PAT、GitHub App 安装令牌、GitHub App 用户访问令牌、OAuth App 令牌、GITHUB_TOKEN、OIDC(id-token)、SSH 密钥、部署密钥,说明各自的身份、有效期、权限范围与适用场合。
选择建议:在 GitHub Actions 内访问 GitHub 用 GITHUB_TOKEN 并收窄 permissions:;访问云服务商用 OIDC,不存云密钥;需跨仓库访问用 GitHub App 安装令牌。Actions 之外:长期自动化用安装令牌,代表某用户用 App 用户令牌,本地开发或本地智能体用最小权限的细粒度 PAT。任何长于单次会话的场景优先用 GitHub App 而非 PAT。
必要用法:在 workflow 中显式声明 permissions:,例如工作流级 contents: read,任务级再收窄为 contents: write 和 id-token: write。
限制与注意:GITHUB_TOKEN 不能触发后续工作流;fork PR 在 pull_request 下只有只读令牌且无密钥;pull_request_target 不要与检出 PR 头组合。细粒度 PAT 并非经典 PAT 的超集,部分端点仍须经典令牌,组织资源需组织启用并可能逐令牌审批。报错解读:401 为令牌错误或过期;403 常指缺权限;已知存在的仓库返回 404 多为未授权;SAML 强制需 SSO 授权;本地成功而 Actions 中 403 多为 permissions: 问题。SSH 与 API 分离,SSH 不能调 API。凭证不得写入源码或配置,本地用系统凭证助手或 gh auth login。具体检测与降级模式参见 ../commands/setup.md。