使用 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 发布和安装软件包”。

如果令牌对软件包具有 admin 权限，则可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN 使用 REST API 删除或恢复软件包。使用工作流发布软件包的存储库以及您已明确连接到软件包的存储库会自动获得对存储库中软件包的 admin 权限。

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

您还可以选择分别为 GitHub Codespaces 和 GitHub Actions 提供软件包的访问权限。有关更多信息，请参阅“配置软件包的访问控制和可见性”和“配置软件包的访问控制和可见性”。

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

您必须使用具有适当作用域的个人访问令牌（经典）才能在 GitHub Packages 中发布和安装软件包。有关更多信息，请参阅“GitHub Packages 简介”。

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

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

例如，您将创建或编辑 ~/.gem/credentials 以包含以下内容，将 TOKEN 替换为您的个人访问令牌。

---
:github: Bearer TOKEN

要安装 gem，您需要通过更新 gem 源以包含 https://USERNAME:[email protected]/NAMESPACE/ 来对 GitHub Packages 进行身份验证。您必须替换

• 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 在发布后立即链接到存储库，方法是在 gem.metadata 中的 github_repo 字段中包含 GitHub 存储库的 URL。您可以将多个 gem 链接到同一存储库。

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

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

安装包

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

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

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

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

3. 对于 Bundler 1.7.0 之前的版本，您需要添加一个新的全局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"
   

进一步阅读

• "删除和恢复包"