针对 Dependabot 的专用注册表配置指南

关于如何配置 Dependabot 专用注册表

本文包含的建议可帮助用户配置 Dependabot 以访问专用注册表，以及：

• 每个包管理器的 dependabot.yml 配置文件的详细片段。
• 重要限制或注意事项。
• 解释如何测试配置是否正常工作的步骤。
• 任何适当的额外配置选项（例如 npm 有一个需要进行设置的配置文件）。
• 关于配置注册表主机的建议。

可找到有关设置以下包管理器的详细指南：

• Bundler
• Docker
• Gradle
• Maven
• npm
• Nuget
• Python
• Yarn

还可找到有关设置以下注册表主机的建议：

• Artifactory
• Azure Artifacts
• GitHub Packages 注册表
• Nexus
• ProGet

配置包管理器

Bundler

受 Artifactory、Artifacts、GitHub Packages 注册表、Nexus 和 ProGet 支持。

可以使用用户名和密码或令牌进行身份验证。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 ruby-gems。

使用用户名和密码的 dependabot.yml 文件片段。

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

下面的 dependabot.yml 文件片段使用令牌。 对于使用 GitHub Packages 注册表 (xyz.pkg.github.com) 的此类注册表，令牌实际上是 GitHub personal access token (PAT)。

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

说明

直接从 GitHub 存储库获取的依赖项通过 GitHub UI 授予 Dependabot 访问存储库的权限。 有关允许 Dependabot 访问专用 GitHub 依赖项的信息，请参阅“允许 Dependabot 访问专用依赖项”。

Docker

Docker 支持对注册表使用用户名和密码。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 docker-registry。

使用用户名和密码的 dependabot.yml 文件片段。

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

docker-registry 还可用于通过静态 AWS 凭据从专用 Amazon ECR 中拉取。

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}}

说明

Dependabot 可与实现开放容器计划 (OCI) 分发规范的任何容器注册表配合使用。 有关详细信息，请参阅 https://github.com/opencontainers/distribution-spec/blob/main/spec.md。

Dependabot 支持通过中央令牌服务或 HTTP 基本身份验证对专用注册表进行身份验证。有关详细信息，请参阅 Docker 文档中的令牌身份验证规范和维基百科上的基本访问身份验证。

限制和解决方法

• 容器文件、Helm 文件或 yaml 文件中可能无法始终检测到映像名称。
• Docker 文件只能接收对第一个 FROM 指令的版本更新。
• Docker 文件不会接收使用 ARG 指令指定的映像更新。 COPY 指令有一种可用的解决方法。 有关更多信息，请参阅 dependabot/dependabot-core 仓库中的“Dependabot 忽略 COPY Dockerfile 语句中的映像引用”。
• Dependabot 不支持多阶段 Docker 生成。 有关更多信息，请参阅 dependabot/dependabot-core 仓库中的“支持 Docker 多阶段生成”。

Gradle

Dependabot 不运行 Gradle，但支持对特定 Gradle 文件的更新。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的“Gradle”。

Gradle 支持 maven-repository 注册表类型。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 maven-repository。

maven-repository 类型支持用户名和密码。 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

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"

说明

可能无法看到依赖项关系图中表示的所有依赖项，尤其是在某些依赖项是生成时依赖项时。 可以使用 依赖项提交 API 通知 GitHub 关于其他依赖项的信息，并接收其安全更新。 有关详细信息，请参阅“使用依赖项提交 API”。

Maven

Maven 支持用户名和密码身份验证。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 maven-repository。

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

如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。

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"

说明

可能无法看到依赖项关系图中表示的所有依赖项，尤其是在某些依赖项是生成时依赖项时。 可以使用 依赖项提交 API 通知 GitHub 关于其他依赖项的信息，并接收其安全更新。 有关详细信息，请参阅“使用依赖项提交 API”。

npm

可以使用 npm-registry 类型定义 dependabot.yml 文件中的配置，或者将 Dependabot 配置为通过指定的基 URL 发送所有注册表请求。

在配置文件中使用 npm-registry 类型

使用 npm-registry 类型在 dependabot.yml 文件中定义专用注册表配置。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”。

