RubyGemsレジストリの利用

GitHub Packages にパッケージを公開し、GitHub Packages に保存されたパッケージを依存関係としてBundlerを使うRubyのプロジェクトで利用するよう、RubyGemsを設定できます。

この機能を使用できるユーザーについて

GitHub Packagesは、GitHub Free、GitHub Pro、組織用GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0以降で利用できます。
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 を使用してパッケージを削除および復元する機能は、現在パブリック ベータ版であり、変更される可能性があります。

トークンにパッケージに対する admin アクセス許可がある場合、GitHub Actions ワークフローで GITHUB_TOKEN と REST API を使って、パッケージを削除または復元できます。 ワークフローを使ってパッケージを発行するリポジトリと、パッケージに明示的に接続したリポジトリには、リポジトリ内のパッケージに対する admin アクセス許可が自動的に付与されます。

GITHUB_TOKEN について詳しくは、「自動トークン認証」をご覧ください。 アクションでレジストリを使うときのベスト プラクティスについて詳しくは、「GitHub Actions のセキュリティ強化」をご覧ください。

また、GitHub Codespaces と GitHub Actions に対して、パッケージにアクセス許可を個別に付与することもできます。 詳細については、「パッケージのアクセス制御と可視性の設定」および「パッケージのアクセス制御と可視性の設定」を参照してください。

personal access token

で認証を行う

GitHub Packages でパッケージを発行およびインストールするには、適切なスコープで personal access token (classic) を使う必要があります。 詳しくは、「GitHub Packages の概要」を参照してください。

gem を公開してインストールするには、personal access tokenを使って GitHub Packages に対する認証を行うように、RubyGems または Bundler を構成できます。

新しい gem を公開するには、 ~/.gem/credentials ファイルを編集してpersonal access token (classic)を含めることによって、RubyGems で GitHub Packages に対して認証を行う必要があります。 このファイルが存在しない場合は、新しい ~/.gem/credentials ファイルを作成します。

たとえば、以下を含むように ~/.gem/credentials を作成または編集し、TOKEN をpersonal access tokenに置き換えます。

---
:github: Bearer TOKEN

gem をインストールするには、https://USERNAME:TOKEN@rubygems.pkg.github.com/NAMESPACE/ を含むように gem ソースを更新することによって、GitHub Packages に対する認証を行う必要があります。 以下のように置き換えてください。

  • USERNAME を GitHub に。
  • TOKEN をpersonal access token (classic) に。
  • NAMESPACE を、gem がスコープ設定されている個人アカウントまたは Organization の名前に。

パッケージをグローバルに使用できるようにする場合は、次のコマンドを実行して、レジストリをソースとして追加できます。

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

Bundler で認証を行うには、personal access token (classic) を使うように Bundler を構成します。USERNAME は GitHub のユーザー名、TOKEN はpersonal access token、NAMESPACE は gem がスコープ設定されている個人アカウントまたは Organization の名前に、それぞれ置き換えます。のホスト名に置き換えてください。

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

パッケージの公開

パッケージを最初に公開する際のデフォルトの可視性はプライベートです。 可視性の変更やアクセス許可の設定については、「パッケージのアクセス制御と可視性の設定」を参照してください。 gem の作成の詳細については、RubyGems のドキュメントの「gem の作成」を参照してください。

注: リポジトリにリンクされているパッケージを公開した場合、パッケージは自動的にリンクされたリポジトリのアクセス許可を継承し、Organization によってアクセス許可の自動継承が無効にされていない限り、リンクされたリポジトリ内の GitHub Actions ワークフローは自動的にパッケージにアクセスできるようになります。 詳しくは、「パッケージのアクセス制御と可視性の設定」を参照してください。

  1. GitHub Packagesに認証を受けてください。 詳細については、「GitHub Packages への認証」を参照してください。

  2. gemspec からパッケージをビルドして、gem パッケージを作成します。 GEM_NAME を gem の名前に置き換えます。

    gem build GEM_NAME.gemspec

  3. パッケージを GitHub Packages に公開します。NAMESPACE をパッケージがスコープ設定されている個人アカウントまたは Organization の名前に、また 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 レジストリを使用すると、Organization または個人のアカウント内にパッケージを格納し、パッケージをリポジトリに関連付けることができます。 権限をリポジトリから継承するか、リポジトリとは別に細かい権限を設定するかを選ぶことができます。

gem が発行されるとすぐにリポジトリにリンクされるようにするには、gem.metadata の github_repo フィールドに GitHub リポジトリの URL を含めます。 複数の gem を同じリポジトリにリンクできます。

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

公開されているパッケージをリポジトリにリンクする方法については、「リポジトリのパッケージへの接続」をご覧ください。

パッケージのインストール

GitHub Packages の gem は、rubygems.org の gem を使うのと同じように使用できます。GitHub ユーザーまたは Organization をソースとして ~/.gemrc ファイルに追加するか、Bundler を使用して Gemfile を編集することで、GitHub Packages に対して認証を行う必要があります。

  1. GitHub Packagesに認証を受けてください。 詳細については、「GitHub Packages への認証」を参照してください。

  2. Bundler については、GitHub ユーザーまたは Organization をソースとして Gemfile に追加して、この新しいソースから gem をフェッチするようにします。 たとえば、指定したパッケージに対してのみ GitHub Packagesを使用する新しい source ブロックを Gemfile に追加できます。GEM_NAME を、GitHub Packagesからインストールするパッケージに、NAMESPACE を、インストールする gem がスコープ設定されている個人アカウントまたは Organization に置き換えます。のホスト名に置き換えてください。

    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"

参考資料