Configuring RubyGems for use with GitHub Packages

You can configure RubyGems to publish a package to GitHub Packages and to use packages stored on GitHub Packages as dependencies in a Ruby project with Bundler.

GitHub Packages is available with GitHub Free, GitHub Pro, GitHub Team, and GitHub Enterprise Cloud. GitHub Packages is unavailable for per-repository plans, which are legacy billing plans. For more information, see "GitHub's products."

In this article

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
  • Install keycutter to manage multiple credentials. To install keycutter:

    $ gem install keycutter

Authenticating to GitHub Packages

You need an access token to publish, install, and delete packages in GitHub Packages. You can use a personal access token to authenticate with your username directly to GitHub Packages or the GitHub API. You can use a GITHUB_TOKEN to authenticate using a GitHub Actions workflow.

Authenticating with a personal access token

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

To authenticate to GitHub Packages with RubyGems, edit your ~/.gem/credentials file to include your personal access token for publishing new gems. Create a new ~/.gem/credentials file if one 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

Configure Bundler to use your personal access token, 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. Because upper case letters aren't supported, you must use lowercase letters for the repository owner even if the GitHub user or organization name contains uppercase letters.

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

Authenticating with the GITHUB_TOKEN

If you are using a GitHub Actions workflow, you can use a GITHUB_TOKEN to publish and consume packages in GitHub Packages without needing to store and manage a personal access token. For more information, see "Authenticating with the GITHUB_TOKEN."

Publishing a package

By default, GitHub uses the package name to create a repository where the package will be published. For example, if you publish 'mygem' published to the 'my-org' organization, then GitHub Packages will create a my-org/mygem repository that contains mygem. For more information on creating your gem, see "Make your own gem" in the RubyGems documentation.

After you publish a package, you can view the package on GitHub. For more information, see “Viewing a repository's packages.”

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

  2. Publish a package to GitHub Packages, replacing OWNER with the name of the user or organization account that owns the repository containing your project.

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

Publishing multiple packages to the same repository

To publish multiple gems to the same repository, you can include the URL to the GitHub repository in the github_repo field in gem.metadata. If you include this field, GitHub matches the repository based on this value, instead of using the gem name.

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

Installing a package

Using gems from GitHub Packages in your project is similar to using gems from rubygems.org.

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

  2. 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 for a simple Ruby on Rails app, replacing GEM NAME with the package you want to install and OWNER with the user or organization that owns the repository containing 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"

Further reading

Ask a human

Can't find what you're looking for?

Contact us