Configuring RubyGems for use with GitHub Package Registry

You can configure RubyGems to publish a package with GitHub Package Registry and use that package as a dependency in a Ruby project with Bundler.

GitHub Package Registry is currently available in limited public beta. You should avoid using GitHub Package Registry for high-value workflows and content during the beta period. For more information, see "About GitHub Package Registry."

In this article


  • You must have rubygems 2.4.1 or higher

    $ gem --version
  • You must have bundler 1.6.4 or higher

    $ bundle --version
    Bundler version 1.13.7
  • Install keycutter to manage multiple credentials

    $ gem install keycutter

Authenticating to GitHub Package Registry

You must use a personal access token with the read:packages and write:packages scopes to publish and delete public packages in the GitHub Package Registry with RubyGems. Your personal access token must also have the repo scope when the repository is private. For more information, see "Creating a personal access token for the command line."

  1. Configure gem to use your token when pushing new gems by editing ~/.gem/credentials or creating it if it doesn't exist. Replace TOKEN with your personal access token and add this line:

    :github: Bearer TOKEN
  2. Configure Bundler to use your token. Replace OWNER with the GitHub user or organization name that contains the repository where you want to publish the gem, and enter your GitHub username and personal access token.

    $ bundle config USERNAME:TOKEN

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

You can use a script to inject your GITHUB_TOKEN into the appropriate configuration file for GitHub Package Registry. Add GitHub Package Registry as an alternative registry or repository in the configuration file for the package client, as well as your GitHub username and a personal access token with the appropriate scopes. The exact steps for creating a configuration file vary by package type.

Publishing a package

You can use the gem push command to publish a package to GitHub Package Registry.

$ gem push --key github \
--host \YOUR-GEM.gem

By default the package name is used to determine the repository to publish the gem to. For example a gem called 'mygem' published to the 'my-org' organization is published to the my-org/mygem GitHub repository.

If you would like to publish multiple gems to the same repository, you can include the URL to the GitHub repository in the github_repo field in the gemspec metadata. If you include this field, GitHub will match the repository based on this value, instead of based on the gem name.

For example:

gem.metadata = { "github_repo" => "ssh://" }

For more information on creating your gem, see "Make your own gem" in the RubyGems documentation.

You can access your packages from this URL by replacing OWNER with your GitHub user or organization name and REPOSITORY with your repository name:

Receiving package registry events

You can receive webhook events when a package is published or updated. For more information, see "RegistryPackageEvent" in the GitHub Developer documentation.

Installing a package

Using gems from GitHub Package Registry in your project is similar to using gems from You can add your GitHub user or organization as a source in your Gemfile, and fetch gems from it.

For example, here is a Gemfile for a simple Ruby on Rails app:

source ""

gem "rails"

Add a new source block for your GitHub user or organization that contains the repository with your gem in it. For example, to modify that same rails app Gemfile:

source ""

gem "rails"

source "" do
  gem "GEM NAME"

For Bundler versions earlier than 1.7.0, add a new global source instead:

source ""
source ""

gem "rails"
gem "GEM NAME"

The credentials you configured earlier with bundle config will be used automatically when you bundle install. For more information on using bundler, see the documentation.

Deleting a package

To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support deleting published versions of a package or an entire published package for public repositories. Under special circumstances, such as for legal reasons or to conform with GDPR standards, you can request deleting a package through GitHub Support. Contact GitHub Support using our contact form and the subject line "GitHub Package Registry."

You can delete private packages via GitHub's API. For more information, see "Access to package version deletion" in the GitHub Developer documentation.

Ask a human

Can't find what you're looking for?

Contact us