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 Packages 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 此外,使用旧版按存储库计划的帐户无法访问支持精细权限的注册表,因为这些帐户按存储库计费。 Enterprise Managed Users 没有单独的存储分配来在其帐户的命名空间内发布包,但可以发布到组织的命名空间。 有关 Enterprise Managed Users 的其他信息,请参阅“关于 Enterprise Managed Users”。有关支持精细权限的注册表列表,请参阅“关于 GitHub Packages 的权限”。 有关详细信息,请参阅“GitHub 的计划”。

RubyGems 注册表的 URL

如果在 GitHub.com 上访问 GitHub,请将包发布到 https://rubygems.pkg.github.com。 本文中的示例使用此 URL。

如果在另一个域中(例如 octocorp.ghe.com)访问 GitHub,请将“https://rubygems.pkg.github.com”替换为 https://rubygems.SUBDOMAIN.ghe.com,其中 SUBDOMAIN 是企业的唯一子域。

先决条件

  • 您必须具有 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 发布和安装包”。

Note

GitHub Actions 工作流使用 REST API 删除和还原包的功能目前为 公共预览版,可能随时更改。

如果令牌具有对包的 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”。

Note

如果发布链接到存储库的包,该包会自动继承链接存储库的访问权限,链接存储库中的 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 包的名称。的主机名。

    Note

    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"
    

延伸阅读