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 不适用于使用旧版按仓库计划的帐户所拥有的私有仓库。 此外,使用旧版按仓库计划的帐户无法访问 Container registry,因为这些帐户是按仓库计费的。 有关详细信息,请参阅“GitHub 的产品”。

先决条件

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

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

    $ bundle --version
    Bundler version 1.13.7
  • 安装 keycutter 以管理多个凭据。 要安装 keycutter:

    $ gem install keycutter

向 GitHub Packages 验证

需要访问令牌才能发布、安装和删除包。

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

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

  • GITHUB_TOKEN 发布与工作流存储库相关联的包。
  • PAT 来安装与其他专用存储库(GITHUB_TOKEN 无法访问)相关联的包。

有关 GitHub Actions 工作流中使用的 GITHUB_TOKEN 的详细信息,请参阅“工作流中的身份验证”。

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

您必须使用具有适当范围的个人访问令牌才可在 GitHub Packages 中发布和安装。 有关详细信息,请参阅“关于 GitHub Packages”。

通过编辑用于发布 gem 的 ~/.gem/credentials 文件、编辑用于安装单个 gem 的 ~/.gemrc 文件或使用用于跟踪和安装一个或多个 gem 的 Bundler,可使用 RubyGems 向 GitHub Packages 进行身份验证 。

要发布新的 gem,需要通过编辑 ~/.gem/credentials 文件以包含你的个人访问令牌,使用 RubyGems 向 GitHub Packages 进行身份验证。 如果此文件不存在,请创建新的 ~/.gem/credentials 文件。

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

---
:github: Bearer TOKEN

要安装 gem,需要通过编辑项目的 ~/.gemrc 文件以包含 https://USERNAME:TOKEN@rubygems.pkg.github.com/OWNER/,来对 GitHub Packages 进行身份验证。 必须:

  • USERNAME 替换为 GitHub 用户名。
  • TOKEN 替换为个人访问令牌。
  • OWNER 替换为拥有项目所在存储库的用户或组织帐户的名称。

如果没有 ~/.gemrc 文件,请使用此示例创建新的 ~/.gemrc 文件 。

---
:backtrace: false
:bulk_threshold: 1000
:sources:
- https://rubygems.org/
- https://USERNAME:TOKEN@rubygems.pkg.github.com/OWNER/
:update_sources: true
:verbose: true  

若要使用 Bundler 进行身份验证,请将 Bundler 配置为使用个人访问令牌,将“用户名”替换为 GitHub 用户名,将“令牌”替换为个人访问令牌,并将“所有者”替换为拥有包含项目的存储库的用户或组织帐户的名称。

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

发布包

默认情况下,GitHub 将包发布到名称与包相同的现有仓库中。 例如,将 octo-gem 发布到 octo-org 组织时,GitHub Packages 会将 gem 发布到 octo-org/octo-gem 存储库。 有关创建 gem 的详细信息,请参阅 RubyGems 文档中的“创建自己的 gem”。

在发布包后,您可以在 GitHub 上查看该包。 有关详细信息,请参阅“查看包”。

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

  2. 从 gemspec 生成包以创建 .gem 包 。

    gem build OCTO-GEM.gemspec
  3. 将包发布到 GitHub Packages,将 OWNER 替换为拥有包含项目的存储库的用户或组织帐户的名称,并将 OCTO-GEM 替换为 gem 包的名称。

    $ gem push --key github \
    --host https://rubygems.pkg.github.com/OWNER \
    OCTO-GEM-0.0.1.gem

将多个包发布到同一个仓库

要将多个 gem 发布到同一存储库,可在 gem.metadatagithub_repo 字段中包含指向 GitHub 存储库的 URL。 如果包含此字段,则 GitHub 将基于此值匹配存储库,而不是使用 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 安装的包,并将“所有者”替换为拥有包含要安装的 gem 的存储库的用户或组织。

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://rubygems.pkg.github.com/OWNER" do
      gem "GEM NAME"
    end
    
  3. 对于低于 1.7.0 的 Bundler 版本,需要添加新的全局 source。 有关使用 Bundler 的详细信息,请参阅 bundler.io 文档

    source "https://rubygems.pkg.github.com/OWNER"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM NAME"
    
  4. 安装包:

    $ gem install octo-gem --version "0.1.1"

延伸阅读