Diretrizes para a configuração de registros privados para o Dependabot

Este artigo contém informações detalhadas sobre como configurar registros privados, bem como sobre os comandos que podem ser executados a partir da linha de comando para configurar localmente os gerenciadores de pacotes.

Quem pode usar esse recurso?

Usuários com com acesso para gravação

Neste artigo

Como configurar registros privados no Dependabot

Este artigo contém recomendações e conselhos para ajudá-lo a configurar o Dependabot para acessar seu registro privado, juntamente com:

  • Trechos detalhados do arquivo de configuração dependabot.yml de cada gerenciador de pacotes.
  • Limitações ou ressalvas importantes.
  • Explicações em etapas sobre como testar o funcionamento da configuração.
  • Opções extras de configuração, sempre que apropriado (por exemplo, quando o npm tiver um arquivo de configuração que precisa ser configurado).
  • Orientações sobre como configurar hosts de registro.

Você encontrará orientações detalhadas para a configuração dos seguintes gerenciadores de pacotes:

Você também encontrará recomendações para a configuração dos seguintes hosts de registro:

Como configurar gerenciadores de pacotes

Bundler

Compatível com o Artifactory, Artifacts, Cloudsmith, GitHub Packages Registro, Nexus e ProGet.

É possível realizar a autenticação com um nome de usuário e senha ou com um token. Para obter mais informações, confira rubygems-server em Configurando o acesso a registros privados para Dependabot.

Trecho de um arquivo dependabot.yml usando um nome de usuário e senha.

YAML
registries:
  ruby-example:
    type: rubygems-server
    url: https://rubygems.example.com
    username: octocat@example.com
    password: ${{secrets.MY_RUBYGEMS_PASSWORD}}

O trecho do arquivo dependabot.yml abaixo usa um token. Nesse tipo de registro que usa o GitHub Packages (xyz.pkg.github.com), o token é, na verdade, um GitHub personal access token (PAT).

YAML
registries:
  ruby-github:
    type: rubygems-server
    url: https://rubygems.pkg.github.com/octocat/github_api
    token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}

Observações

As dependências originadas diretamente de um repositório do GitHub dão ao Dependabot acesso ao repositório por meio da interface do usuário do GitHub. Para obter informações sobre como permitir que o Dependabot acesse dependências privadas do GitHub, confira Permitindo que o Dependabot acesse dependências privadas.

Docker

O Docker oferece suporte ao uso de um nome de usuário e senha para registros. Para obter mais informações, confira docker-registry em Configurando o acesso a registros privados para Dependabot.

Trecho de arquivo dependabot.yml usando um nome de usuário e senha.

YAML
registries:
  dockerhub:
    type: docker-registry
    url: https://registry.hub.docker.com
    username: octocat
    password: ${{secrets.MY_DOCKERHUB_PASSWORD}}

O docker-registry também pode ser usado para efetuar pull do Amazon ECR particular usando as credenciais estáticas da AWS.

YAML
registries:
  ecr-docker:
    type: docker-registry
    url: https://1234567890.dkr.ecr.us-east-1.amazonaws.com
    username: ${{secrets.ECR_AWS_ACCESS_KEY_ID}}
    password: ${{secrets.ECR_AWS_SECRET_ACCESS_KEY}}

Observações

O Dependabot funciona com todos os registros de contêiner que implementam a especificação de distribuição da OCI (Open Container Initiative). Para obter mais informações, consulte https://github.com/opencontainers/distribution-spec/blob/main/spec.md.

O Dependabot oferece suporte à autenticação em registros privados por meio de um serviço de token central ou autenticação básica HTTP. Para obter mais informações, confira Especificação de autenticação de token na documentação do Docker e a Autenticação de acesso básica na Wikipédia.

Limitações e soluções alternativas

Gradle

O Dependabot não executa o Gradle, mas dá suporte a atualizações a determinados arquivos Gradle. Para obter mais informações, consulte "Gradle” em Ecossistemas e repositórios compatíveis com o Dependabot.

O Gradle dá suporte ao tipo de registro maven-repository. Para obter mais informações, confira maven-repository em Configurando o acesso a registros privados para Dependabot.

O tipo maven-repository dá suporte a nome de usuário e senha. Se a conta for uma conta GitHub, você poderá usar um GitHub personal access token no lugar da senha.

YAML
registries:
  gradle-artifactory:
    type: maven-repository
    url: https://acme.jfrog.io/artifactory/my-gradle-registry
    username: octocat
    password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
updates:
  - package-ecosystem: "gradle"
    directory: "/"
    registries:
      - gradle-artifactory
    schedule:
      interval: "monthly"

