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

Prerequisites

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 https://rubygems.pkg.github.com/OWNER 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 https://rubygems.pkg.github.com/OWNER \
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://github.com/OWNER/REPOSITORY" }

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:

https://github.com/OWNER/REPOSITORY/packages

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 rubygems.org. 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 "https://rubygems.org"

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 "https://rubygems.org"

gem "rails"

source "https://rubygems.pkg.github.com/OWNER" do
  gem "GEM NAME"
end

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

source "https://rubygems.pkg.github.com/OWNER"
source "https://rubygems.org"

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 bundler.io documentation.

Deleting a package

To avoid breaking projects that may depend on your packages, GitHub Package Registry does not support package deletion or deleting a version of a package. 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."

Ask a human

Can't find what you're looking for?

Contact us