Gerenciar gems do Ruby

Nesta página, descrevemos como adicionar, visualizar e excluir gems do Ruby e versões de gem.

Antes de começar

  1. Instale e inicialize a Google Cloud CLI.

    A Google Cloud CLI versão 354.0.0 ou mais recente é necessária para executar comandos em repositórios Ruby. Para verificar a versão, use o comando:

    gcloud version

  2. Se o repositório de destino não existir, crie um repositório de pacotes Ruby.

  3. Verifique se o Ruby está instalado. Para instruções de instalação, consulte o Google Cloud tutorial de configuração do Ruby.

  4. (Opcional) Defina padrões para comandos gcloud.

Funções exigidas

Para receber as permissões necessárias para gerenciar gems, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Adicionar Gems

Os pacotes em Ruby são chamados de gems, e cada gem tem um nome, uma versão e uma plataforma. Um projeto Ruby também precisa conter um gemfile, que é um arquivo de configuração que especifica as dependências de gem necessárias.

Modos de repositório: padrão

Ao criar um projeto Ruby, os arquivos de distribuição são salvos em um subdiretório lib no projeto. Em seguida, use o RubyGems para fazer upload de gems em um repositório padrão.

Para adicionar uma gem ao seu repositório do Artifact Registry:

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

Em que:

  • GEM_NAME é o nome da gem a ser enviada por push para o repositório.
  • LOCATION é o local do repositório.
  • PROJECT é o ID do projeto. Se essa flag for omitida, o projeto padrão ou atual será usado.
  • REPOSITORY é o nome do seu repositório no Artifact Registry.

Ver Gems e versões

Modos de repositório: padrão

Para conferir pacotes e versões de pacotes usando o console Google Cloud ou gcloud:

Console

  1. Abra a página Repositórios no console do Google Cloud .

    Abrir a página Repositórios

  2. Na lista de repositórios, clique no repositório apropriado.

    A página Pacotes lista os pacotes no repositório.

  3. Clique em um pacote para visualizar as versões dele.

gcloud

Para listar pacotes em um repositório, execute o seguinte comando:

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

Substitua:

  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
  • LOCATION é o local regional ou multirregional do repositório. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.

Para ver as versões de um pacote, execute o seguinte comando:

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Substitua:

  • PACKAGE é o ID do pacote ou o identificador totalmente qualificado do pacote.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
  • LOCATION é o local regional ou multirregional do repositório. Use esta flag para conferir repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.

Para repositórios remotos, a lista retornada precisa incluir todas as dependências diretas e transitivas.

Listar arquivos

Modos de repositório: padrão

É possível listar arquivos em um repositório, em todas as versões de um pacote especificado ou em uma versão específica de um pacote.

Para todos os comandos a seguir, é possível definir um número máximo de arquivos a serem retornados adicionando a flag --limit ao comando.

Para listar todos os arquivos no projeto, repositório e local padrão quando os valores padrão estiverem configurados:

gcloud artifacts files list

Para listar arquivos em um projeto, repositório e local especificados, execute o comando:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

Para listar arquivos de todas as versões de um pacote específico:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

Para listar arquivos de uma versão específica do pacote:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

Substitua os seguintes valores:

  • LOCATION: o local regional ou multirregional do repositório.
  • PROJECT: o ID do projeto do Google Cloud . Se o ID do projeto tiver dois pontos (:), consulte Projetos com escopo de domínio.
  • REPOSITORY: o nome do repositório em que a imagem está armazenada.
  • PACKAGE: o nome do pacote.
  • VERSION: a versão do pacote.

Exemplos

Considere as seguintes informações do pacote:

  • Projeto: my-project
  • Repositório: my-repo
  • Local do repositório: us-west1
  • Pacote: my-app

O comando a seguir lista todos os arquivos no repositório my-repo no local us-west1 no projeto padrão:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo
O comando a seguir lista os arquivos na versão 1.0 do pacote.

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

Instalar gems

Modos de repositório: padrão

Para instalar a versão estável mais recente de um pacote:

gem install GEM_NAME

No caso de repositórios padrão, você baixa um pacote diretamente do repositório.

Para um repositório remoto, faça o download de uma cópia em cache do pacote e das dependências dele. Se não houver uma cópia em cache, o repositório remoto vai baixar o pacote da origem upstream e armazená-lo em cache antes de disponibilizá-lo para você. Para verificar se o repositório remoto recuperou os pacotes da origem upstream, confira a lista de pacotes no repositório.