Observações

Talvez você não veja todas as suas dependências representadas no gráfico de dependências, especialmente se algumas dependências forem dependências em tempo de compilação. Você pode usar o API de envio de dependência para informar o GitHub sobre suas outras dependências e receber atualizações de segurança para elas. Para saber mais, confira Usar a API de envio de dependências.

Maven

Maven oferece suporte à a autenticação com nome de usuário e senha. Para obter mais informações, confira maven-repository em Configurando o acesso a registros privados para Dependabot.

YAML
registries:
  maven-artifactory:
    type: maven-repository
    url: https://acme.jfrog.io/artifactory/my-maven-registry
    username: octocat
    password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}

Se a conta for uma conta GitHub, você poderá usar um GitHub personal access token no lugar da senha.

YAML
version: 2
registries:
  maven-github:
    type: maven-repository
    url: https://maven.pkg.github.com/octocat
    username: octocat
    password: ${{secrets.OCTOCAT_GITHUB_PAT}}
updates:
  - package-ecosystem: "maven"
    directory: "/"
    registries:
      - maven-github
    schedule:
      interval: "monthly"

Observações

Talvez você não veja todas as suas dependências representadas no gráfico de dependências, especialmente se algumas dependências forem dependências em tempo de compilação. Você pode usar o API de envio de dependência para informar o GitHub sobre suas outras dependências e receber atualizações de segurança para elas. Para saber mais, confira Usar a API de envio de dependências.

npm

Você pode definir a configuração no arquivo dependabot.yml usando o tipo npm-registry ou configurar o Dependabot para enviar todas as solicitações de registro por meio de uma URL base especificada.

Usando o tipo npm-registry no arquivo de configuração

É possível definir a configuração do registro privado em um arquivo dependabot.yml usando o tipo npm-registry. Para saber mais, confira Configurando o acesso a registros privados para Dependabot.

Abaixo, o trecho de um arquivo dependabot.yml usa um token. Nesse tipo de registro que usa o GitHub Packages (xyz.pkg.github.com), o token é, na verdade, um GitHub personal access token (PAT).

YAML
registries:
  npm-github:
    type: npm-registry
    url: https://npm.pkg.github.com
    token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}

Além disso, o ecossistema do npm requer a verificação de um arquivo .npmrc com a URL do registro privado no repositório.

Exemplo do conteúdo de um arquivo .npmrc:

registry=https://<private-registry-url>

De maneira alternativa, você pode adicionar a URL do registro privado a um arquivo .npmrc existente usando o comando a seguir.

npm config set registry <url>

Para obter mais informações, confira registro na documentação do npm.

Também é possível pode definir o escopo da configuração para somente uma única dependência ou organização. Nesse caso, o token só será válido para a organização, e tokens diferentes podem ser usados por organizações diferentes no mesmo repositório.

npm config set @<org-name>:registry <url>

Isso resultaria em um “.npmrc” com o registro:

@<org-name>:registry=https://<private-registry-url>

O npm pode ser configurado para usar a URL do registro privado em arquivos de bloqueio com replace-registry-host. Para obter mais informações, confira replace-registry-ho na documentação do npm.

npm config set replace-registry-host "never"

Se você usar replace-registry-host, deverá executar npm install localmente para regenerar o arquivo de bloqueio para usar a URL do registro privado. O Dependabot usará a mesma URL ao fornecer atualizações.

Depois que o registro estiver configurado, será possível executar npm login para verificar se a configuração está correta e válida. O arquivo de bloqueio também pode ser regenerado para usar o novo registro privado executando npm install novamente.

É necessário garantir que o arquivo .npmrc esteja no mesmo diretório do projeto package.json e que o arquivo não inclua nenhuma variável de ambiente ou segredos. Se você usar um repositório único, o arquivo .npmrc deverá ficar no diretório raiz do projeto.

Como configurar o Dependabot para enviar solicitações de registro por meio de uma URL base especificada

Você pode configurar o Dependabot para enviar solicitações de registro por meio de uma URL base especificada. Para que o Dependabot acesse uma dependência pública, o registro deve ter uma cópia clonada da dependência com a versão solicitada ou permitir tráfego para efetuar fetch de um registro público se a dependência não estiver disponível.

Se não houver um registro global definido em um arquivo .npmrc, configure replaces-base como true no arquivo dependabot.yml. Para obter mais informações, confira "replaces-base" em Chave registries de nível superior.

Observações

As dependências originadas diretamente de um repositório do GitHub dão ao Dependabot acesso ao repositório por meio da interface do usuário do GitHub. Para obter informações sobre como permitir que o Dependabot acesse dependências privadas do GitHub, confira Permitindo que o Dependabot acesse dependências privadas.

