Skip to main content

RubyGemsレジストリの利用

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

GitHub Packages は、GitHub Free、GitHub Pro、Organization の GitHub Free、GitHub Team、GitHub Enterprise Cloud、GitHub Enterprise Server 3.0 以降、GitHub AE で利用できます。
GitHub Packagesは、レガシーのリポジトリごとのプランを使っているアカウントが所有しているプライベートリポジトリでは利用できません。 また、レガシーのリポジトリごとのプランを使っているアカウントは、リポジトリごとに課金される Container registry にはアクセスできません。 詳細については、「GitHub's products」を参照してください。

Prerequisites

  • You must have RubyGems 2.4.1 or higher. To find your RubyGems version:

    $ gem --version
  • You must have bundler 1.6.4 or higher. To find your Bundler version:

    $ bundle --version
    Bundler version 1.13.7

Authenticating to GitHub Packages

GitHub Packages only supports authentication using a personal access token (classic). For more information, see "Creating a personal access token."

You need an access token to publish, install, and delete private, internal, and public packages.

You can use a personal access token (classic) to authenticate to GitHub Packages or the GitHub API. When you create a personal access token (classic), you can assign the token different scopes depending on your needs. For more information about packages-related scopes for a personal access token (classic), see "About permissions for GitHub Packages."

To authenticate to a GitHub Packages registry within a GitHub Actions workflow, you can use:

  • GITHUB_TOKEN to publish packages associated with the workflow repository.
  • a personal access token (classic) with at least read:packages scope to install packages associated with other private repositories (which GITHUB_TOKEN can't access).

Authenticating in a GitHub Actions workflow

This registry supports granular permissions. For registries that support granular permissions, if your workflow is using a personal access token to authenticate to a registry, we highly recommend you update your workflow to use the GITHUB_TOKEN. For guidance on updating your workflows that authenticate to a registry with a personal access token, see "Upgrading a workflow that accesses a registry using a personal access token."

For more information about the GITHUB_TOKEN, see "Authentication in a workflow." For more information about the best practices when using a registry in actions, see "Security hardening for GitHub Actions."

You can also choose to give access permissions to packages independently for GitHub Codespaces and GitHub Actions. For more information, see "Ensuring Codespaces access to your package" and "Ensuring workflow access to your package."

Authenticating with a personal access token

You must use a personal access token (classic) with the appropriate scopes to publish and install packages in GitHub Packages. For more information, see "About GitHub Packages."

To publish and install gems, you can configure RubyGems or Bundler to authenticate to GitHub Packages using your personal access token.

To publish new gems, you need to authenticate to GitHub Packages with RubyGems by editing your ~/.gem/credentials file to include your personal access token (classic). Create a new ~/.gem/credentials file if this file doesn't exist.

For example, you would create or edit a ~/.gem/credentials to include the following, replacing TOKEN with your personal access token.

---
:github: Bearer TOKEN

To install gems, you need to authenticate to GitHub Packages by updating your gem sources to include https://USERNAME:TOKEN@rubygems.pkg.github.com/OWNER/. You must replace:

  • USERNAME with your GitHub username.
  • TOKEN with your personal access token (classic).
  • OWNER with the name of the user or organization account that owns the repository containing your project.

If you would like your package to be available globally, you can run the following command to add your registry as a source.

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

To authenticate with Bundler, configure Bundler to use your personal access token (classic), replacing USERNAME with your GitHub username, TOKEN with your personal access token, and OWNER with the name of the user or organization account that owns the repository containing your project.

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

Publishing a package

When you first publish a package, the default visibility is private. When a package is linked to a repository, the package visibility is dependent on the repository's visibility. To change the visibility or set access permissions, see "Configuring a package's access control and visibility." For more information on creating your gem, see "Make your own gem" in the RubyGems documentation.

  1. Authenticate to GitHub Packages. For more information, see "Authenticating to GitHub Packages."

  2. Build the package from the gemspec to create the .gem package.

    gem build <GEM NAME>.gemspec
    
  3. Publish a package to GitHub Packages, replacing OWNER with the name of your user or organization account and <GEM NAME> with the name of your gem package.

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

Connecting a package to a repository

The RubyGems registry stores packages within your organization or personal account, and allows you to associate packages with a repository. You can choose whether to inherit permissions from a repository, or set granular permissions independently of a repository.

You can ensure gems will be linked to a repository as soon as they are published by including the URL of the GitHub repository in the github_repo field in gem.metadata. You can link multiple gems to the same repository.

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

For information on linking a published package with a repository, see "Connecting a repository to a package."

Installing a package

You can use gems from GitHub Packages much like you use gems from rubygems.org. You need to authenticate to GitHub Packages by adding your GitHub user or organization as a source in the ~/.gemrc file or by using Bundler and editing your Gemfile.

  1. Authenticate to GitHub Packages. For more information, see "Authenticating to GitHub Packages."

  2. For Bundler, add your GitHub user or organization as a source in your Gemfile to fetch gems from this new source. For example, you can add a new source block to your Gemfile that uses GitHub Packages only for the packages you specify, replacing GEM NAME with the package you want to install from GitHub Packages and OWNER with the user or organization that owns the gem you want to install.

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://rubygems.pkg.github.com/OWNER" do
      gem "GEM NAME"
    end
    
  3. For Bundler versions earlier than 1.7.0, you need to add a new global source. For more information on using Bundler, see the bundler.io documentation.

    source "https://rubygems.pkg.github.com/OWNER"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM NAME"
    
  4. Install the package:

    $ gem install <GEM NAME> --version "0.1.1"
    

Further reading