dependabot.yml 文件片段使用令牌。 对于使用 GitHub Packages 注册表 (xyz.pkg.github.com) 的此类注册表，令牌实际上是 GitHub personal access token (PAT)。

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

npm 生态系统要求将具有专用注册表 URL 的 .npmrc 文件签入存储库。

.npmrc 文件的内容示例：

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

还可以使用以下命令，将专用注册表 URL 添加到现有 .npmrc 文件。

npm config set registry <url>

有关详细信息，请参阅 npm 文档中的注册表。

还可以将配置范围限定为单个依赖项或组织，在这种情况下，令牌将仅对组织有效，并且不同令牌可用于同一存储库的不同组织。

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

这将导致注册表包含“.npmrc”：

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

可使用 replace-registry-host 将 npm 配置为使用锁定文件中的专用注册表 URL。 有关详细信息，请参阅 npm 文档中的 replace-registry-host 文档。

npm config set replace-registry-host "never"

如果使用 replace-registry-host，则必须在本地运行 npm install，以重新生成锁定文件以使用专用注册表 URL。 在提供更新时，Dependabot 会使用相同的 URL。

配置注册表后，还可以运行 npm login 以验证配置是否正确和有效。 还可以重新生成锁定文件，以便通过再次运行 npm install 使用新的专用注册表。

需要确保 .npmrc 文件签入到项目的 package.json 所在的同一目录中，并且该文件不包含任何环境变量或机密。 如果使用 monorepo，则 .npmrc 文件应位于项目的根目录中。

配置 Dependabot，以通过指定的基 URL 发送注册表请求

可配置 Dependabot，以通过指定的基 URL 发送所有注册表请求。 为了使 Dependabot 访问公共依赖项，注册表必须要么具有所请求版本的依赖项的克隆副本，要么允许流量在依赖项不可用时从公共注册表提取。

如果 .npmrc 文件中未定义全局注册表，可以在 dependabot.yml 文件中将 replaces-base 设置为 true。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 replaces-base。

说明

直接从 GitHub 存储库获取的依赖项通过 GitHub UI 授予 Dependabot 访问存储库的权限。 有关允许 Dependabot 访问专用 GitHub 依赖项的信息，请参阅“允许 Dependabot 访问专用依赖项”。

对于已限定范围的依赖项 (@my-org/my-dep)，Dependabot 要求在项目的 .npmrc file 文件中定义专用注册表。 若要为个别范围定义专用注册表，请使用 @myscope:registry=https://private_registry_url。

应使用 https 协议配置注册表。

Nuget

受 Artifactory、Artifacts、GitHub Packages 注册表、Nexus 和 ProGet 支持。

nuget-feed 类型支持用户名和密码或者令牌。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 nuget-feed。

registries:
  nuget-example:
    type: nuget-feed
    url: https://nuget.example.com/v3/index.json
    username: octocat@example.com
    password: ${{secrets.MY_NUGET_PASSWORD}}

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}}

说明

还可以在 dependabot.yml 文件中使用令牌。 对于使用 GitHub Packages 注册表 (xyz.pkg.github.com) 的此类注册表，令牌实际上是 GitHub personal access token (PAT)。

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

受 Artifactory、Azure Artifacts、Nexus 和 ProGet 支持。 不支持 GitHub Packages 注册表。

python-index 类型支持用户名和密码或者令牌。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 python-index。

registries:
  python-example:
    type: python-index
    url: https://example.com/_packaging/my-feed/pypi/example
    username: octocat
    password: ${{secrets.MY_BASIC_AUTH_PASSWORD}}

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}}

registries:
  python-gemfury:
    type: python-index
    url: https://pypi.fury.io/my_org
    token: ${{secrets.MY_GEMFURY_TOKEN}}

说明

直接从 GitHub 存储库获取的依赖项通过 GitHub UI 授予 Dependabot 访问存储库的权限。 有关允许 Dependabot 访问专用 GitHub 依赖项的信息，请参阅“允许 Dependabot 访问专用依赖项”。

url 应包含 URL、组织，以及“源”或存储库。

Yarn

Yarn 注册表使用类似于 npm 注册表的配置。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的 npm-registry。

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