Para as dependências com escopo (@my-org/my-dep), o Dependabot exige que o registro privado seja definido no arquivo .npmrc do projeto. Para definir registros privados para escopos individuais, use @myscope:registry=https://private_registry_url.

Os registros devem ser configurados usando o protocolo https.

NuGet

Compatível com o Artifactory, Artifacts, Cloudsmith, GitHub Packages Registro, Nexus e ProGet.

O tipo nuget-feed dá suporte a nome de usuário e senha ou a um token. Para obter mais informações, confira nuget-feed em Configurando o acesso a registros privados para Dependabot.

YAML
registries:
  nuget-example:
    type: nuget-feed
    url: https://nuget.example.com/v3/index.json
    username: octocat@example.com
    password: ${{secrets.MY_NUGET_PASSWORD}}
YAML
registries:
  nuget-azure-devops:
    type: nuget-feed
    url: https://pkgs.dev.azure.com/.../_packaging/My_Feed/nuget/v3/index.json
    username: octocat@example.com
    password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}}

Observações

Você também pode usar um token no seu arquivo dependabot.yml. Nesse tipo de registro que usa o GitHub Packages (xyz.pkg.github.com), o token é, na verdade, um GitHub personal access token (PAT).

YAML
registries:
  nuget-azure-devops:
    type: nuget-feed
    url: https://pkgs.dev.azure.com/.../_packaging/My_Feed/nuget/v3/index.json
    token: ${{secrets.MY_AZURE_DEVOPS_TOKEN}}

Python

Compatível com Artifactory, Azure Artifacts, Nexus e ProGet. O registro de GitHub Packages não é compatível.

O tipo python-index dá suporte a nome de usuário e senha ou a um token. Para obter mais informações, confira python-index em Configurando o acesso a registros privados para Dependabot.

YAML
registries:
  python-example:
    type: python-index
    url: https://example.com/_packaging/my-feed/pypi/example
    username: octocat
    password: ${{secrets.MY_BASIC_AUTH_PASSWORD}}
YAML
registries:
  python-azure:
    type: python-index
    url: https://pkgs.dev.azure.com/octocat/_packaging/my-feed/pypi/example
    username: octocat@example.com
    password: ${{secrets.MY_AZURE_DEVOPS_TOKEN}}
YAML
registries:
  python-gemfury:
    type: python-index
    url: https://pypi.fury.io/my_org
    token: ${{secrets.MY_GEMFURY_TOKEN}}

Observações

As dependências originadas diretamente de um repositório do GitHub dão ao Dependabot acesso ao repositório por meio da interface do usuário do GitHub. Para obter informações sobre como permitir que o Dependabot acesse dependências privadas do GitHub, confira Permitindo que o Dependabot acesse dependências privadas.

url deve conter a URL, a organização e o "feed" ou repositório.

Yarn

O registro Yarn usa uma configuração semelhante à do registro npm. Para obter mais informações, confira "npm-registry" em Configurando o acesso a registros privados para Dependabot.

YAML
registries:
  yarn-github:
    type: npm-registry
    url: https://npm.pkg.github.com
    token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
  • Para registros privados, é necessário fazer check-in de um arquivo .yarnrc.yml (no Yarn 3) ou um arquivo .yarnrc (no Yarn Classic).
  • Os arquivos de configuração yarn não devem conter variáveis de ambiente.
  • Os registros particulares listados no arquivo dependabot.yml devem ser configurados via https.

Yarn Classic

É possível especificar a configuração do registro privado no arquivo dependabot.yml ou configurar o Yarn Classic de acordo com as instruções padrão do gerenciador de pacotes.

Definindo a configuração de registro privado no arquivo dependabot.yml

Você pode definir a configuração de registro privado no seu arquivo dependabot.yml. Para obter mais informações, confira Chave registries de nível superior.

Para garantir que o registro privado seja listado como a fonte de dependência no arquivo yarn.lock do projeto, execute yarn install em um computador com acesso ao registro privado. O yarn deve atualizar o campo resolvido para incluir a URL do registro privado.

encoding@^0.1.11:
  version "0.1.13"
  resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9"
  integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==
  dependencies:
    iconv-lite "^0.6.2"
Seguindo as instruções padrão do seu gerenciador de pacotes

