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. For more information, see "About GitHub Package Registry."

In this article


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

Publishing a package

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

$ gem push --key github \
--host \

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. A GitHub release and associated Git tag will be automatically created for the version of the gem, if it doesn't already exist.

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 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 ""
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 version

You can use the gem yank command to remove a package version from GitHub Package Registry.

Caution: Deleting a package is irreversible.

$ gem yank PACKAGE NAME -v VERSION --key github --host

Ask a human

Can't find what you're looking for?

Contact us