• 对于专用注册表，必须签入 .yarnrc.yml 文件（针对 Yarn 3）或 .yarnrc 文件（针对 Yarn Classic）。
• Yarn 配置文件不应包含环境变量。
• 应使用 https 配置 dependabot.yml 文件中列出的专用注册表。

Yarn Classic

可以在 dependabot.yml 文件中指定专用注册表配置，也可以根据标准包管理器说明设置 Yarn Classic。

在 dependabot.yml 文件中定义专用注册表配置

可在 dependabot.yml 文件中定义专用注册表配置。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的“专用注册表配置选项”。

若要确保专用注册表作为项目的 yarn.lock 文件中的依赖项源列出，需要在具有专用注册表访问权限的计算机上运行 yarn install。 Yarn 应更新已解决字段以包含专用注册表 URL。

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"

按照包管理器中的标准说明进行操作

如果 yarn.lock 文件没有将专用注册表列为依赖项源，则可以根据标准包管理器的说明来设置 Yarn Classic。

1. 在 dependabot.yml 文件中定义专用注册表配置。

2. 然后可以执行以下操作之一：

   • 通过将注册表添加到项目根目录中具有注册表键的 .yarnrc.yml 文件，将专用注册表手动设置到 .yarnrc 文件，或
   • 通过在终端中运行 yarn config set registry <private registry URL> 来执行相同的操作。

   定义了专用注册表的 .yarnrc 示例：registry https://nexus.example.com/repository/yarn-all

Yarn Berry (v3)

有关配置的信息，请参阅 Yarn 文档中的设置 (.yarnrc.yml)。

与 Yarn Classic 一样，可以在 dependabot.yml 文件中指定专用注册表配置，也可以根据包管理器说明设置 Yarn Berry。

在 dependabot.yml 文件中定义专用注册表配置

可在 dependabot.yml 文件中定义专用注册表配置。 有关详细信息，请参阅“dependabot.yml 文件的配置选项”中的“专用注册表配置选项”。

若要确保专用注册表作为项目的 yarn.lock 文件中的依赖项源列出，请在具有专用注册表访问权限的计算机上运行 yarn install。 Yarn 应更新已解决字段以包含专用注册表 URL。

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"

还可以使用 npmAuthIdent 或 npmAuthToken 配置专用注册表。 有关详细信息，请参阅 Yarn 文档中的“npmAuthIdent”和“npmAuthToken”。

yarn config set registry <url>

可以将配置范围限定为仅涵盖单一依赖项或组织。

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

最后，建议运行 yarn login 以验证配置是否正确并有效。 还可以重新生成锁定文件，以便通过再次运行 yarn install 使用新的专用注册表。

按照包管理器中的标准说明进行操作

如果 yarn.lock 文件没有将专用注册表列为依赖项源，则可以根据标准包管理器的说明来设置 Yarn Berry。

1. 在 dependabot.yml 文件中定义专用注册表配置。

2. 然后可以执行以下操作之一：

   • 通过将注册表添加到项目根目录中具有 npmRegistryServer 键的 .yarnrc.yml 文件，将专用注册表手动设置到 .yarnrc 文件，或
   • 通过在终端中运行 yarn config set npmRegistryServer <private registry URL> 来执行相同的操作。

   配置了专用注册表的 .yarnrc.yml 文件示例：npmRegistryServer: "https://nexus.example.com/repository/yarn-all"

   有关详细信息，请参阅 Yarn 文档中的 npmRegistryServer。

说明

直接从 GitHub 存储库获取的依赖项通过 GitHub UI 授予 Dependabot 访问存储库的权限。 有关允许 Dependabot 访问专用 GitHub 依赖项的信息，请参阅“允许 Dependabot 访问专用依赖项”。

对于已限定范围的依赖项 (@my-org/my-dep)，Dependabot 要求在项目的 .yarnrc file 文件中定义专用注册表。 若要为个别范围定义专用注册表，请使用 @myscope:registry" "https://private_registry_url"。

配置专用注册表主机

Artifactory

有关 Artifactory 配置的信息，请参阅 JFrog Artifactory 文档中的配置 Artifactory。

远程存储库

