使用 RubyGems 注册表

先决条件

• 您必须拥有 RubyGems 2.4.1 或更高版本。要查找您的 RubyGems 版本

  gem --version
  

• 您必须拥有 bundler 1.6.4 或更高版本。要查找您的 Bundler 版本

  $ bundle --version
  Bundler version 1.13.7
  

向 GitHub Packages 身份验证

您需要访问令牌才能发布、安装和删除私有、内部和公共包。

您可以使用个人访问令牌（经典版）向 GitHub Packages 或 GitHub API 进行身份验证。创建个人访问令牌（经典版）时，您可以根据需要为令牌分配不同的范围。有关个人访问令牌（经典版）的包相关范围的更多信息，请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流中向 GitHub Packages 注册表进行身份验证，您可以使用

• GITHUB_TOKEN 发布与工作流存储库关联的包。
• 至少具有 read:packages 范围的个人访问令牌（经典版）来安装与其他私有存储库关联的包（GITHUB_TOKEN 无法访问）。

在 GitHub Actions 工作流中进行身份验证

此注册表支持细粒度权限。对于支持细粒度权限的注册表，如果您的 GitHub Actions 工作流使用个人访问令牌向注册表进行身份验证，我们强烈建议您更新工作流以使用 GITHUB_TOKEN。有关更新使用个人访问令牌向注册表进行身份验证的工作流的指南，请参阅“使用 GitHub Actions 发布和安装包”。

如果令牌对程序包具有“管理员”权限，则可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN 通过 REST API 删除或还原程序包。使用工作流发布程序包的存储库以及明确连接到程序包的存储库会自动获得对存储库中程序包的“管理员”权限。

有关 GITHUB_TOKEN 的详细信息，请参阅“自动令牌身份验证”。有关在操作中使用注册表的最佳实践的详细信息，请参阅“GitHub Actions 的安全强化”。

您还可以选择独立地为 GitHub Codespaces 和 GitHub Actions 授予对程序包的访问权限。有关详细信息，请参阅“配置程序包的访问控制和可见性”和“配置程序包的访问控制和可见性”。

使用个人访问令牌进行身份验证

您必须使用具有适当范围的个人访问令牌（经典版）才能在 GitHub Packages 中发布和安装程序包。有关详细信息，请参阅“GitHub Packages 简介”。

要发布和安装 gem，您可以将 RubyGems 或 Bundler 配置为使用您的个人访问令牌向 GitHub Packages 进行身份验证。

要发布新 gem，您需要通过编辑 ~/.gem/credentials 文件来使用 RubyGems 向 GitHub Packages 进行身份验证，以包括您的个人访问令牌（经典版）。如果此文件不存在，请创建一个新的 ~/.gem/credentials 文件。

例如，您可以创建或编辑一个 ~/.gem/credentials 来包括以下内容，用您的个人访问令牌替换 TOKEN。

---
:github: Bearer TOKEN

要安装 gem，你需要通过更新 gem 源来向 GitHub Packages 进行身份验证，其中包括 https://USERNAME:[email protected]/NAMESPACE/。你必须替换

• USERNAME 为你的 GitHub 用户名。
• TOKEN 为你的个人访问令牌（经典）。
• NAMESPACE 为 gem 所属的个人帐户或组织的名称。

如果你希望你的软件包全局可用，则可以运行以下命令来将你的注册表添加为源。

gem sources --add https://USERNAME:[email protected]/NAMESPACE/

要通过 Bundler 进行身份验证，请将 Bundler 配置为使用你的个人访问令牌（经典），将 USERNAME 替换为你的 GitHub 用户名，将 TOKEN 替换为你的个人访问令牌，将 NAMESPACE 替换为 gem 所属的个人帐户或组织的名称。

bundle config https://rubygems.pkg.github.com/NAMESPACE USERNAME:TOKEN

发布软件包

当你首次发布软件包时，默认可见性为私有。要更改可见性或设置访问权限，请参阅“配置软件包的访问控制和可见性”。有关创建 gem 的更多信息，请参阅 RubyGems 文档中的“制作你自己的 gem”。

1. 向 GitHub Packages 进行身份验证。有关更多信息，请参阅“向 GitHub Packages 进行身份验证”。

2. 从 gemspec 构建软件包以创建 .gem 软件包。将 GEM_NAME 替换为你的 gem 的名称。

   gem build GEM_NAME.gemspec
   

3. 将软件包发布到 GitHub Packages，将 NAMESPACE 替换为软件包所属的个人帐户或组织的名称，将 GEM_NAME 替换为你的 gem 软件包的名称。

   注意：gem 的 metadata.gz 文件的最大未压缩大小必须小于 2 MB。推送超过该限制的 gem 的请求将失败。

   $ gem push --key github \
   --host https://rubygems.pkg.github.com/NAMESPACE \
   GEM_NAME-0.0.1.gem
   

将包连接到存储库

RubyGems 注册表将包存储在您的组织或个人帐户中，并允许您将包与存储库关联。您可以选择继承存储库的权限，或独立于存储库设置细粒度权限。

您可以通过在 gem.metadata 中的 github_repo 字段中包含 GitHub 存储库的 URL，确保宝石在发布后立即链接到存储库。您可以将多个宝石链接到同一个存储库。

gem.metadata = { "github_repo" => "ssh://github.com/OWNER/REPOSITORY" }

有关将已发布包与存储库链接的信息，请参阅“将存储库连接到包”。

安装包

您可以像使用 rubygems.org 中的宝石一样使用 GitHub Packages 中的宝石。您需要通过在 ~/.gemrc 文件中将您的 GitHub 用户或组织添加为源，或使用 Bundler 并编辑您的 Gemfile 来对 GitHub Packages 进行身份验证。

1. 向 GitHub Packages 进行身份验证。有关更多信息，请参阅“向 GitHub Packages 进行身份验证”。

2. 对于 Bundler，在您的 Gemfile 中将您的 GitHub 用户或组织添加为源，以便从这个新源获取宝石。例如，您可以向您的 Gemfile 中添加一个新的 source 块，该块仅对您指定的包使用 GitHub Packages，将 GEM_NAME 替换为要从 GitHub Packages 安装的包，将 NAMESPACE 替换为要安装的宝石的范围所在的个人帐户或组织。

   source "https://rubygems.org.cn"
   
   gem "rails"
   
   source "https://rubygems.pkg.github.com/NAMESPACE" do
     gem "GEM_NAME"
   end
   

3. 对于早于 1.7.0 的 Bundler 版本，您需要添加一个新的全局 source。有关使用 Bundler 的更多信息，请参阅 bundler.io 文档。

   source "https://rubygems.pkg.github.com/NAMESPACE"
   source "https://rubygems.org.cn"
   
   gem "rails"
   gem "GEM_NAME"
   

4. 安装包

   gem install GEM_NAME --version "0.1.1"
   

进一步阅读

• "删除和还原包"