Configurar a autenticação no Artifact Registry para repositórios de gem do Ruby

Esta página descreve como configurar a autenticação com um repositório de gemas do Ruby do Artifact Registry.

É necessário se autenticar no Artifact Registry ao usar um aplicativo de terceiros para se conectar a um repositório.

Não é necessário configurar a autenticação para o Cloud Build ou Google Cloud ambientes de execução, como o Google Kubernetes Engine e o Cloud Run.

Antes de começar

  1. Se o repositório de destino não existir, crie um repositório de gemas do Ruby.
  2. Verifique se o Ruby está instalado. Para instruções de instalação, consulte o Google Cloud tutorial de configuração do Ruby.
  3. Verifique se a conta de usuário ou de serviço que você está usando tem as permissões necessárias para acessar o repositório.

  4. Instale a Google Cloud CLI. Após a instalação, inicialize a Google Cloud CLI executando o seguinte comando: 

    gcloud init

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  5. (Opcional) Configure padrões para comandos da CLI gcloud.

Visão geral

O Ruby oferece suporte a dois métodos para autenticar solicitações ao repositório do Artifact Registry:

  • CLI do RubyGems: oferece suporte a solicitações de envio e recebimento. Essa CLI está disponível com o Ruby por padrão. Ao se autenticar com o RubyGems, você precisa se autenticar sempre que fizer uma solicitação de envio ou solicitação de pull ao repositório.

  • CLI do Bundler: oferece suporte a solicitações de recebimento. O Bundler armazena pacotes e fluxos de dados em um gemfile, o que permite que os usuários padronizem as configurações em várias máquinas sem precisar autenticar cada solicitação de envio individual. No entanto, ainda é necessário autenticar novamente suas credenciais no Bundler ocasionalmente.

    Para instalar a CLI do Bundler, insira gem install bundler.

Autenticar com a CLI do RubyGems

A CLI do RubyGems usa tokens OAuth2 para autenticar uma solicitação. Para transmitir tokens OAuth2 para chamadas aos repositórios do Artifact Registry, você deve primeiro gerar o token e transmiti-lo com o endereço do repositório ao fazer uma solicitação. Os tokens têm um período de validade de uma hora e precisam ser atualizados a cada hora.

Autenticar solicitações de recebimento

É possível autenticar uma solicitação de envio na linha de comando da Google Cloud CLI ou atualizando o arquivo .gemrc.

Autenticar solicitações de recebimento na linha de comando

Para autenticar a versão mais recente da gem na solicitação de envio, execute o seguinte comando:

export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
gem install GEM_NAME --source https://$GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Para autenticar uma versão específica da gema, adicione -v GEM_VERSION ao comando gem install.

Em que:

  • GEM_NAME é o nome da gema para a qual a solicitação é feita.
  • LOCATION é o local regional ou multirregional location do repositório.
  • PROJECT é o ID do projeto que contém o repositório.
  • REPOSITORY é o ID do repositório.

Autenticar em um arquivo .gemrc

É possível configurar o arquivo /.gemrc global ou específico do projeto para autenticar suas fontes em solicitações de recebimento adicionando o seguinte:

# File: ~/.gemrc

# Use the GEM_TOKEN retrieved from export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"

<...>
:sources:
    - https://GEM_TOKEN@LOCATION-ruby.pkg.dev/PROJECT/REPO/
<...>

Para instalar uma gema usando a origem ou as origens definidas no arquivo /.gemrc, execute:

gem install GEM_NAME

Autenticar solicitações de envio

É possível autenticar uma solicitação de envio na linha de comando da Google Cloud CLI ou atualizando o arquivo de credenciais.

Autenticar solicitações de envio na linha de comando

Para autenticar a solicitação de envio, execute o seguinte comando:

export GEM_HOST_API_KEY="Bearer $(gcloud auth print-access-token)"
gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Em que:

  • GEM_NAME é o nome da gema para a qual a solicitação é feita.
  • LOCATION é o local regional ou multirregional location do repositório.
  • PROJECT é o ID do projeto que contém o repositório.
  • REPOSITORY é o ID do repositório.

Autenticar solicitações de envio em um arquivo de credenciais

A ferramenta de linha de comando gem usa o arquivo ~/.gem/credentials para armazenar chaves de API para envio e recebimento de gemas. Para configurar o arquivo de credenciais para autenticar suas fontes em solicitações de envio, faça o seguinte:

  1. Gere um token de acesso OAuth2 executando o seguinte comando:

    gcloud auth print-access-token

    Esse token funciona como sua chave de API para o Artifact Registry.

  2. Atualize o arquivo de credenciais:

    1. Abra ~/.gem/credentials e adicione uma linha para o repositório. A chave é o URL do repositório, e o valor é Bearer, seguido pelo token:

      :rubygems_api_key: RUBYGEMS_ORG_KEY
https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY: Bearer OAUTH_TOKEN

      Em que:

      • RUBYGEMS_ORG_KEY é a chave de API para RubyGems.org.
      • LOCATION é o local regional ou multirregional location do repositório.
      • PROJECT é o ID do projeto que contém o repositório.
      • REPOSITORY é o ID do repositório.
      • OAUTH_TOKEN é o token de acesso OAuth2.

    2. Envie a gema. Não é necessário definir a GEM_HOST_API_KEY, já que você definiu a chave no arquivo de credenciais.

      gem push GEM_NAME --host https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY

Autenticar com o Bundler

O Ruby Bundler gerencia dependências de aplicativos em uma ou mais gemas. Para configurar o Bundler, faça o seguinte:

  1. Adicione o endereço do repositório como uma source no gemfile:

    # Gemfile
# <...>
source "https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"

  2. Autentique-se no repositório usando bundle config:

    export GEM_TOKEN="oauth2accesstoken:$(gcloud auth print-access-token)"
export HOST="https://LOCATION-ruby.pkg.dev/PROJECT/REPOSITORY"
bundle config $HOST $GEM_TOKEN

Em que:

  • LOCATION é o local regional ou multirregional location do repositório.
  • PROJECT é o ID do projeto. Se essa sinalização for omitida, o projeto atual ou padrão é usado.
  • REPOSITORY é o ID do repositório. Se você tiver configurado um repositório do Artifact Registry padrão, ele será usado quando essa sinalização for omitida no comando.

É necessário autenticar novamente o repositório remoto ocasionalmente. Nesse caso, execute o mesmo comando de autenticação da etapa 2.

Para mais informações sobre como configurar o Bundler, consulte Gemfiles na documentação do bundler.io.

A seguir