远程存储库充当生成工件和依赖项的缓存。 生成工具可以使用 artifactory 缓存来加快生成时间，而无需联系全局依赖项存储库。 有关详细信息，请参阅 JFrog Artifactory 文档中的远程存储库。

如果使用 replace-base 设置，在专用注册表中未找到依赖项的情况下，如果希望 Dependabot 访问另一个注册表，则还应为 Artifactory 配置远程存储库。

虚拟注册表

可以使用虚拟注册表将单一域下的所有专用和公共依赖项组合在一起。 有关详细信息，请参阅 JFrog Artifactory 文档中的 npm 注册表。

限制和解决方法

target branch 设置不适用于 Artifactory 上的 Dependabot security updates 。 如果收到 401 身份验证错误提示，则需要从 dependabot.yml 文件中删除 target-branch 属性。 有关详细信息，请参阅 JFrog Artifactory 文档中的 ARTIFACTORY：为何在启动与 Artifactory npm 专用注册表的连接以获取安全更新时 GitHub Dependabot 安全更新失败并出现 401 身份验证错误。

Azure Artifacts

有关 Azure Artifacts 的信息，以及如何将 Dependabot 配置为与 Azure Artifacts 配合使用的说明，请分别参阅 Azure Artifacts 文档中的 Azure DevOps，以及将 GitHub 中的 Dependabot 与 Azure Artifacts 配合使用。

Azure Artifacts 注册表示例：

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}}

Azure Artifacts 密码必须是未编码的令牌，并且在令牌后应包含 :。 此外，密码不能为 base64 编码。

可以通过查看 Dependabot 日志来检查是否成功访问专用注册表。

GitHub Packages 注册表

有关 Container registry 注册表的信息，请参阅“使用 GitHub Packages 注册表”。 从该文章中，可以访问描述如何配置以下注册表的页面。

• Bundler (rubygems)
• Docker（容器）
• GitHub Actions
• Gradle
• Maven
• npm
• NuGet
• Yarn

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

说明

没有 Python 容器注册表。

对于范围限定为特定组织的专用注册表，Dependabot 需要 URL 将组织名称包含在 dependabot.yml 文件中。

Nexus

有关 Nexus 配置的信息，请参阅 Sonatype 文档中的 Repository Manager 3。

说明

使用 Nexus Repository Pro，可以启用用户令牌。 有关详细信息，请参阅 Sonatype 文档中的用户令牌。

Nexus 注册表示例：

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

如果在反向代理背后运行 Nexus，则需要确保可通过 curl -v -H 'Authorization: Bearer <token>' 'https://<nexus-repo-url>/repository/<repo-name>/@<scope>%2<package>'，使用身份验证令牌访问服务器。 有关详细信息，请参阅 Sonatype 文档中的在反向代理背后运行。

如果要限制哪些 IP 可以访问 Nexus 主机，需要将 Dependabot IP 加入允许列表。

• 可在 dependabot 键下找到用于访问 Meta API 端点中的注册表的 IP 地址 Dependabot。 有关详细信息，请参阅“元数据的 REST API 终结点”。
• 以下是当前 IP：
  • “18.213.123.130/32”
  • “3.217.79.163/32”
  • “3.217.93.44/32”有关详细信息，请参阅 Sonatype 文档中的保护 Nexus Repository Manager 的安全。

如果专用注册表中有依赖项不可用，则可以代理注册表以联系公共注册表。但是，可能需要 Dependabot 仅访问专用注册表，并且完全不访问公共注册表。 有关详细信息，请参阅 Sonatype 文档中的快速入门指南 - 代理 Maven 和 NPM，以及“删除对公共注册表的 Dependabot 访问权限”。

ProGet

有关 ProGet 的信息以及如何将 Dependabot 配置为在 ProGet 中使用源的说明，请参阅 ProGet 文档。

NuGet 源的 ProGet 注册表配置示例：

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

Bundler 的 ProGet 注册表配置示例（rubygems）：

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

Python 的 ProGet 注册表配置示例（PyPI）：

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

说明

token 应为有权查看包的 API 密钥。 有关详细信息，请参阅 ProGet 文档中的 API 访问权限和 API 密钥。

可以通过查看 Dependabot 日志来检查是否成功访问专用注册表。