Skip to main content

Trabalhando com o registro do RubyGems

Você pode configurar RubyGems para publicar um pacote em GitHub Packages e usar pacotes armazenados em GitHub Packages como dependências em um projeto Ruby com o Bundler.

O

Observação: talvez esse tipo de pacote não esteja disponível para sua instância, pois os administradores do site podem habilitar ou desabilitar cada tipo de pacote compatível. Para obter mais informações, confira "Como configurar o suporte a pacotes para sua empresa".

Pré-requisitos

  • Você deve ter o RubyGems 2.4.1 ou superior. Para encontrar a versão do seu RubyGems:

    $ gem --version
  • Você precisa ter o Bundler 1.6.4 ou superior. Para encontrar sua versão do Bundler:

    $ bundle --version
    Bundler version 1.13.7
  • Instale o keycutter para gerenciar várias credenciais. Para instalar o keycutter:

    $ gem install keycutter

Autenticar-se no GitHub Packages

Você precisa de um token de acesso para publicar, instalar e excluir pacotes.

Você pode usar um PAT (token de acesso pessoal) para se autenticar no GitHub Packages ou na API do GitHub Enterprise Server. Ao criar um token de acesso pessoal, você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para um PAT, confira "Sobre as permissões para pacotes do GitHub".

Para efetuar a autenticação em um registro do GitHub Packages dentro de um fluxo de trabalho de GitHub Actions, você pode utilizar:

  • GITHUB_TOKEN para publicar pacotes associados ao repositório do fluxo de trabalho.
  • um PAT para instalar pacotes associados a outros repositórios privados (que não podem ser acessados pelo GITHUB_TOKEN).

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

Efetuando a autenticação com um token de acesso pessoal

Você deve usar um token de acesso pessoal com os escopos apropriados para publicar e instalar pacotes no GitHub Packages. Para obter mais informações, confira "Sobre o GitHub Packages".

Autentique-se no GitHub Packages com o RubyGems editando o arquivo ~/.gem/credentials para publicação de gems, editando o arquivo ~/.gemrc para instalar um só gem ou usando o Bundler para acompanhar e instalar um ou mais gems.

Para publicar novos gems, você precisa se autenticar no GitHub Packages com o RubyGems editando o arquivo ~/.gem/credentials para incluir seu token de acesso pessoal. Crie um arquivo ~/.gem/credentials se ele não existir.

Por exemplo, crie ou edite um arquivo ~/.gem/credentials para incluir o conteúdo indicado a seguir, substituindo TOKEN pelo seu token de acesso pessoal.

---
:github: Bearer TOKEN

Para instalar gems, você precisa se autenticar no GitHub Packages editando o arquivo ~/.gemrc para que o projeto inclua https://USERNAME:TOKEN@REGISTRY-URL/OWNER/. Você deve substituir:

  • USERNAME pelo seu nome de usuário do GitHub.
  • TOKEN pelo seu token de acesso pessoal.
  • OWNER pelo nome da conta de usuário ou da organização que é proprietário do repositório que contém o projeto.
  • REGISTRY-URL pela URL do registro do RubyGems da instância. Se a sua instância tem o isolamento de subdomínio habilitado, use rubygems.HOSTNAME. Se a sua instância tem o isolamento de subdomínio desabilitado, use HOSTNAME/_registry/rubygems. Em ambos os casos, substitua HOSTNAME pelo nome do host da sua instância do GitHub Enterprise Server.

Caso você não tenha um arquivo ~/.gemrc, crie um arquivo ~/.gemrc usando este exemplo.

---
:backtrace: false
:bulk_threshold: 1000
:sources:
- https://rubygems.org/
- https://USERNAME:TOKEN@REGISTRY-URL/OWNER/
:update_sources: true
:verbose: true  