Se o arquivo yarn.lock não listar o registro privado como a fonte de dependência, será possível configurar o Yarn Classic de acordo com as instruções padrão do gerenciador de pacotes.

  1. Defina a configuração do registro privado no arquivo dependabot.yml.

  2. Você pode escolher uma das ações a seguir:

    • Definir manualmente o registro privado no arquivo .yarnrcadicionando o registro a um arquivo .yarnrc.yml na raiz do projeto com o registro principal, ou
    • Realizar a mesma ação executando yarn config set registry <private registry URL> em seu terminal.

    Exemplo de um .yarnrc com um registro privado definido: registry https://nexus.example.com/repository/yarn-all

Yarn Berry (v3)

Para obter informações sobre configuração, consulte Configurações (.yarnrc.yml) na documentação do Yarn.

Assim como no Yarn Classic, é possível especificar a configuração do registro privado no arquivo dependabot.yml ou configurar o Yarn Berry de acordo com as instruções padrão do gerenciador de pacotes.

Definindo a configuração de registro privado no arquivo dependabot.yml

Você pode definir a configuração de registro privado no seu arquivo dependabot.yml. Para obter mais informações, confira Chave registries de nível superior.

Para garantir que o registro privado esteja listado como a fonte de dependência no arquivo yarn.lock do projeto, execute yarn install em um computador com acesso ao registro privado. O yarn deve atualizar o campo resolvido para incluir a URL do registro privado.

encoding@^0.1.11:
  version "0.1.13"
  resolved "https://private_registry_url/encoding/-/encoding-0.1.13.tgz#56574afdd791f54a8e9b2785c0582a2d26210fa9"
  integrity sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==
  dependencies:
    iconv-lite "^0.6.2"

Também é possível configurar registros privados com npmAuthIdent ou npmAuthToken. Para saber mais, confira "npmAuthIdent" and "npmAuthToken" na documentação do Yarn.

yarn config set registry <url>

É possível definir o escopo da configuração para abranger apenas uma única dependência ou organização.

yarn config set @<SCOPE>:registry <url>

Para finalizar, recomendamos que você execute yarn login para verificar se sua configuração está correta e válida. O arquivo de bloqueio também pode ser regenerado para usar o novo registro privado executando yarn install novamente.

Seguindo as instruções padrão do seu gerenciador de pacotes

Se o arquivo yarn.lock não listar o registro privado como a fonte de dependência, será possível configurar o Yarn Berry de acordo com as instruções padrão do gerenciador de pacotes.

  1. Defina a configuração do registro privado no arquivo dependabot.yml.

  2. Você pode escolher uma das ações a seguir:

    • Definir manualmente o registro privado para o arquivo .yarnrcadicionando o registro a um arquivo .yarnrc.yml na raiz do projeto com a chave npmRegistryServer, ou
    • Realizar a mesma ação executando yarn config set npmRegistryServer <private registry URL> em seu terminal.

    Exemplo de um arquivo .yarnrc.yml com um registro privado configurado: npmRegistryServer: "https://nexus.example.com/repository/yarn-all"

    Para obter mais informações, confira npmRegistryServer na documentação do npm.

Observações

As dependências originadas diretamente de um repositório do GitHub dão ao Dependabot acesso ao repositório por meio da interface do usuário do GitHub. Para obter informações sobre como permitir que o Dependabot acesse dependências privadas do GitHub, confira Permitindo que o Dependabot acesse dependências privadas.

Para dependências de escopo definido (@my-org/my-dep), o Dependabot requer que o registro privado seja configurado .yarnrc file do projeto. Para definir registros privados para escopos individuais, use @myscope:registry" "https://private_registry_url".

Configurar hosts de registro privados

Artifactory

Para obter informações sobre a configuração do Artifactory, consulte Configurando o Artifactory na documentação do JFrog Artifactory.

Repositórios remotos

Os repositórios remotos servem como um cache para artefatos de compilação e dependências. Em vez de ter que entrar em contato com um repositório de dependência global, sua ferramenta de build pode usar o cache do artifactory, o que acelerará os tempos de build. Para obter mais informações, consulte Repositórios remotos na documentação do JFrog Artifactory.

Caso use a configuração replace-base, você deverá também configurar um repositório remoto para o Artifactory se desejar que o Dependabot acesse outro registro quando a dependência não for encontrada no registro privado.

Registro virtual

É possível usar um registro virtual para agrupar todas as dependências privadas e públicas em um único domínio. Para obter mais informações, confira Registro npm na documentação do JFrog Artifactory.

Limitações e soluções alternativas

A configuração target branch não funciona com o Dependabot security updates no Artifactory. Caso receba um erro de autenticação 401, deverá remover a propriedade target-branch do arquivo dependabot.yml. Para obter mais informações, consulte ARTIFACTORY: Por que as atualizações de segurança do GitHub Dependabot estão gerando falha com o erro de autenticação 401 quando ele inicia uma conexão com o registro privado npm do Artifactory para atualizações de segurança na documentação do JFrog Artifactory.

