Skip to main content

使用 RubyGems 注册表

您可以配置 RubyGems 以将包发布到 GitHub Packages 并将存储在 GitHub Packages 上的包用作带 Bundler 的 Ruby 项目中的依赖项。

GitHub Packages 适用于 GitHub Free、GitHub Pro、面向组织的 GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0 或更高版本以及 GitHub AE。
GitHub Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 此外,使用旧版按存储库计划的帐户无法访问支持精细权限的注册表,因为这些帐户按存储库计费。 有关支持精细权限的注册表的列表,请参阅“关于 GitHub Packages 的权限”。 有关详细信息,请参阅“GitHub 的计划”。

先决条件

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

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

    $ bundle --version
    Bundler version 1.13.7
    

向 GitHub Packages 验证

GitHub Packages 仅支持使用 personal access token (classic) 进行身份验证。 有关详细信息,请参阅“管理个人访问令牌”。

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

可使用 personal access token (classic) 向 GitHub Packages 或 GitHub API 进行身份验证。 创建 personal access token (classic) 时,可根据需要为令牌分配不同的作用域。 有关 personal access token (classic) 的包相关范围的详细信息,请参阅“关于 GitHub Packages 的权限”。

要在 GitHub Actions 工作流程内向 GitHub Packages 注册表验证,您可以使用:

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • 范围至少为 read:packages 的 personal access token (classic),用于安装与其他专用存储库(GITHUB_TOKEN 无法访问)关联的包。

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

此注册表支持精细权限。 对于支持精细权限的注册表,如果 GitHub Actions 工作流使用 personal access token 向注册表进行身份验证,则强烈建议更新工作流以使用 GITHUB_TOKEN。 有关如何更新通过 personal access token 向注册表进行身份验证的工作流的指南,请参阅“使用 GitHub Actions 发布和安装包”。

注意:GitHub Actions 工作流使用 REST API 删除和还原包的功能目前提供公共 beta 版本,可能会发生更改。

如果令牌具有对包的 admin 权限,你可以在 GitHub Actions 工作流中使用 GITHUB_TOKEN,通过 REST API 来删除或还原包。 使用工作流发布包的存储库,以及已经显式连接到包的存储库,会自动获得对存储库中包的 admin 权限。

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

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

使用 personal access token

进行身份验证

必须使用具有适当范围的 personal access token (classic) 才可在 GitHub Packages 中发布和安装包。 有关详细信息,请参阅“GitHub Packages 简介”。

要发布和安装 gem,可以将 RubyGems 或 Bundler 配置为使用 personal access token 向 GitHub Packages 进行身份验证。

要发布新的 gem,需要通过编辑 ~/.gem/credentials 文件以包含你的 personal access token (classic),使用 RubyGems 向 GitHub Packages 进行身份验证。 如果此文件不存在,请创建新的 ~/.gem/credentials 文件。

例如,创建或编辑 ~/.gem/credentials 以包含以下内容,将 TOKEN 替换为 personal access token。

---
:github: Bearer TOKEN

要安装 gem,需要通过更新 gem 资源以包含 https://USERNAME:TOKEN@rubygems.pkg.github.com/NAMESPACE/,来向 GitHub Packages 进行身份验证。 必须:

  • USERNAME 替换为 GitHub 用户名。
  • TOKEN 替换为 personal access token (classic)。
  • NAMESPACE 替换为作为 gem 限定范围的个人帐户或组织的名称。

如果希望包全局可用,可以运行以下命令,将注册表添加为源。

gem sources --add https://USERNAME:TOKEN@rubygems.pkg.github.com/NAMESPACE/

若要使用 Bundler 进行身份验证,请将 Bundler 配置为使用 personal access token (classic),将 USERNAME 替换为 GitHub 用户名,将 TOKEN 替换为 personal access token,并将 NAMESPACE 替换为作为 gem 的限定范围的个人帐户或组织的名称。

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

发布包

首次发布包时,默认可见性是私有的。 要更改可见性或设置访问权限,请参阅“配置包的访问控制和可见性”。有关创建 gem 的详细信息,请参阅 RubyGems 文档中的“创建自己的 gem”。

注意: 如果发布链接到存储库的包,该包会自动继承链接存储库的访问权限,链接存储库中的 GitHub Actions 工作流会自动获得对包的访问权限,除非你的组织已禁用访问权限的自动继承。 有关详细信息,请参阅“配置包的访问控制和可见性”。

  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 在发布后立即链接到存储库。 可将多个 gem 链接到同一存储库。

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

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

安装包

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

  1. 向 GitHub Packages 验证。 有关详细信息,请参阅“向 GitHub Packages 进行身份验证”。

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

    source "https://rubygems.org"
    
    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"
    
    gem "rails"
    gem "GEM_NAME"
    
  4. 安装包:

    gem install GEM_NAME --version "0.1.1"
    

延伸阅读