Para se autenticar no Bundler, configure-o para usar seu token de acesso pessoal, substituindo USERNAME pelo seu nome de usuário do GitHub, TOKEN pelo seu token de acesso pessoal e OWNER pelo nome da conta de usuário ou da organização que é o proprietário do repositório que contém o projeto. Substitua REGISTRY-URL pela URL do registro do RubyGems da instância. Se a sua instância tem o isolamento de subdomínio habilitado, use rubygems.HOSTNAME. Se a sua instância tem o isolamento de subdomínio desabilitado, use HOSTNAME/_registry/rubygems. Em ambos os casos, substitua HOSTNAME pelo nome do host da instância do GitHub Enterprise Server.

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

Publicando um pacote

Por padrão, o GitHub publica o pacote em um repositório existente com o mesmo nome do pacote. Por exemplo, quando você publica octo-gem na organização octo-org, o GitHub Packages publica o gem no repositório octo-org/octo-gem. Para obter mais informações sobre como criar seu gem, confira "Criar seu gem" na documentação do RubyGems.

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. Compile o pacote do gemspec para criar o pacote .gem.

    gem build OCTO-GEM.gemspec
  3. Publique um pacote no GitHub Packages, substituindo OWNER pelo nome da conta de usuário ou da organização que é o proprietário do repositório que contém o projeto e OCTO-GEM pelo nome do pacote do gem. Substitua REGISTRY-URL pela URL do registro do RubyGems da instância. Se a sua instância tem o isolamento de subdomínio habilitado, use rubygems.HOSTNAME. Se a sua instância tem o isolamento de subdomínio desabilitado, use HOSTNAME/_registry/rubygems. Em ambos os casos, substitua HOSTNAME pelo nome do host da instância do GitHub Enterprise Server.

    $ gem push --key github \
    --host https://REGISTRY-URL/OWNER \
    OCTO-GEM-0.0.1.gem

Publicar vários pacotes no mesmo repositório

Para publicar vários gems no mesmo repositório, inclua a URL do repositório do GitHub no campo github_repo em gem.metadata. Se você incluir esse campo, o GitHub corresponderá ao repositório com base nesse valor, em vez de usar o nome do gem. Substitua HOSTNAME pelo nome do host da your GitHub Enterprise Server instance.

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

Instalando um pacote

Você pode usar gems no GitHub Packages da mesma forma que você usa gems em rubygems.org. Você precisa se autenticar no GitHub Packages adicionando o usuário ou a organização do GitHub como uma fonte no arquivo ~/.gemrc ou usando o Bundler e editando o Gemfile.

  1. Autenticar para GitHub Packages. Para obter mais informações, confira "Autenticação no GitHub Packages".

  2. Para o Bundler, adicione o usuário ou a organização do GitHub como uma fonte no Gemfile para buscar gems dessa nova fonte. Por exemplo, você pode adicionar um novo bloco source ao Gemfile que só usa o GitHub Packages para os pacotes que você especificar, substituindo GEM NAME pelo pacote que deseja instalar por meio do GitHub Packages e OWNER pelo usuário ou pela organização que é o proprietário do repositório que contém o gem que deseja instalar. Substitua REGISTRY-URL pela URL do registro do RubyGems da instância. Se a sua instância tem o isolamento de subdomínio habilitado, use rubygems.HOSTNAME. Se a sua instância tem o isolamento de subdomínio desabilitado, use HOSTNAME/_registry/rubygems. Em ambos os casos, substitua HOSTNAME pelo nome do host da instância do GitHub Enterprise Server.

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://REGISTRY-URL/OWNER" do
      gem "GEM NAME"
    end
    
  3. Para versões do Bundler anteriores à 1.7.0, adicione uma nova source global. Para obter mais informações sobre como usar o Bundler, confira a documentação em bundler.io.

    source "https://REGISTRY-URL/OWNER"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM NAME"
    
  4. Instale o pacote:

    $ gem install octo-gem --version "0.1.1"

Leitura adicional