Skip to main content
We publish frequent updates to our documentation, and translation of this page may still be in progress. For the most current information, please visit the English documentation.

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 GitHub Packages está disponível com GitHub Free, GitHub Pro, GitHub Free for organizations, GitHub Team, GitHub Enterprise Cloud, GitHub Enterprise Server 3.0 ou superior e o GitHub AE.
O GitHub Packages não está disponível para repositórios privados de contas que utilizam planos antigos por-repositório. Além disso, as contas que usam os planos de legado por repositório não podem acessar o Container registry já que essas contas são cobradas por repositório. Para obter mais informações, confira "produtos de GitHub".

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

Autenticar-se no GitHub Packages

O GitHub Packages dá suporte apenas à autenticação que usa um personal access token (classic). Para obter mais informações, confira "Como criar um personal access token".

Você precisa de um token de acesso para publicar, instalar e excluir pacotes privados, públicos e internos.

Você pode usar um personal access token (classic) para se autenticar no GitHub Packages ou na API do GitHub. Ao criar um personal access token (classic), você pode atribuir diferentes escopos de token, dependendo da sua necessidade. Para obter mais informações sobre escopos relacionados a pacotes para um personal access token (classic), 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 personal access token (classic) com pelo menos escopo read:packages para instalar pacotes associados a outros repositórios privados (que não podem ser acessados por GITHUB_TOKEN).

Como se autenticar em um fluxo de trabalho de GitHub Actions

Esse registro dá suporte a permissões granulares. Para registros que oferecem suporte a permissões granulares, se o seu fluxo de trabalho estiver usando um personal access token para autenticar em um registro, recomendamos fortemente que você atualize seu fluxo de trabalho para usar GITHUB_TOKEN. Para obter diretrizes sobre como atualizar seus fluxos de trabalho que se autenticam em um registro com um personal access token, confira "Como fazer upgrade de um fluxo de trabalho que acessa um registro usando um personal access token".

Para obter mais informações sobre o GITHUB_TOKEN, confira "Autenticação em um fluxo de trabalho". Para obter mais informações sobre as melhores práticas ao usar um registro em ações, confira "Proteção de segurança para GitHub Actions".

Você também pode optar por dar permissões de acesso a pacotes de modo independente para GitHub Codespaces e GitHub Actions. Para obter mais informações, confira "Como garantir que os codespaces acessem seu pacote" e "Como garantir o acesso do fluxo de trabalho ao seu pacote".

Autenticar com um personal access token

Você precisa usar um personal access token (classic) com os escopos apropriados para publicar e instalar pacotes no GitHub Packages. Para obter mais informações, confira "Sobre o GitHub Packages".

Para publicar e instalar gems, você pode configurar o RubyGems ou o Bundler para se autenticar no GitHub Packages usando seu personal access token.

Para publicar novos gems, você precisa se autenticar no GitHub Packages com o RubyGems editando o arquivo ~/.gem/credentials para incluir seu personal access token (classic). 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 personal access token.

---
:github: Bearer TOKEN

Para instalar gems, você precisa se autenticar em GitHub Packages atualizando suas fontes de gem para incluir https://USERNAME:TOKEN@rubygems.pkg.github.com/OWNER/. Você deve substituir:

  • USERNAME pelo seu nome de usuário do GitHub.
  • TOKEN com seu personal access token (classic).
  • OWNER pelo nome da conta de usuário ou da organização que é proprietário do repositório que contém o projeto.

Se você quiser que seu pacote esteja disponível globalmente, execute o comando a seguir para adicionar seu registro como uma fonte.

gem sources --add https://USERNAME:TOKEN@rubygems.pkg.github.com/OWNER/

Para se autenticar no Bundler, configure-o para usar seu personal access token (classic), substituindo USERNAME pelo seu nome de usuário do GitHub, TOKEN pelo seu personal access token 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.

$ bundle config https://rubygems.pkg.github.com/OWNER USERNAME:TOKEN

Publicando um pacote

Ao publicar um pacote pela primeira vez a visibilidade-padrão será privada. Quando um pacote é vinculado a um repositório, a visibilidade do pacote depende da visibilidade do repositório. Para alterar a visibilidade ou definir permissões de acesso, confira "Como configurar o controle de acesso e a visibilidade de um pacote". Para obter mais informações sobre como criar seu gem, confira "Como criar um gem própria" na documentação do RubyGems.

  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 <GEM NAME>.gemspec
    
  3. Publique um pacote no GitHub Packages, substituindo OWNER pelo nome da conta do usuário ou da organização e <GEM NAME> pelo nome do pacote do gem.

    $ gem push --key github \
    --host https://rubygems.pkg.github.com/OWNER \
    <GEM NAME>-0.0.1.gem
    

Como conectar um pacote a um repositório

O registro do RubyGems armazena pacotes na sua organização ou conta pessoal e permite que você associe pacotes a um repositório. Você pode escolher se deve herdar permissões de um repositório ou definir permissões granulares, independentemente de um repositório.

Você pode garantir que os gems serão vinculados a um repositório assim que forem publicados, incluindo a URL do repositório do GitHub no campo github_repo em gem.metadata. Você pode vincular vários gems ao mesmo repositório.

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

Para obter mais informações sobre como vincular um pacote publicado a um repositório, confira "Como conectar um repositório a um pacote".

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 especificados, substituindo GEM NAME pelo pacote que deseja instalar por meio do GitHub Packages e OWNER pelo usuário ou pela organização que detém o gem que você deseja instalar.

    source "https://rubygems.org"
    
    gem "rails"
    
    source "https://rubygems.pkg.github.com/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://rubygems.pkg.github.com/OWNER"
    source "https://rubygems.org"
    
    gem "rails"
    gem "GEM NAME"
    
  4. Instale o pacote:

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

Leitura adicional