Azure Artifacts

Para obter informações sobre o Azure Artifacts e orientações sobre como configurar o Dependabot para trabalhar com Azure Artifacts, consulte Azure DevOps na documentação o Azure Artifacts e Usar o Dependabot no GitHub com o Azure Artifacts, respectivamente.

Exemplo de registro do Azure Artifacts:

YAML
registries:
  nuget-azure-devops:
    type: nuget-feed
    url: https://pkgs.dev.azure.com/my_org/_packaging/public/nuget/v3/index.json
    token: ${{secrets.AZURE_DEVOPS_TOKEN}}

A senha dos Azure Artifacts deve ser um token não codificado e deve incluir um : após o token. Além disso, ela não pode ser codificada em base64.

Para verificar se o registro particular foi acessado com êxito, observe os logs do Dependabot.

Cloudsmith

Para obter informações sobre o Cloudsmith e instruções sobre como configurar o Dependabot para trabalhar com o Cloudsmith, consulte Introdução ao Cloudsmith e Integrar o GitHub Dependabot ao Cloudsmith na documentação do Cloudsmith.

Registro do GitHub Packages

Para saber mais sobre os registros do GitHub Packages, confira Trabalhar com um registro do GitHub Packages. Nesse artigo, você pode acessar páginas que descrevem como configurar os registros a seguir.

  • Bundler (rubygems)
  • Docker (contêineres)
  • GitHub Actions
  • Gradle
  • Maven
  • Npm
  • NuGet
  • Yarn
YAML
registries:
  github:
    type: npm-registry
    url: https://npm.pkg.github.com
    token: ${{ secrets.<token> }}

Observações

Não há registro de contêiner Python.

Em registros privados com escopo definido para uma organização específica, o Dependabot espera que a URL inclua o nome da organização no arquivo.dependabot.yml.

Nexus

Para obter informações sobre a configuração do Nexus, consulte Gerenciador de repositório 3 na documentação do Sonatype.

Observações

Com o Nexus Repository Pro, é possível habilitar tokens de usuário. Para obter mais informações, confira Tokens de usuário na documentação do Sonatype

Exemplo de registro do Nexus:

YAML
registries:
  npm-nexus:
    type: npm-registry
    url: https://registry.example.com/repository/npm-internal/
    token: ${{secrets.NEXUS_NPM_TOKEN}}

Se estiver executando o Nexus atrás de um proxy reverso, precisará garantir que o servidor esteja acessível usando um token de autenticação por meio do uso do curl -v -H 'Authorization: Bearer <token>' 'https://<nexus-repo-url>/repository/<repo-name>/@<scope>%2<package>'. Para obter mais informações, consulte Executando atrás de um proxy reverso na documentação do Sonatype.

Se você estiver restringindo quais IPs podem alcançar seu host Nexus, será necessário adicionar os IPs do Dependabot à lista de permissões.

Os registros podem ser enviados por proxy para um registro público caso uma dependência não esteja disponível no registro privado. No entanto, talvez você queira que o Dependabot acesse apenas o registro privado e não acesse o registro público. Para obter mais informações, confira Guia de Início Rápido: Como usar um proxy Maven e NPM na documentação do Sonatype e Removendo o acesso do Dependabot a registros públicos.

ProGet

Para obter informações sobre o ProGet e instruções sobre como configurar o Dependabot para trabalhar com feeds no ProGet, consulte a documentação do ProGet.

Exemplo de configuração do registro ProGet para um feed NuGet:

YAML
registries:
  proget-nuget-feed:
    type: nuget-feed
    url: https://proget.corp.local/nuget/MyNuGetFeed/v3/index.json
    token: ${{secrets.PROGET_APK_KEY}}

Exemplo de configuração do registro ProGet para Bundler (rubygems):

YAML
registries:
  proget-gems-feed:
    type: rubygems-server
    url: https://proget.corp.local/rubygems/MyRubygemsFeed
    token: ${{secrets.PROGET_APK_KEY}}

Exemplo de configuração do registro ProGet para Python (PyPI):

YAML
registries:
  proget-python-feed:
    type: python-index
    url: https://proget.corp.local/pypi/MyPythonFeed
    token: ${{secrets.PROGET_APK_KEY}}

Observações

O token deve ser uma chave de API com acesso para visualizar pacotes. Para obter mais informações, consulte Acesso à API e chaves de API na documentação do ProGet.

Para verificar se o registro particular foi acessado com êxito, observe os logs do Dependabot.