Para um repositório virtual, o Artifact Registry pesquisa nos repositórios upstream o pacote solicitado.

  • Os repositórios remotos upstream vão fazer o download e armazenar em cache o pacote solicitado se não houver uma cópia em cache. Os repositórios virtuais só atendem aos pacotes solicitados, não os armazenam.
  • Se você solicitar uma versão disponível em mais de um repositório upstream, o Artifact Registry vai escolher um repositório upstream para usar com base nas configurações de prioridade configuradas para o repositório virtual.

Por exemplo, considere um repositório virtual com as seguintes configurações de prioridade para repositórios upstream:

  • main-repo: prioridade definida como 100
  • secondary-repo1: prioridade definida como 80.
  • secondary-repo2: prioridade definida como 80.
  • test-repo: prioridade definida como 20.

main-repo tem o maior valor de prioridade, então o repositório virtual sempre o pesquisa primeiro.

secondary-repo1 e secondary-repo2 têm a prioridade definida como 80. Se um pacote solicitado não estiver disponível em main-repo, o Artifact Registry vai pesquisar nesses repositórios. Como ambos têm o mesmo valor de prioridade, o Artifact Registry pode veicular um pacote de qualquer repositório se a versão estiver disponível nos dois.

test-repo tem o menor valor de prioridade e vai veicular um artefato armazenado se nenhum dos outros repositórios upstream tiver esse artefato.

Informações adicionais

Quando você envia ou extrai gems de um repositório do Artifact Registry, se o gem solicitado ou as dependências dele não forem encontrados no repositório especificado, o cliente gem usará qualquer outra origem definida no Gemfile do gem. Se você quiser apenas buscar e instalar diretamente do Artifact Registry, execute o seguinte comando para remover uma fonte que não seja do Artifact Registry do seu gemfile:

gem sources --remove SOURCE

Para adicionar rubygems.org de volta como uma origem:

gem sources --add SOURCE

Em que SOURCE é o endereço da origem, como https://rubygems.org.

Excluir pacotes e versões

Modos de repositório: padrão

É possível excluir um pacote e todas as versões dele ou uma versão específica.

  • Depois de excluir um pacote, não é possível desfazer a ação.
  • Para repositórios remotos, apenas a cópia em cache do pacote é excluída. A fonte upstream não é afetada. Se você excluir um pacote em cache, o Artifact Registry vai fazer o download e armazenar em cache novamente na próxima vez que o repositório receber uma solicitação para a mesma versão do pacote.

Antes de excluir uma versão de pacote ou um pacote, verifique se você comunicou ou resolveu qualquer dependência importante nele.

Para excluir um pacote:

Console

  1. Abra a página Repositórios no console do Google Cloud .

    Abrir a página Repositórios

  2. Na lista de repositórios, clique no repositório apropriado.

    A página Pacotes lista os pacotes no repositório.

  3. Selecione o pacote que você quer excluir.

  4. Clique em EXCLUIR.

  5. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Substitua:

  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
  • LOCATION é o local regional ou multirregional do repositório. Use esta flag para conferir repositórios em um local específico. Se você configurou um local padrão, poderá omitir essa flag para usar o padrão.

A flag --async faz com que o comando seja retornado imediatamente, sem aguardar a conclusão da operação em andamento.

Para excluir versões de um pacote:

Console

  1. Abra a página Repositórios no console do Google Cloud .

    Abrir a página Repositórios

  2. Na lista de repositórios, clique no repositório apropriado.

    A página Pacotes lista os pacotes no repositório.

  3. Clique em um pacote para visualizar as versões dele.

  4. Selecione as versões que você quer excluir.

  5. Clique em EXCLUIR.

  6. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Execute este comando:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Substitua:

  • VERSION é o nome da versão a ser excluída.
  • PACKAGE é o nome do pacote no repositório.
  • REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, poderá omitir essa flag para usar o padrão.
  • LOCATION é o local regional ou multirregional do repositório. Use esta flag para conferir repositórios em um local específico. Se você configurou um local padrão, poderá omitir essa flag para usar o padrão.

A flag --async faz com que o comando seja retornado imediatamente, sem aguardar a conclusão da operação em andamento.

Limitações

  • O Artifact Registry não aceita a adição de repositórios como fontes usando o comando gem sources -add. No entanto, é possível adicionar fontes manualmente ao arquivo .gemrc ou transmitir a flag --source diretamente no comando gem.

  • O Artifact Registry não é compatível com o pull de gems usando gem fetch.

A seguir