Skip to main content

Working with the RubyGems registry

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.

O

Observação: atualmente, o GitHub Packages está em versão beta no GitHub AE.

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

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

You can use a personal access token to authenticate to GitHub Packages or the GitHub AE API. When you create a personal access token, you can assign the token different scopes depending on your needs. For more information about packages-related scopes for a personal access token, 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 with at least packages:read scope to install packages associated with other private repositories (which GITHUB_TOKEN can't access).

Para obter mais informações sobre o GITHUB_TOKEN usado em fluxos de trabalho do GitHub Actions, confira "Autenticação em um fluxo de trabalho".

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 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. 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@REGISTRY-URL/OWNER/. You must replace:

  • USERNAME with your GitHub username.
  • TOKEN with your personal access token.
  • OWNER with the name of the user or organization account that owns the repository containing your project.
  • REGISTRY-URL with the URL for your instance's Rubygems registry, rubygems.HOSTNAME. Replace HOSTNAME with the hostname of your enterprise.

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@REGISTRY-URL/OWNER/

To authenticate with Bundler, 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.Replace REGISTRY-URL with the URL for your instance's Rubygems registry, rubygems.HOSTNAME. Replace HOSTNAME with the hostname of your enterprise.

$ bundle config https://REGISTRY-URL/OWNER USERNAME:TOKEN

Publishing a package

Por padrão, o GitHub publica o pacote em um repositório existente com o mesmo nome do pacote. For example, when you publish <GEM NAME> to the octo-org organization, GitHub Packages publishes the gem to the octo-org/<GEM NAME> repository. For more information on creating your gem, see "Make your own gem" in the RubyGems documentation.

Após publicar um pacote, você poderá visualizá-lo no GitHub. Para obter mais informações, confira "Como ver pacotes".

  1. Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no 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 the user or organization account that owns the repository containing your project and <GEM NAME> with the name of your gem package. Replace REGISTRY-URL with the URL for your instance's Rubygems registry, rubygems.HOSTNAME. Replace HOSTNAME with the hostname of your enterprise.

    $ gem push --key github \
    --host https://REGISTRY-URL/OWNER \
    <GEM NAME>-0.0.1.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. Replace HOSTNAME with the host name of your enterprise.

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

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. Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no 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 repository containing the gem you want to install. Replace REGISTRY-URL with the URL for your instance's Rubygems registry, rubygems.HOSTNAME. Replace HOSTNAME with the hostname of your enterprise.

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://REGISTRY-URL/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://REGISTRY-URL/OWNER"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM NAME"
    
  4. Install the package:

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

Further reading