Nesta página, descrevemos as seguintes tarefas:
- Como visualizar e excluir pacotes e versões de pacote
- Como visualizar, criar, atualizar e excluir tags
Antes de começar
- Se não existir um repositório de destino, crie um novo repositório.
- Verifique se você tem as permissões necessárias para o repositório.
- Configure a autenticação do npm.
- (Opcional) Configure padrões para comandos gcloud.
- Se você estiver usando o auxiliar de credenciais do npm para autenticação, obtenha um token de acesso antes de se conectar a um repositório com o npm.
Funções exigidas
Para receber as permissões necessárias para gerenciar pacotes, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:
-
Conferir pacotes, arquivos em pacotes e tags:
Leitor do Artifact Registry (
roles/artifactregistry.reader
) -
Faça o download ou instale pacotes:
Leitor do Artifact Registry (
roles/artifactregistry.reader
) -
Adicione pacotes a um repositório:
Gravador do Artifact Registry (
roles/artifactregistry.writer
) -
Exclua pacotes:
Administrador do repositório do Artifact Registry (
roles/artifactregistry.repoAdmin
)
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 por meio de papéis personalizados ou de outros papéis predefinidos.
Como conseguir um token de acesso
Os tokens de acesso são válidos por 60 minutos. Gere um token de acesso em breve antes de executar comandos que interagem com repositórios.
Para receber um token, use uma destas opções:
Use o comando
npx
para atualizar o token de acesso.Verifique se as credenciais para se conectar ao registro npm público estão no arquivo de configuração do npm do usuário,
~/.npmrc
.Execute o seguinte comando no diretório do projeto Node.js.
npx google-artifactregistry-auth
Se o repositório do Artifact Registry estiver definido como registro global e os pacotes não tiverem escopo, use o comando abaixo para que ele possa fazer o download do auxiliar de credenciais do registro npm público em vez do repositório do Artifact Registry.
npm_config_registry=https://registry.npmjs.org npx google-artifactregistry-auth
Adicione um script ao arquivo
package.json
no seu projeto."scripts": { "artifactregistry-login": "npx google-artifactregistry-auth" }
Execute o script no diretório do projeto Node.js.
npm run artifactregistry-login
O Artifact Registry lê as configurações do repositório do Artifact Registry no
arquivo .npmrc
do projeto e as usa para adicionar credenciais de token ao seu usuário
.npmrc
. Armazenar o token no arquivo .npmrc
do usuário isola seu
credenciais do código-fonte e do sistema de controle de origem.
Como adicionar pacotes
Modos de repositório: padrão
Só é possível publicar uma versão específica de um pacote uma vez. Essa é uma restrição de npm para garantir que o conteúdo de uma versão de pacote publicada seja sempre o mesmo. Como resultado, você não poderá:
- Substituir uma versão do pacote publicando-a novamente no repositório
- Remover um pacote ou sua versão do repositório e, em seguida, publicar um pacote com o mesmo nome e número da versão
Se você não especificar uma tag ao publicar um pacote, o npm adicionará a tag latest
.
Para simplificar a instalação dos pacotes em um estágio específico de desenvolvimento,
publique os pacotes com uma tag, como beta
ou dev
.
O Artifact Registry exige nomes de pacotes alfanuméricos em letras minúsculas para pacotes npm.
Para adicionar um pacote:
Verifique se o nome do pacote em
package.json
inclui o escopo configurado para seu repositório. O exemplo a seguir mostra um pacote com o escopodev-repo
."name": "@dev-repo/my-package"
Se você estiver usando o auxiliar de credenciais para fazer a autenticação com um token de acesso, obtenha um novo token.
Adicione pacotes ao repositório. Use um comando
npm
ouyarn
.Para incluir uma tag no pacote, inclua a flag
--tag
e substitua TAG. com a tag que você quer usar. Se você não incluir a flag--tag
, o npm definirá a tag comolatest
automaticamente.npm publish --tag=TAG
yarn publish --tag TAG
Como visualizar pacotes e versões
Modos de repositório: padrão, remoto, virtual
Para conferir informações do pacote com npm
ou yarn
:
Se você estiver usando o auxiliar de credenciais para fazer a autenticação com um token de acesso, obtenha um novo token.
Execute o comando apropriado:
npm view
yarn info
Para conferir os pacotes e as versões deles usando o console do Google Cloud
ou gcloud
:
Console
Abra a página Repositórios no console do Google Cloud.
Na lista de repositórios, clique no repositório apropriado.
A página Pacotes lista os pacotes no repositório.
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]
Onde
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um regional ou multirregional local. Use esta sinalização para ver 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 ver as versões de um pacote, execute o seguinte comando:
gcloud artifacts versions list --package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION]
Onde
- 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, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um regional ou multirregional local. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.
Visualizar pacotes e versões no console do Google Cloud ou CLI gcloud está disponível apenas para repositórios padrão e remotos.
Para repositórios remotos, a lista retornada precisa incluir todas as dependências diretas e transitivas armazenadas em cache no repositório.
Como listar arquivos
Modos de repositório: padrão, remoto
É possível listar arquivos em um repositório, arquivos em todas as versões de um ou arquivos 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
gcloud artifacts files list \
--project=PROJECT \
--repository=REPOSITORY \
--location=LOCATION \
--package=PACKAGE \
--tag=TAG
Substitua os seguintes valores:
LOCATION
: o regional ou multirregional local do repositório.PROJECT
: seuID de projeto no Google Cloud. Se o ID do projeto contiver dois pontos (`:`), consulte Projetos com escopo de domínio.REPOSITORY
: o nome do repositório em que a imagem são armazenados.PACKAGE
: o nome do pacote.VERSION
: a versão do pacote.TAG
: a tag associada ao 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
1.0
do pacote.
gcloud artifacts files list \
--project=my-project \
--location=us-west1 \
--repository=my-repo \
--package=my-app \
--version=1.0
1.0-dev
.
gcloud artifacts files list \
--project=my-project \
--location=us-west1 \
--repository=my-repo \
--package=my-app \
--tag=1.0-dev
Como marcar pacotes
Modos de repositório: padrão
Você pode ver, adicionar, atualizar e excluir tags. As tags podem ajudar a gerenciar versões semânticas dos pacotes e agilizar a instalação deles em um estágio específico de desenvolvimento.
Por exemplo, é possível marcar o build candidato a lançamento atual com rc
. Seu
a equipe poderá instalar a versão correta com base na tag em vez de
especificador de versão, e o cancelamento da publicação de versões de pré-lançamento não usadas não causará problemas
suas dependências no pacote candidato a lançamento.
Como visualizar tags
Para ver as tags de um pacote:
Console
Abra a página Repositórios no console do Google Cloud.
Clique no pacote para visualizar as versões e tags associadas.
Selecione a versão do pacote a ser marcada.
Na linha da versão selecionada, clique em Mais ações () e, em seguida, clique em Editar tags.
Insira novas tags no campo e clique em SALVAR.
gcloud
Execute o comando:
gcloud artifacts tags list --package=PACKAGE \
[--repository=REPOSITORY] [--location=LOCATION]
Onde
- PACKAGE é o nome do pacote no repositório.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
Por exemplo, para visualizar tags para o pacote my-package
no repositório
my-repo
no local padrão, execute o comando:
gcloud artifacts tags list --package=my-pkg --repository=my-repo
Como criar tags
Você pode criar uma tag para uma versão específica de um pacote.
Para adicionar uma tag em uma imagem atual em um repositório:
Console
Abra a página Repositórios no console do Google Cloud.
Clique no pacote para visualizar as versões do pacote.
Selecione a versão do pacote a ser adicionar a tag.
Na linha da versão selecionada, clique em Mais ações () e, em seguida, clique em Editar tags.
Insira novas tags no campo e clique em SALVAR.
gcloud
Execute este comando:
gcloud artifacts tags create TAG --package=PACKAGE \
version=VERSION [--location=LOCATION] [--repository=REPOSITORY]
Onde
- TAG é a tag que você quer aplicar ao pacote.
- PACKAGE é o nome do pacote no repositório.
- VERSION é a versão do pacote que você quer adicionar a tag.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
Por exemplo, para criar a tag release-candidate
para a versão 1.0.0
do pacote
my-package
no repositório my-repo
no local padrão, execute o
comando:
gcloud artifacts tags create release-candidate --version=1.0.0 \
--package=my-pkg --repository=my-repo
Como atualizar tags
É possível alterar uma tag associada a uma versão do pacote.
Para alterar uma tag existente, faça o seguinte:
Console
Abra a página Repositórios no console do Google Cloud.
Clique no pacote para visualizar as versões do pacote.
Selecione a versão do pacote com a tag a ser alterada.
Na linha da versão selecionada, clique em Mais ações () e, em seguida, clique em Editar tags.
Edite a tag e clique em SALVAR.
gcloud
Execute este comando:
gcloud artifacts tags update TAG --package=PACKAGE \
version=VERSION [--location=LOCATION] [--repository=REPOSITORY]
Onde
- TAG é a tag que você quer aplicar ao pacote.
- PACKAGE é o nome do pacote no repositório.
- VERSION é a versão do pacote que você quer adicionar a tag.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
Por exemplo, para alterar a tag da versão 1.0.0
do pacote
my-package
para production
no repositório my-repo
no local padrão,
execute o comando:
gcloud artifacts tags update production --version=1.0.0 \
--package=my-pkg --repository=my-repo
Como desmarcar versões do pacote
É possível remover uma tag existente de uma versão de pacote.
Para remover uma tag:
Console
Abra a página Repositórios no console do Google Cloud.
Clique na imagem para ver as versões dela.
Selecione a versão da imagem para remover a tag.
Na linha da versão selecionada, clique em Mais ações () e, em seguida, clique em Editar tags.
Exclua a tag e clique em SALVAR.
gcloud
Execute este comando:
gcloud artifacts tags delete TAG --package=PACKAGE \
[--location=<LOCATION] [--repository=REPOSITORY]
Onde
- TAG é a tag que você quer aplicar ao pacote.
- PACKAGE é o nome do pacote no repositório.
- LOCATION é um local regional ou multirregional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa sinalização para usar o padrão.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
Por exemplo, para remover a tag release-candidate
do pacote
my-package
no repositório my-repo
no local
padrão, execute o comando:
gcloud artifacts tags delete release-candidate --package=my-pkg \
--repository=my-repo
Como instalar pacotes
Modos de repositório: padrão, remoto, virtual
Para instalar um pacote do repositório de pacotes do Node.js:
Se você estiver usando o auxiliar de credenciais para fazer a autenticação com um token de acesso, obtenha um novo token.
Use o comando
npm install
ouyarn add
.npm
Para instalar a versão com a tag
latest
:npm install @SCOPE/PACKAGE
Para instalar a versão com uma tag diferente:
npm install @SCOPE/PACKAGE@TAG
Para instalar uma versão específica:
npm install @SCOPE/PACKAGE@VERSION
yarn
Para instalar a versão com a tag
latest
:yarn add @SCOPE/PACKAGE
Para instalar a versão com uma tag diferente:
yarn add @SCOPE/PACKAGE@TAG
Para instalar uma versão específica:
yarn add @SCOPE/PACKAGE@VERSION
Substitua os seguintes valores:
- SCOPE é o escopo associado ao repositório. Se as
O repositório de pacotes Node.js não está configurado com um escopo. Omita
@SCOPE/
no comando. - PACKAGE é o nome do pacote no repositório.
- TAG é a tag da versão que você quer instalar.
- VERSION é o número da versão que você quer instalar.
- SCOPE é o escopo associado ao repositório. Se as
O repositório de pacotes Node.js não está configurado com um escopo. Omita
Ao especificar um pacote como dependência em package.json
, verifique se
inclua o escopo do repositório. O exemplo a seguir mostra o
escopo @dev-repo
de um pacote chamado my-package
.
"dependencies": {
"@dev-repo/my-package": ">=1.0.0"
}
Para repositórios padrão, você faz o download de um pacote diretamente do repositório.
Para um repositório remoto, você faz o download de uma cópia em cache do pacote e das dependências. Se uma cópia em cache não existir, o repositório remoto vai fazer o download do pacote da origem upstream e armazená-lo em cache antes de exibi-lo para você. É possível verificar se o repositório remoto recuperou os pacotes da origem upstream conferindo a lista de pacotes no repositório.
Para um repositório virtual, o Artifact Registry pesquisa repositórios upstream para o pacote solicitado.
- Os repositórios remotos upstream vão fazer o download e armazenar em cache o pacote solicitado se uma cópia em cache não existe. Os repositórios virtuais disponibilizam somente solicitações pacotes, eles 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 como100
secondary-repo1
: prioridade definida como80
.secondary-repo2
: prioridade definida como80
.test-repo
: prioridade definida como20
.
main-repo
tem o valor de prioridade mais alto, então o repositório virtual
sempre pesquisa primeiro.
A prioridade de secondary-repo1
e secondary-repo2
está definida como 80
. Se um
pacote solicitado não estiver disponível em main-repo
, o Artifact Registry
procurará esses repositórios em seguida. Como ambas têm o mesmo valor de prioridade,
O Artifact Registry pode exibir um pacote de qualquer repositório
se a versão estiver disponível em ambas.
test-repo
tem o menor valor de prioridade e servirá um artefato armazenado se
nenhum dos outros repositórios upstream a tem.
Como excluir pacotes
Modos de repositório: padrão, remoto
Você pode excluir um pacote e todas as versões dele ou excluir 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 origem upstream não é afetada. Se você excluir um pacote armazenado em cache, O Artifact Registry vai fazer o download e armazenar em cache novamente na próxima vez que recebe uma solicitação para a mesma versão do pacote.
Depois que uma versão do pacote é publicada, não é possível republicar um pacote com o mesmo nome e combinação de versões, mesmo após excluir a versão. Essa é uma restrição npm para garantir que o conteúdo de uma versão de pacote publicada seja sempre o mesmo.
Se você quiser incentivar os usuários a instalar uma versão atualizada do pacote, use o comando npm deprecate para marcar a versão antiga do pacote como obsoleta. Quando um usuário tenta instalar o pacote obsoleto, o Artifact Registry retorna um aviso de suspensão de uso.
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
Abra a página Repositórios no console do Google Cloud.
Na lista de repositórios, clique no repositório apropriado.
A página Pacotes lista os pacotes no repositório.
Selecione o pacote que você quer excluir.
Clique em EXCLUIR.
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]
Onde
- PACKAGE é o nome do pacote no repositório.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um local regional. Use esta sinalização para ver repositórios em um local específico. Se você configurado um local padrão, é possível omitir essa sinalização para padrão.
--async
Retorna imediatamente, sem aguardar a conclusão da operação em andamento.
Para excluir versões de um pacote:
Console
Abra a página Repositórios no console do Google Cloud.
Na lista de repositórios, clique no repositório apropriado.
A página Pacotes lista os pacotes no repositório.
Clique em um pacote para visualizar as versões dele.
Selecione as versões que você quer excluir.
Clique em EXCLUIR.
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]
Onde
- PACKAGE é o nome do pacote no repositório.
- REPOSITORY é o nome do repositório. Se você tiver configurado um repositório padrão, você pode omitir essa sinalização para usar o padrão.
- LOCATION é um local regional. Use esta sinalização para ver repositórios em um local específico. Se você tiver configurado um local padrão, poderá omitir essa flag para usar o padrão.
--async
retorna imediatamente, sem aguardar a conclusão da operação em andamento.
A seguir
- Saiba como gerenciar pacotes Maven
- Saiba mais sobre como gerenciar imagens de contêiner
- Fazer o download de arquivos individuais em um pacote