排查存储库身份验证问题

了解如何排查在 codespace 中克隆、推送到存储库或从该存储库中执行拉取操作时常见的身份验证问题。

本文内容

为存储库创建 codespace 时，通常可以使用 git pull 和 git push 拉取更改并将其推送到该存储库，而无需任何其他身份验证。 但是，在尝试执行这些操作时，有时可能会看到身份验证错误。

如果尝试进行交互的存储库不是从中创建 codespace 的存储库，也可能会遇到错误。

向从中创建 codespace 的存储库进行身份验证

如果向从中创建 codespace 的存储库推送或从该存储库中拉取更改，但身份验证失败，可能会看到 git@github.com: Permission denied (publickey) 或 Host key verification failed 等错误。

如果将 dotfiles 存储库与 GitHub Codespaces 配合使用，并且已将 Git 配置为使用 HTTPS 以外的协议将数据传输到远程存储库，则可能会看到这些错误。 例如，你可能已将 Git 配置为使用 SSH，方法是在 dotfiles 的配置文件中包含如下行。

[url "git@github.com:"]
  insteadOf = https://github.com/

GitHub Codespaces 默认使用 HTTPS 协议，并使用配置了对从中创建 codespace 的存储库的读取和写入访问权限的 GITHUB_TOKEN 进行身份验证。 建议在 codespace 中使用默认 HTTPS 和 GITHUB_TOKEN。 GITHUB_TOKEN 的权限通常仅限于一个存储库，遵循最小特权的安全原则。 SSH 身份验证没有细化的存储库权限，因此意外泄露 SSH 密钥可能会使某人能够访问你的所有存储库。

若要使用默认 HTTPS，请从 dotfiles 中删除冲突的配置。 如果 dotfiles 存储库在识别的文件（如 install.sh）中包含安装脚本，则可以使用如下所示的逻辑来排除 codespace 中的配置。

if [ -z "$CODESPACES" ]; then
  git config --global url."git@github.com".insteadOf "https://github.com"
fi

如果在从信任的存储库创建的 codespace 中工作，并且需要使用 SSH，请确保将 codespace 设置为使用链接到 GitHub 帐户的 SSH 密钥进行身份验证。 有关详细信息，请参阅“生成新的 SSH 密钥并将其添加到 ssh-agent”。

向未从中创建 codespace 的存储库进行身份验证

codespace 中的 GITHUB_TOKEN 配置了对从中创建 codespace 的存储库的读取和写入访问权限。 默认情况下，该令牌无权访问其他存储库。 你可能会发现无法克隆存储库，或者无法推送到已克隆的存储库。

不建议在 codespace 中手动更新 GITHUB_TOKEN 的值。 如果项目需要具有对其他存储库的访问权限，可以通过列举其他权限在开发容器配置中授予对这些存储库的 codespace 访问权限。 这将允许用户在创建 codespace 时授权其他权限。 但是，它不会更改现有 codespace 的权限。 有关详细信息，请参阅“管理对代码空间中其他存储库的访问权限”。

如果你需要访问现有 codespace 中的其他存储库，或者所需的权限特定于你，并且不适用于其他参与者，则可以创建具有存储库访问权限的 personal access token，并将令牌添加到 codespace。 建议使用 fine-grained personal access token 限制令牌的访问，仅选择需要访问的存储库，并仅授予对“内容”权限所需的访问权限。 有关详细信息，请参阅“管理个人访问令牌”。

然后，你可以将令牌添加为 codespace 中的环境变量，或添加为 GitHub Codespaces 的机密。 如果创建机密，则应仅允许某些受信任的存储库访问该机密。 当你添加新的机密时，系统会提示你重新加载现有 codespace 以拉取新机密。 有关详细信息，请参阅“管理 GitHub Codespaces 特定于帐户的机密”。

若要在 codespace 中使用令牌进行身份验证，可以使用以下选项。

  • 创建环境变量或机密时，可以使用名称 GH_TOKEN。 默认情况下，GH_TOKEN 变量在 GitHub CLI 操作中使用，因此可以使用命令 gh repo clone OWNER/REPO 克隆存储库。

    但是，如果随后尝试使用 git push 向存储库推送更改，Git 的凭据帮助程序将尝试使用现有的 GITHUB_TOKEN 进行身份验证，并且身份验证将失败。 可以替代帮助程序，但在尝试与从中创建 codespace 的原始存储库进行交互时，这可能会产生摩擦。

  • 可以使用包含访问令牌的 URL 克隆存储库。 将 YOUR-VARIABLE 替换为环境变量的名称或你创建的机密。

    git clone https://USERNAME:$YOUR-VARIABLE@github.com/OWNER/REPO`

    这将存储特定存储库的访问令牌，因此无需替代现有凭据帮助程序即可向存储库推送并从中拉取更改。

    注意：如果以这种方式克隆，则令牌将在 Git 配置中可见。 仅当在从信任的存储库创建的 codespace 中工作时，才应使用此方法，并且应尽可能地限制访问令牌的范围。