关于如何配置 Dependabot 专用注册表
本文包含的建议可帮助用户配置 Dependabot 以访问专用注册表,以及:
- 每个包管理器的
dependabot.yml
配置文件的详细片段。 - 重要限制或注意事项。
- 解释如何测试配置是否正常工作的步骤。
- 任何适当的额外配置选项(例如 npm 有一个需要进行设置的配置文件)。
- 关于配置注册表主机的建议。
可找到有关设置以下包管理器的详细指南:
还可找到有关设置以下注册表主机的建议:
配置包管理器
Bundler
受 Artifactory、Artifacts、Cloudsmith、GitHub Packages 注册表、Nexus 和 ProGet 支持。
可以使用用户名和密码或令牌进行身份验证。 有关详细信息,请参阅“dependabot.yml 文件的配置选项”中的 rubygems-server
。
使用用户名和密码的 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
文件中定义专用注册表。 若要为个别范围定义专用注册表,请使用 @myscope:registry=https://private_registry_url
。
应使用 https
协议配置注册表。
NuGet
受 Artifactory、Artifacts、Cloudsmith、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、Cloudsmith、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。
-
在
dependabot.yml
文件中定义专用注册表配置。 -
然后可以执行以下操作之一:
- 通过将注册表添加到项目根目录中具有注册表键的
.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。
-
在
dependabot.yml
文件中定义专用注册表配置。 -
然后可以执行以下操作之一:
- 通过将注册表添加到项目根目录中具有
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 日志来检查是否成功访问专用注册表。
Cloudsmith
有关 Cloudsmith 的信息以及如何配置 Dependabot 以与 Cloudsmith 配合使用的说明,请参阅 Cloudsmith 文档中的 Cloudsmith 入门和将 GitHub Dependabot 与 Cloudsmith 集成。
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 日志来检查是否成功访问专用注册表。