关于 dependabot.yml
文件
Dependabot 配置文件 dependabot.yml
使用 YAML 语法。 如果你不熟悉 YAML 并且想要了解详细信息,请参阅“在五分钟内了解 YAML”。
必须将此文件存储在存储库的默认分支的 .github
目录中。 在添加或更新 dependabot.yml
文件时,会立即触发版本更新检查。 有关详细信息和示例,请参阅“配置 Dependabot 版本更新”。
下次安全警报触发安全更新的拉取请求时将使用所有同时影响安全更新的选项。 有关详细信息,请参阅“配置 Dependabot 安全更新”。
注意****:不能使用 dependabot.yml
文件配置 Dependabot alerts。
dependabot.yml
文件有两个必需的顶层键:version
和 updates
。 可以选择包括顶层 registries
键。 该文件必须以 version: 2
开头。
有关 dependabot.yml
文件的实际示例,请参阅 Dependabot 自身的配置文件。
dependabot.yml
文件的配置选项
顶级 updates
项是必需的。 您使用它来配置 Dependabot 如何更新版本或项目的依赖项。 每个条目都为特定的包管理器配置更新设置。 您可以使用以下选项。
选项 | 必需 | 安全更新 | 版本更新 | 说明 |
---|---|---|---|---|
package-ecosystem | 要使用的包管理器 | |||
directory | 包清单位置 | |||
directories | 包清单的位置(多个目录) | |||
schedule.interval | 检查更新的频率 | |||
allow | 自定义允许的更新 | |||
assignees | 要在拉取请求上设置的受让人 | |||
commit-message | 提交消息首选项 | |||
enable-beta-ecosystems | 启用具有 beta 级支持的生态系统 | |||
groups | 对某些依赖项的更新分组 | |||
ignore | 请参阅 ignore | 请参阅 ignore | 忽略某些依赖项或版本 | |
insecure-external-code-execution | 允许或拒绝清单文件中的代码执行 | |||
labels | 要在拉取请求上设置的标签 | |||
milestone | 要在拉取请求上设置的里程碑 | |||
open-pull-requests-limit | 限制对版本更新打开的拉取请求数 | |||
pull-request-branch-name.separator | 更改拉取请求分支名称的分隔符 | |||
rebase-strategy | 禁用自动变基 | |||
registries | Dependabot 可以访问的私有注册表 | |||
reviewers | 要在拉取请求上设置的审查者 | |||
schedule.day | 检查更新的周日期 | |||
schedule.time | 每天检查更新的时间 (hh:mm) | |||
schedule.timezone | 一天中时间的时区(区域标识符) | |||
target-branch | 对其创建拉取请求的分支 | |||
vendor | 更新供应或缓存的依赖项 | |||
versioning-strategy | 如何更新清单版本要求 |
注意: 不能在同一配置块中同时使用 directory
和 directories
。 只需要一个选项,而不是两个选项都需要。
这些选项大致分为以下类别。
- 必须在所有配置中包括的基本设置选项:
package-ecosystem
、directory
或directories
、schedule.interval
。 - 用于自定义更新计划的选项:
schedule.time
、schedule.timezone
、schedule.day
。 - 用于控制依赖项更新的选项:
allow
、groups
、ignore
、vendor
。 - 用于向拉取请求添加元数据的选项:
reviewers
、assignees
、labels
、milestone
。 - 用于更改拉取请求的行为的选项:
target-branch
、versioning-strategy
、commit-message
、rebase-strategy
、pull-request-branch-name.separator
。
此外,open-pull-requests-limit
选项会更改 Dependabot 可以打开的版本更新的最大拉取请求数。
注意:其中一些配置选项还可能会影响针对易受攻击的程序包清单安全更新提出的拉取请求。
仅对默认分支上有漏洞的包清单提出安全更新。 如果为同一分支设置了配置选项(除非使用 target-branch
,否则为 true),并为易受攻击的清单指定了 package-ecosystem
和 directory
,则安全更新的拉取请求将使用相关选项。
一般而言,安全更新会使用影响拉取请求的任何配置选项,例如添加元数据或改变其行为。 有关安全更新的详细信息,请参阅“配置 Dependabot 安全更新”。
package-ecosystem
“必需”。 你为希望 Dependabot 监视新版本的每个包管理器添加一个 package-ecosystem
元素。 仓库还必须包含其中每个包管理器的依赖项清单或锁定文件。
如果您想要为支持它的软件包管理器启用供应,则必须在所需的目录中找到供应的依赖项。 有关详细信息,请参阅下面的 vendor
。
要在执行版本更新时允许 Dependabot 访问私有包注册表,可在配置文件中包含 registries
设置。 有关详细信息,请参阅下面的 registries
。
程序包管理器 | YAML 值 | 支持的版本 | 版本更新 | 安全更新 | 私有仓库 | 专用注册表 | 供应 |
---|---|---|---|---|---|---|---|
Bundler | bundler | v2 | |||||
Cargo | cargo | v1 | |||||
编辑器 | composer | v1, v2 | |||||
开发容器 | devcontainers | 不适用 | |||||
Docker | docker | v1 | 不适用 | ||||
Hex | mix | v1 | |||||
elm-package | elm | v0.19 | |||||
git submodule | gitsubmodule | 不适用 | 不适用 | ||||
GitHub Actions | github-actions | 不适用 | 不适用 | ||||
Go 模块 | gomod | v1 | |||||
Gradle | gradle | 不适用 | |||||
Maven | maven | 不适用 | |||||
npm | npm | v6、v7、v8、v9 | |||||
NuGet | nuget | <=6.8.0 | |||||
pip | pip | v21.1.2 | |||||
pipenv | pip | <= 2021-05-29 | |||||
pip-compile | pip | 6.1.0 | |||||
pnpm | npm | v7、v8、v9 | |||||
poetry | pip | v1 | |||||
酒馆 | pub | v2 | |||||
Swift | swift | v5 | (仅适用于 git) | ||||
Terraform | terraform | >= 0.13、<= 1.8.x | 不适用 | ||||
yarn | npm | V1、V2、V3 |
提示:对于包管理器(如 pipenv
和 poetry
),需要使用 pip
YAML 值。 例如,如果使用 poetry
来管理 Python 依赖项,并且希望让 Dependabot 监视新版本的依赖项清单文件,请在 dependabot.yml
文件中使用 package-ecosystem: "pip"
。
有关 Dependabot security updates 生态系统支持的详细信息,请参阅“依赖项关系图支持的包生态系统”。
Cargo
专用注册表支持包括 Cargo 注册表,因此可以使用 Dependabot 保持 Rust 依赖项更新。 有关详细信息,请参阅 "针对 Dependabot 的专用注册表配置指南"。
开发容器
可以在 dependabot.yml
文件中将 devcontainers
用作 package-ecosystem
,以更新 devcontainer.json
配置文件中的功能。 有关此支持的详细信息以及配置文件示例,请参阅开发容器文档中的 Dependabot 集成正式发布。
开发容器用于包括 Codespaces 在内的多个工具和服务。 有关功能和支持的服务的详细信息,请分别参阅开发容器文档中的功能和支持工具和服务。
此更新程序可确保功能固定到关联 devcontainer.json
文件中的最新 major
版本。 如果开发容器具有锁定文件,则该文件也会被更新。 有关锁定文件规范的详细信息,请参阅 devcontainers/spec
存储库中的锁定文件。
任何有效开发容器位置中的功能都将在单个拉取请求中更新。 有关开发容器规范的详细信息,请参阅开发容器文档中的规范。
Docker
Dependabot 可以从 Docker 映像添加元数据,以拉取版本更新请求。 元数据包括发行说明、更改日志和提交历史记录。 存储库管理员可以使用元数据快速评估依赖项更新的稳定性风险。
为了使 Dependabot 提取 Docker 元数据,Docker 映像的维护员必须将 org.opencontainers.image.source
标签添加到其 Dockerfile,并包含源存储库的 URL。 此外,维护员必须使用与已发布的 Docker 映像相同的标记来标记存储库。 有关示例,请参阅 dependabot-fixtures/docker-with-source
存储库。 有关 Docker 标签的详细信息,请参阅 Docker 文档中的扩展映像标签和 BUILDX_GIT_LABELS。
Dependabot 可更新 Kubernetes 清单中的 Docker 映像标记。 对于包含引用 Docker 映像标记的 Kubernetes 清单的每个目录,请向 dependabot.yml
文件的 Docker package-ecosystem
元素添加一个条目。 Kubernetes 清单可以是 Kubernetes 部署 YAML 文件或 Helm 图表。 有关为 docker
配置 dependabot.yml
文件的信息,请参阅“dependabot.yml 文件的配置选项”中的“package-ecosystem
”。
Dependabot 支持公共和专用 Docker 注册表。 有关支持的注册表的列表,请参阅“dependabot.yml 文件的配置选项”中的“docker-registry
”。
Dependabot 解析 Docker 映像标签以进行语义化版本控制 (SemVer)。 如果 Dependabot 检测到带有预发布标签的标签,那么它只会建议更新到具有匹配预发布标签的最新版本,而不会建议使用不同预发布标签的较新版本。 有关详细信息,请参阅 dependabot/dependabot-core
存储库中的dependabot-docker
README.md 文件。
GitHub Actions
Dependabot 支持对 GitHub Actions 的版本更新,但有以下注意事项。
- Dependabot 仅支持使用 GitHub 存储库语法(例如
actions/checkout@v4
)更新 GitHub Actions。 Dependabot 将忽略本地引用的操作或可重用工作流(例如,./.github/actions/foo.yml
)。 - 目前不支持 Docker Hub 和 GitHub Packages Container registry URL。 例如,不支持使用
docker://
语法引用 Docker 容器操作。 - Dependabot 支持 GitHub Actions 的公共存储库和专用存储库。 有关专用注册表配置选项,请参阅“dependabot.yml 文件的配置选项”中的“
git
”。
有关通过 GitHub Actions 使用 Dependabot version updates 的详细信息,请参阅“使用 GitHub 的安全功能来保护 GitHub Actions 的使用”。
Gradle
Dependabot 不运行 Gradle,但支持对以下文件的更新:
build.gradle
、build.gradle.kts
(适用于 Kotlin 项目)gradle/libs.versions.toml
(适用于使用标准 Gradle 版本目录的项目)- 通过
apply
声明包含的文件,文件名中包含dependencies
。 请注意,apply
不支持apply to
、递归或高级语法(例如,Kotlin 的apply
和mapOf
,由属性定义的文件名)。
对于 Dependabot security updates,Gradle 的支持仅限于使用 依赖项提交 API 手动上传依赖项关系图数据。 有关 依赖项提交 API 的详细信息,请参阅“使用依赖项提交 API”。
注意:
- 使用 依赖项提交 API 将 Gradle 依赖项上传到依赖项关系图时,将上传所有的项目依赖项,甚至是任何依赖项文件中未显式提及的可转移依赖项。 在可转移依赖项中检测到警报时,Dependabot 无法在存储库中找到易受攻击的依赖项,因此不会为该警报创建安全更新程序。
- 但是,当父依赖项在项目清单文件中显式声明为直接依赖项时,Dependabot version updates 将创建拉取请求。
Maven
Dependabot 不运行 Maven,但支持对 pom.xml
文件的更新。
NuGet CLI
Dependabot 不运行 NuGet CLI,但支持版本 6.8.0 以前的大多数功能。
pip 和 pip-compile
除支持更新 requirements.txt
文件外,Dependabot 还支持更新 pyproject.toml
文件(如果它们遵循 PEP 621 标准)。
酒馆
Dependabot 在尝试更新到的版本被忽略时不会为 pub
执行更新,即使有可用的早期版本也是如此。
如果使用专用托管的 pub 存储库,则可以通过 Dependabot 使 Dart 依赖项保持最新。 有关允许 Dependabot 访问专用 GitHub 依赖项的信息,请参阅“允许 Dependabot 访问专用依赖项”。
Swift
专用注册表支持仅适用于 git 注册表。 不支持 Swift 注册表。 不支持非声明性清单。 有关非声明性清单的详细信息,请参阅 Swift Evolution 文档中的编辑非声明性清单。
Terraform
Terraform 支持包括:
- Terraform 注册表或可公开访问的 Git 存储库上托管的模块。
- Terraform 提供程序。
- 专用 Terraform 注册表。 可以在
dependabot.yml
文件中指定一个 git 注册表,以配置对专用 git 存储库的访问权限。 有关详细信息,请参阅git
。
yarn
Dependabot 支持 v2 及更高版本的 vendored 依赖项。
三个包管理器的基本设置示例
# Basic set up for three package managers
version: 2
updates:
# Maintain dependencies for GitHub Actions
- package-ecosystem: "github-actions"
# Workflow files stored in the default location of `.github/workflows`. (You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.)
directory: "/"
schedule:
interval: "weekly"
# Maintain dependencies for npm
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Maintain dependencies for Composer
- package-ecosystem: "composer"
directory: "/"
schedule:
interval: "weekly"
directory
“必需”。 必须为每个包管理器定义程序包清单的位置(例如 package.json 或 Gemfile) 。 为所有生态系统(GitHub Actions 除外)定义相对于存储库根目录的目录。
可以使用 directories
(而不是 directory
)将相同的配置应用于多个目录的列表。 directory
或 directories
条目必须是唯一的,并且不能与具有相同生态系统和 target-branch
的块中的 directory
或 directories
条目重叠。 可以有一个块指定多个目录,另一个块只指定一个目录,但两个键不能存在于同一个块中。 有关详细信息,请参阅 directories
。
注意: 不能在同一配置块中同时使用 directory
和 directories
。 只需要一个选项,而不是两个选项都需要。
对于 GitHub Actions,无需将目录设置为 /.github/workflows
。 将该键配置为 /
,以自动指示 Dependabot 搜索 /.github/workflows
目录,并从根目录中搜索 action.yml / action.yaml 文件。
# Specify location of manifest files for each package manager
version: 2
updates:
- package-ecosystem: "composer"
# Files stored in repository root
directory: "/"
schedule:
interval: "weekly"
- package-ecosystem: "npm"
# Files stored in `app` directory
directory: "/app"
schedule:
interval: "weekly"
- package-ecosystem: "github-actions"
# Workflow files stored in the default location of `.github/workflows`. (You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.)
directory: "/"
schedule:
interval: "weekly"
directories
**** 必需。 必须为每个包管理器定义程序包清单的位置。 为所有生态系统(GitHub Actions 除外)定义相对于存储库根目录的目录。 directories
选项包含表示目录的字符串列表。
注意: 不能在同一配置块中同时使用 directory
和 directories
。 只需要一个选项,而不是两个选项都需要。
# Specify locations of manifest files for each package manager using `directories`
version: 2
updates:
- package-ecosystem: "bundler"
directories:
- "/frontend"
- "/backend"
- "/admin"
schedule:
interval: "weekly"
可以使用 directories
(而不是 directory
)将相同的配置应用于多个目录的列表。 directory
或 directories
条目必须是唯一的,并且不能与具有相同生态系统和 target-branch
的块中的 directory
或 directories
条目重叠。 可以有一个块指定多个目录,另一个块只指定一个目录,但两个键不能存在于同一个块中。
使用 directory
、directories
或两者混合使用都是有效的方法。 应该根据自己的需求定制配置。 当想要将完全相同的配置应用于多个目录或跨多个目录对依赖项更新进行分组时,建议使用 directories
;当只想将配置应用于一个目录或希望每个目录都有不同的配置时,建议使用 directory
。
# Specify locations of manifest files for each package manager using both `directories` and `directory`
version: 2
updates:
- package-ecosystem: "bundler"
directories:
- "/frontend"
- "/backend"
- "/admin"
schedule:
interval: "weekly"
- package-ecosystem: "bundler"
directory: "/"
schedule:
interval: "daily"
Tip
directories
键支持通配和通配符 *
。 directory
键不支持这些功能。
# Specify the root directory and directories that start with "lib-", using globbing, for locations of manifest files
version: 2
updates:
- package-ecosystem: "composer"
directories:
- "/"
- "/lib-*"
schedule:
interval: "weekly"
# Specify the root directory and directories in the root directory as the location of manifest files using the wildcard character
version: 2
updates:
- package-ecosystem: "composer"
directories:
- "*"
schedule:
interval: "weekly"
# Specify all directories from the current layer and below recursively, using globstar, for locations of manifest files
version: 2
updates:
- package-ecosystem: "composer"
directories:
- "**/*"
schedule:
interval: "weekly"
多目录支持不同于拉取请求中的更新组。
dependabot.yml
文件中的directories
选项允许同时将 Dependabot updates 应用到多个目录。dependabot.yml
文件中的groups
选项会为 Dependabot 创建依赖项集(每个包管理器),并将其放入同一个拉取请求。
如果要在存储库上使用这两项功能,则需要使用上述两个密钥,独立地显式启用这些功能。 有关分组的详细信息,请参阅“groups
”。
schedule.interval
**** 必需。 必须为每个包管理器定义检查新版本的频率。 默认情况下, Dependabot 随机分配一个时间来应用配置文件中的所有更新。 若要设置特定时间,可以使用 schedule.time
和 schedule.timezone
。
注意:选项 schedule.time
是相对较好的选择,Dependabot 可能需要一些时间来开立拉取请求并更新到较新的依赖项版本。
时间间隔类型 | 频率 |
---|---|
daily | 在每个工作日(周一至周五)运行。 |
weekly | 每周运行一次。 默认情况下为星期一。 若要对此进行修改,请使用 schedule.day 。 |
monthly | 每月运行一次。 在每月的第一天运行。 |
# Set update schedule for each package manager
version: 2
updates:
- package-ecosystem: "github-actions"
# Workflow files stored in the default location of `.github/workflows`. (You don't need to specify `/.github/workflows` for `directory`. You can use `directory: "/"`.)
directory: "/"
schedule:
# Check for updates to GitHub Actions every weekday
interval: "daily"
- package-ecosystem: "composer"
directory: "/"
schedule:
# Check for updates managed by Composer once a week
interval: "weekly"
注意:schedule
定义 Dependabot 尝试新更新的时间。 但是,这不是您可收到拉取请求的唯一时间。 对 dependabot.yml
文件所做的更改、或 Dependabot security updates 都可触发更新。 有关详细信息,请参阅“关于 Dependabot 版本更新”和“关于 Dependabot 安全更新”。
有时,由于配置错误或版本不兼容,可能会看到 Dependabot 运行失败。 运行失败 15 次后,15 Dependabot version updates 会跳过后续的计划运行,直到你手动触发检查依赖项关系图的更新。 Dependabot security updates 仍照常运行。
allow
默认情况下,清单中明确定义的所有依赖项都通过 Dependabot 版本更新保持最新。 此外,Dependabot 安全更新还更新了锁定文件中定义的易受攻击的依赖项。 可以使用 allow
和 ignore
自定义要维护的依赖项。 Dependabot 可检查所有被允许的依赖项,然后过滤到任何被忽略的依赖项或版本。 因此,将忽略由 allow
和 ignore
匹配的依赖项。
使用 allow
选项自定义更新的依赖项。 这适用于版本和安全更新。 您可以使用下列选项:
-
dependency-name
- 用于允许具有匹配名称的依赖项的更新,可以选择使用*
匹配零个或多个字符。- 对于 Java 依赖项,
dependency-name
属性的格式为groupId:artifactId
;例如:org.kohsuke:github-api
。 - 对于 Docker 映像标记,格式为存储库的全名;例如,对于
<account ID>.dkr.ecr.us-west-2.amazonaws.com/base/foo/bar/ruby:3.1.0-focal-jemalloc
的映像标记,请使用base/foo/bar/ruby
。
- 对于 Java 依赖项,
-
dependency-type
- 用于允许特定类型的依赖项的更新。依赖项类型 支持的包管理器 允许更新 direct
All 所有明确定义的依赖项。 indirect
bundler
、pip
、composer
、cargo
、gomod
直接依赖关系的依赖项(也称为子依赖项或暂时依赖项)。 all
All 所有明确定义的依赖项。 对于 bundler
、pip
、composer
、cargo
、gomod
,还包括直接依赖项的依赖项。production
bundler
、composer
、mix
、maven
、npm
、pip
(不是所有经理)仅“产品依赖项组”中的依赖项。 development
bundler
、composer
、mix
、maven
、npm
、pip
(不是所有经理)仅“产品依赖项组”中的依赖项。
# Use `allow` to specify which dependencies to maintain
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
allow:
# Allow updates for Lodash
- dependency-name: "lodash"
# Allow updates for React and any packages starting "react"
- dependency-name: "react*"
- package-ecosystem: "composer"
directory: "/"
schedule:
interval: "weekly"
allow:
# Allow both direct and indirect updates for all packages
- dependency-type: "all"
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
allow:
# Allow only direct updates for
# Django and any packages starting "django"
- dependency-name: "django*"
dependency-type: "direct"
# Allow only production updates for Sphinx
- dependency-name: "sphinx"
dependency-type: "production"
assignees
使用 assignees
为针对包管理器提出的所有拉取请求指定单个代理人。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
# Specify assignees for pull requests
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Add assignees
assignees:
- "octocat"
commit-message
默认情况下,Dependabot 会尝试检测您的提交消息首选项并使用类似的模式。 使用 commit-message
选项可显式指定首选项。 该设置还会影响拉取请求的标题。
拉取请求的标题会根据提交消息填充,无论是通过显式设置还是从存储库历史记录中自动检测。
支持的选项
注意****:prefix
和 prefix-development
选项具有 50 个字符的限制。
-
prefix
会指定所有提交消息的前缀,也会被添加到 PR 标题的开头。 指定提交消息的前缀时,GitHub 将自动在定义的前缀和提交消息之间添加冒号,前提是定义的前缀以字母、数字、右括号或右方括号结尾。 这意味着,例如,如果前缀以空格结尾,则前缀和提交消息之间不会添加冒号。 下面的代码片段在同一配置文件中提供了这两种情况的示例。 -
prefix-development
为更新开发依赖项组中的依赖项的所有提交消息指定单独的前缀。 为该选项指定值时,prefix
仅用于更新生产依赖项组中的依赖项。 这由bundler
、composer
、mix
、maven
、npm
和pip
支持。 -
include: "scope"
指定任何前缀都后跟提交中更新的依赖项类型(deps
或deps-dev
)。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
# Customize commit messages
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
commit-message:
# Prefix all commit messages with "npm: "
prefix: "npm"
- package-ecosystem: "docker"
directory: "/"
schedule:
interval: "weekly"
commit-message:
# Prefix all commit messages with "[docker] " (no colon, but a trailing whitespace)
prefix: "[docker] "
- package-ecosystem: "composer"
directory: "/"
schedule:
interval: "weekly"
# Prefix all commit messages with "Composer" plus its scope, that is, a
# list of updated dependencies
commit-message:
prefix: "Composer"
include: "scope"
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# Include a list of updated dependencies
# with a prefix determined by the dependency group
commit-message:
prefix: "pip prod"
prefix-development: "pip dev"
如果使用与上述示例相同的配置,则升级 pip
开发依赖项组中的 requests
库将生成提交消息:
pip dev: bump requests from 1.0.0 to 1.0.1
groups
你可以使用 dependabot.yml
文件 创建单独的规则,以分组 Dependabot version updates 和 Dependabot security updates。
注意: 如果 Dependabot version updates 的分组的拉取请求中包含易受到攻击的包,则 Dependabot security updates 仍将会尝试创建创建_单独的_拉取请求将易受到攻击的包更新到安全版本。 为安全更新创建单独的摘取请求可确保了解包的脆弱性。
默认情况下,Dependabot 为每个需要更新到较新版本的依赖项提出单个拉取请求。 可以使用 groups
创建依赖项集(每个包管理器),以便 Dependabot 打开单个拉取请求以同时更新多个依赖项。
还可以根据更新如何影响特定生态系统来指定分组设置并遵循语义版本控制 (SemVer)。 这意味着你可以将所有修补程序更新组合在一起。 此方法可帮助 Dependabot 创建尽可能少的拉取请求,同时降低意外接受可能导致问题的更改的可能性。 如果包遵循 SemVer,则小补丁和补丁更新向后兼容的几率更高(但不能保证)。
注意: SemVer 是用于定义软件包版本的接受标准,格式为 x.y.z
。 Dependabot 假设此形式的版本始终为 major.minor.patch
。
当第一次配置组时,需要指定一个组名,它将显示在拉取请求标题和分支名称中,以及组规则是应用于版本更新还是安全更新。 然后,就可以定义其他选项,以包括或排除组中的特定依赖关系。 必须使用 patterns
、exclude-patterns
、dependency-type
或 update-types
选项来定义组或其任何组合。
选项 | 说明 |
---|---|
applies-to | 用于指定组中的规则是应用于版本更新还是安全更新。 applies-to 可以是 version-updates 或 security-updates 。 |
dependency-type | 用于指定要在组中包含的依赖关系类型。 dependency-type 可以是 development 或 production 。 |
patterns | 用于定义与依赖关系名称(或多个依赖关系名称)匹配的字符串,以在组中包括这些依赖关系。 |
exclude-patterns | 用于从组中排除某些依赖关系。 如果从某个组排除了某个依赖项,则 Dependabot 将继续引发单个拉取请求,以将该依赖项更新到其最新版本。 |
update-types | 用于指定要在组中包含的语义版本控制级别。 可能的值为 minor 、patch 和 major 。 |
applies-to
键用于指定分组规则集是用于版本更新还是安全更新。 applies-to
键的使用是可选的。 如果分组规则集中没有 applies-to
键,则默认为 version-updates
以确保后向兼容性。 不能将单个分组规则集同时应用于版本更新和安全更新。 相反,如果要使用相同的条件对版本更新和安全更新进行分组,则必须定义两个分别单独命名的分组规则集。 为此,可以复制生态系统和目录的组配置块,并按不同的方式分别命名每个规则集。
Dependabot 按组在 dependabot.yml
文件中出现的顺序创建组。 如果依赖项更新可以属于多个组,则只会将它分配给与之匹配的第一个组。
如果依赖项不属于任何组,Dependabot 会继续引发单个拉取请求,以便正常将依赖项更新为最新版本。 如果组为空,GitHub 会在日志中报告。 有关详细信息,请参阅“Dependabot 无法将一组依赖项分组到单个拉取请求中”。
计划的更新运行时,Dependabot 会使用以下规则刷新分组更新的拉取请求:
- 如果所有相同的依赖项都需要更新到相同的版本,则 Dependabot 将对分支进行变基处理。
- 如果需要更新所有相同的依赖项,但较新版本可用于一个(或多个)依赖项),则 Dependabot 将关闭该拉取请求并创建一个新拉取请求。
- 如果要更新的依赖项已更改(例如,组中的另一个依赖项现在有可用的更新),则 Dependabot 将关闭该拉取请求并创建一个新拉取请求。
还可以使用注释命令管理已分组版本更新和安全更新的拉取请求,这些注释命令是对拉取请求做出的简短注释,用以向 Dependabot 给出指令。 有关详细信息,请参阅“管理依赖项更新的所有拉取请求”。
示例 1
dependabot.yml
文件配置使用 patterns
和 dependency-type
选项来包括组中的特定依赖项,并使用 exclude-patterns
从组中排除一个依赖项(或多个依赖项)。分组规则默认只应用于版本更新,因为没有 applies-to
密钥。
# `dependabot.yml` file using the `dependency-type` option to group updates
# in conjunction with `patterns` and `exclude-patterns`.
# Grouping rules default to applying to version updates only, since
# the `applies-to` key is absent.
groups:
production-dependencies:
dependency-type: "production"
development-dependencies:
dependency-type: "development"
exclude-patterns:
- "rubocop*"
rubocop:
patterns:
- "rubocop*"
示例 2
一个具有自定义捆绑程序配置的 dependabot.yml
文件,已对其进行修改以创建一组依赖项。 配置会指定与一个依赖项(或多个依赖项)的名称匹配的 patterns
(字符串),以便将依赖项包含在组中。分组规则只适用于版本更新,因为使用了 applies-to: version-updates
。
# `dependabot.yml` file with customized Bundler configuration
# In this example, the name of the group is `dev-dependencies`, and
# only the `patterns` and `exclude-patterns` options are used.
# Grouping rules apply to version updates only.
version: 2
updates:
# Keep bundler dependencies up to date
- package-ecosystem: "bundler"
directories:
- "/frontend"
- "/backend"
- "/admin"
schedule:
interval: "weekly"
# Create a group of dependencies to be updated together in one pull request
groups:
# Specify a name for the group, which will be used in pull request titles
# and branch names
dev-dependencies:
# Define patterns to include dependencies in the group (based on
# dependency name)
applies-to: version-updates # Applies the group rule to version updates
patterns:
- "rubocop" # A single dependency name
- "rspec*" # A wildcard string that matches multiple dependency names
- "*" # A wildcard that matches all dependencies in the package
# ecosystem. Note: using "*" may open a large pull request
# Define patterns to exclude dependencies from the group (based on
# dependency name)
exclude-patterns:
- "gc_ruboconfig"
- "gocardless-*"
示例 3
对 dependabot.yml
文件进行了配置,以便与最高可解析版本为 minor
或 patch
的模式 @angular*
匹配的任何包都将分到同一个组。 Dependabot 将为任何不匹配模式的包,或者没有更新到 minor
或 patch
版本的包创建一个单独的拉取请求。分组规则只适用于版本更新,因为使用了 applies-to: version-updates
。
# `dependabot.yml` file using the `update-types` option to group updates.
# Any packages matching the pattern @angular* where the highest resolvable
# version is minor or patch will be grouped together.
# Grouping rules apply to version updates only.
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
groups:
angular:
applies-to: version-updates
patterns:
- "@angular*"
update-types:
- "minor"
- "patch"
示例 4
dependabot.yml
文件使用 ignore
条件来排除对 major
版本 @angular*
包的更新。指定了两个分组规则,一个用于版本更新,另一个用于安全更新。
# `dependabot.yml` file using the `update-types` option to group updates
# in conjunction with an `ignore` condition. If you do not want updates
# to `major` versions of `@angular*` packages, you can specify an `ignore` condition.
# Grouping rules for both version updates and security updates are specified.
groups:
angular:
applies-to: version-updates
patterns:
- "@angular*"
update-types:
- "minor"
- "patch"
minor-and-patch:
applies-to: security-updates
patterns:
- "@angular*"
update-types:
- "patch"
- "minor"
ignore:
- dependency-name: "@angular*"
update-types: ["version-update:semver-major"]
多目录支持不同于拉取请求中的更新组。
dependabot.yml
文件中的directories
选项允许同时将 Dependabot updates 应用到多个目录。dependabot.yml
文件中的groups
选项会为 Dependabot 创建依赖项集(每个包管理器),并将其放入同一个拉取请求。
如果要在存储库上使用这两项功能,则需要使用上述两个密钥,独立地显式启用这些功能。 有关多目录支持的详细信息,请参阅“directories
”。
ignore
默认情况下,清单中明确定义的所有依赖项都通过 Dependabot 版本更新保持最新。 此外,Dependabot 安全更新还更新了锁定文件中定义的易受攻击的依赖项。 可以使用 allow
和 ignore
自定义要维护的依赖项。 Dependabot 可检查所有被允许的依赖项,然后过滤到任何被忽略的依赖项或版本。 因此,将忽略由 allow
和 ignore
匹配的依赖项。
通过将依赖项添加到 ignore
,或者对由 Dependabot 打开的拉取请求使用 @dependabot ignore
命令,可以忽略依赖项。
警告:
-
建议_不要_使用
ignore
阻止 Dependabot 访问专用注册表。 这种方法可能适用于某些生态系统,但我们无法知道包管理器是否需要访问所有依赖项才能成功执行更新,这使得这种方法不可靠。 处理专用依赖项的受支持方法是向 Dependabot 授予对专用注册表或专用存储库的访问权限。 有关详细信息,请参阅“为 Dependabot 配置对专用注册表的访问权限”。 -
对于 GitHub Actions 和 Docker,可以使用
ignore
来阻止 Dependabot 访问专用注册表。
从 @dependabot ignore
创建 ignore
条件
使用 @dependabot ignore
命令忽略的依赖项将针对每个包管理器集中存储。 如果开始忽略 dependabot.yml
文件中的依赖项,则这些现有首选项将与配置中的 ignore
依赖项一起考虑。
可以在存储库中搜索 "@dependabot ignore" in:comments
或使用 @dependabot show DEPENDENCY_NAME ignore conditions
注释命令来检查该存储库是否存储了 ignore
首选项。 如果希望取消阻止以这种方式忽略的依赖项更新,请重新打开此拉取请求。 这会清除拉取请求关闭时设置的 ignore
条件,并恢复依赖项的 Dependabot 更新。 若要将依赖项更新到较新版本,请合并拉取请求。 在已分组更新的拉取请求中,还可以使用 @dependabot unignore
命令清除依赖项的 ignore
设置。
有关 @dependabot ignore
命令的详细信息,请参阅“管理依赖项更新的所有拉取请求”。
指定要忽略的依赖项和版本
可以使用 ignore
选项自定义更新的依赖项。 ignore
选项支持以下选项。
选项 | 说明 |
---|---|
dependency-name | 用于忽略具有匹配名称的依赖项的更新,可以选择使用 * 匹配零个或多个字符。对于 Java 依赖项, dependency-name 属性的格式为 groupId:artifactId (例如:org.kohsuke:github-api )。要防止 Dependabot 从 DefinitelyTyped 自动更新 TypeScript 类型定义,请使用 @types/* 。 |
versions | 用于忽略特定版本或版本范围。 如果要定义范围,请使用包管理器的标准模式。 例如:对于 npm,请使用 ^1.0.0 ;对于 Bundler,请使用 ~> 2.0 ;对于 Docker,请使用 Ruby 版本语法;对于 NuGet,请使用 7.* 。 |
update-types | 用于忽略更新类型,例如版本更新的 semver major 、minor 或 patch 更新(例如:version-update:semver-patch 将忽略修补程序更新)。 可以将其与 dependency-name: "*" 相结合,以忽略所有依赖项的特定 update-types 。目前,仅支持 version-update:semver-major 、version-update:semver-minor 和 version-update:semver-patch 选项。 |
单独使用时,ignore.versions
密钥会影响 Dependabot 更新,但 ignore.update-types
密钥仅影响 Dependabot version updates。
但是,如果 versions
和 update-types
在同一 ignore
规则中一起使用,则 Dependabot 更新都会受到影响,除非配置使用 target-branch
检查非默认分支上的版本更新。
# Use `ignore` to specify dependencies that should not be updated
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
ignore:
- dependency-name: "express"
# For Express, ignore all Dependabot updates for version 4 and 5
versions: ["4.x", "5.x"]
# For Lodash, ignore all updates
- dependency-name: "lodash"
# For AWS SDK, ignore all patch updates for version updates only
- dependency-name: "aws-sdk"
update-types: ["version-update:semver-patch"]
- package-ecosystem: 'github-actions'
directory: '/'
schedule:
interval: 'weekly'
ignore:
- dependency-name: 'actions/checkout'
# For GitHub Actions, ignore all updates greater than or equal to version 3
versions: '>= 3'
注意:Dependabot 在可以访问文件中的所有依赖项时,只能在清单或锁定文件上运行版本更新,即使你将不可访问的依赖项添加到配置文件的 ignore
选项也是如此。 有关详细信息,请参阅“管理组织的安全和分析设置”和“排查 Dependabot 错误”。
注意:对于 pub
生态系统,Dependabot 在其尝试更新到的版本被忽略时不会执行更新,即使有可用早期版本也是如此。
以下示例演示 ignore
如何用于自定义更新的依赖项。
忽略特定版本之外的更新
ignore:
- dependency-name: "lodash:*"
versions: [ ">=1.0.0" ]
忽略特定版本之外的更新
ignore:
- dependency-name: "sphinx"
versions: [ "[1.1,)" ]
忽略修补程序更新
ignore:
- dependency-name: "@types/node"
update-types: ["version-update:semver-patch"]
忽略特定版本的更新
ignore:
- dependency-name: "django*"
versions: [ "11" ]
insecure-external-code-execution
包含 package-ecosystem
值 bundler
、mix
和 pip
的包管理器可能会在版本更新过程中在清单中执行外部代码。 这可能允许受损害的软件包窃取凭据或访问已配置的注册。 在 updates
配置中添加 registries
设置时,Dependabot 会自动阻止外部代码执行,在此情况下,版本更新可能会失败。 可以选择通过将 insecure-external-code-execution
设置为 allow
来替代此行为,允许针对 bundler
、mix
和 pip
包管理器的外部代码执行。
# Allow external code execution when updating dependencies from private registries
version: 2
registries:
ruby-github:
type: rubygems-server
url: https://rubygems.pkg.github.com/octocat/github_api
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
updates:
- package-ecosystem: "bundler"
directory: "/rubygems-server"
insecure-external-code-execution: allow
registries: "*"
schedule:
interval: "monthly"
如果定义 registries
设置以允许 Dependabot 访问专用包注册表,并在相同 updates
配置中将 insecure-external-code-execution
设置为 allow
,则发生的外部代码执行将只能访问与该 updates
设置关联的注册表中的包管理器。 不允许访问顶级 registries
配置中定义的任何注册表。
在此示例中,配置文件允许 Dependabot 访问 ruby-github
专用包注册表。 在相同 updates
设置中,insecure-external-code-execution
设置为 allow
,这意味着通过依赖项执行的代码将只能访问 ruby-github
注册表,而不能访问 dockerhub
注册表。
# Using `registries` in conjunction with `insecure-external-code-execution:allow`
# in the same `updates` setting
version: 2
registries:
ruby-github:
type: rubygems-server
url: https://rubygems.pkg.github.com/octocat/github_api
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
dockerhub:
type: docker-registry
url: registry.hub.docker.com
username: octocat
password: ${{secrets.DOCKERHUB_PASSWORD}}
updates:
- package-ecosystem: "bundler"
directory: "/rubygems-server"
insecure-external-code-execution: allow
registries:
- ruby-github # only access to registries associated with this ecosystem/directory
schedule:
interval: "monthly"
可以通过将 insecure-external-code-execution
设置为 deny
显式拒绝外部代码执行,而不考虑此更新配置是否有 registries
设置。
labels
默认情况下,Dependabot 会提出所有带有 dependencies
标签的拉取请求。 如果定义了多个包管理器,Dependabot 在每个拉取请求上都会包含一个附加标签。 这表示拉取请求将更新的语言或生态系统,例如:java
表示 Gradle 更新,submodules
表示 git 子模块。 Dependabot 将根据需要自动在您的仓库中创建这些默认标签。
使用 labels
替代默认标签,并为针对包管理器提出的所有拉取请求指定替代标签。 如果其中任何标签未在仓库中定义,将被忽略。
若要禁用所有标签(包括默认标签),请使用 labels: [ ]
。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
# Specify labels for pull requests
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Specify labels for npm pull requests
labels:
- "npm"
- "dependencies"
milestone
使用 milestone
将针对包管理器提出的所有拉取请求与里程碑相关联。 您需要指定里程碑的数字标识符,而不是其标签。 如果查看里程碑,则 milestone
之后的页面 URL 的最后一部分是标识符。 例如:https://github.com/<org>/<repo>/milestone/3
。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
# Specify a milestone for pull requests
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Associate pull requests with milestone "4"
milestone: 4
open-pull-requests-limit
默认情况下, Dependabot 最多打开五个版本更新的拉取请求。 Dependabot 中有五个打开的拉取请求后,Dependabot 不会打开任何新请求,直到其中一些打开的请求合并或关闭。 使用 open-pull-requests-limit
可以更改此限制。 这也提供了一个简单的方法来暂时禁用包管理器的版本更新。
此选项对安全更新没有影响,因为安全更新具有单独的内部限制:10 个打开的拉取请求。
# Specify the number of open pull requests allowed
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Disable version updates for npm dependencies
open-pull-requests-limit: 0
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# Allow up to 10 open pull requests for pip dependencies
open-pull-requests-limit: 10
pull-request-branch-name.separator
Dependabot 为每个拉取请求生成分支。 每个分支名称都包括 dependabot
,以及更新的包管理器和依赖项。 默认情况下,这些部分由 /
符号分隔,例如:dependabot/npm_and_yarn/next_js/acorn-6.4.1
。
使用 pull-request-branch-name.separator
指定不同的分隔符。 这可以是 "-"
、_
或 /
之一。 连字符必须用引号括住,否则会解释为开始一个空的 YAML 列表。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
# Specify a different separator for branch names
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
pull-request-branch-name:
# Separate sections of the branch name with a hyphen
# for example, `dependabot-npm_and_yarn-next_js-acorn-6.4.1`
separator: "-"
rebase-strategy
默认情况下,Dependabot 会在检测到拉取请求有任何更改时自动变基打开的拉取请求。 使用 rebase-strategy
可以禁用此行为。
注意:如果拉取请求 30 天未合并,Dependabot 将停止对拉取请求进行变基。 你仍然可以手动对拉取请求进行变基与合并。
可用的变基策略
auto
用于在检测到更改时使用默认行为并变基打开的拉取请求。disabled
用于禁用自动变基。
当 rebase-strategy
设置为 auto
时,Dependabot 会基于以下情况下尝试变基拉取请求。
- 使用 Dependabot version updates 时,适用于计划运行时任何打开的 Dependabot 拉取请求。
- 重新打开已关闭的 Dependabot 拉取请求。
- 在 Dependabot 配置文件中更改
target-branch
的值时。 有关此字段的详细信息,请参阅“target-branch
”。 - 当 Dependabot 检测到 Dependabot 拉取请求在最近推送到目标分支后发生冲突时。
当 rebase-strategy
设置为 disabled
时,Dependabot 将停止变基拉取请求。
注意:此行为仅适用于与目标分支冲突的拉取请求。 Dependabot 将继续变基在更改 rebase-strategy
设置之前打开的拉取请求(直到打开后 30 天),以及计划运行中的拉取请求。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
# Disable automatic rebasing
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Disable rebasing for npm pull requests
rebase-strategy: "disabled"
registries
若要在执行版本更新时允许 Dependabot 访问专用包注册表,必须在相关 updates
配置中包含 registries
设置。
dependabot.yml
文件中有 2 个位置可以使用 registries
密钥:
- 在顶级,可在这里定义注册表及其访问信息(如果需要)。
- 在
updates
块中,可以使用registries: "*"
告知 Dependabot 使用你在顶级定义的任何或所有注册表。
# registries: gradle-artifactory - provides access details for the gradle-artifactory registry
# registries: "*" - allows Dependabot to use all the defined registries specified at the top level
version: 2
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: "*"
schedule:
interval: "monthly"
有关详细信息,请参阅下面的“专用注册表的配置选项”。
有关可用选项的详细信息,以及配置专用注册表时的建议,请参阅“针对 Dependabot 的专用注册表配置指南”。
若要允许 Dependabot 使用 bundler
、mix
和 pip
包管理器更新专用注册表中的依赖项,可以选择允许外部代码执行。 有关详细信息,请参阅上面的 insecure-external-code-execution
。
# Allow Dependabot to use one of the two defined private registries
# when updating dependency versions for this ecosystem
version: 2
registries:
maven-github:
type: maven-repository
url: https://maven.pkg.github.com/octocat
username: octocat
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
npm-npmjs:
type: npm-registry
url: https://registry.npmjs.org
username: octocat
password: ${{secrets.MY_NPM_PASSWORD}}
updates:
- package-ecosystem: "gitsubmodule"
directory: "/"
registries:
- maven-github
schedule:
interval: "monthly"
reviewers
使用 reviewers
为针对包管理器提出的所有拉取请求指定单个审阅者或审阅者团队。 必须使用完整的团队名称,包括组织,就像你是 @mentioning 团队一样。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
# Specify reviewers for pull requests
version: 2
updates:
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# Add reviewers
reviewers:
- "octocat"
- "my-username"
- "my-org/python-team"
schedule.day
设置 weekly
更新计划时,默认情况下,Dependabot 会在周一的随机设置时间检查存储库的新版本。 使用 schedule.day
可以指定检查更新的备用日期。
支持的值
monday
tuesday
wednesday
thursday
friday
saturday
sunday
# Specify the day for weekly checks
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Check for npm updates on Sundays
day: "sunday"
schedule.time
默认情况下,Dependabot 在仓库的随机设置时间检查新版本。 使用 schedule.time
可以指定检查更新的备用时间(格式:hh:mm
)。
# Set a time for checks
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Check for npm updates at 9am UTC
time: "09:00"
schedule.timezone
默认情况下,Dependabot 在仓库的随机设置时间检查新版本。 使用 schedule.timezone
可以指定备用时区。 时区标识符必须来自 iana 维护的时区数据库。 有关详细信息,请参阅 tz 数据库时区列表。
# Specify the timezone for checks
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
time: "09:00"
# Use Japan Standard Time (UTC +09:00)
timezone: "Asia/Tokyo"
target-branch
默认情况下,Dependabot 会检查默认分支上的清单文件,并对此分支提出版本更新的拉取请求。 使用 target-branch
可以为清单文件和拉取请求指定不同的分支。 使用此选项时,此包管理器的设置将不再影响针对安全更新提出的任何拉取请求。
# Specify a non-default branch for pull requests for pip
version: 2
updates:
- package-ecosystem: "pip"
directory: "/"
schedule:
interval: "weekly"
# Raise pull requests for version updates
# to pip against the `develop` branch
target-branch: "develop"
# Labels on pull requests for version updates only
labels:
- "pip dependencies"
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "weekly"
# Check for npm updates on Sundays
day: "sunday"
# Labels on pull requests for security and version updates
labels:
- "npm dependencies"
vendor
使用 vendor
选项指示 Dependabot 在更新依赖项时提供其供应商。 如果使用 gomod
,请勿使用此选项,因为 Dependabot 会自动检测此工具的供应。
# Configure version updates for both dependencies defined in manifests and vendored dependencies
version: 2
updates:
- package-ecosystem: "bundler"
# Raise pull requests to update vendored dependencies that are checked in to the repository
vendor: true
directory: "/"
schedule:
interval: "weekly"
Dependabot 仅更新位于仓库的特定目录中供应的依赖项。
程序包管理器 | 供应的依赖项所需的文件路径 | 详细信息 |
---|---|---|
bundler | 依赖项必须位于 vendor/cache 目录中。 不支持其他文件路径。 | bundle cache 文档 |
gomod | 无路径要求(依赖项通常位于 vendor 目录中) | go mod vendor 文档 |
versioning-strategy
当 Dependabot 编辑清单文件以更新版本时,有几种不同的潜在版本控制策略:
选项 | 操作 |
---|---|
auto | 尝试区分应用和库。 应用使用 increase ,库则使用 widen 。 |
increase | 始终增加最低版本要求以匹配新版本。 如果范围已存在,通常这只会增加下限。 |
increase-if-necessary | 如果原始约束允许新版本,则保留该约束,否则请升级该约束。 |
lockfile-only | 仅创建用于更新 lockfiles 的拉取请求。 忽略任何需要包清单更改的新版本。 |
widen | 尽可能放宽允许的版本要求,以包括新旧版本。 通常,这只会增加允许的最大版本要求。 |
不可用 | 某些包管理器尚不支持配置 versioning-strategy 参数。 |
下表显示了如何使用 versioning-strategy
的示例。
当前约束 | 当前版本 | 新版本 | 策略 | New 约束 |
---|---|---|---|---|
^1.0.0 | 1.0.0 | 1.2.0 | widen | ^1.0.0 |
^1.0.0 | 1.0.0 | 1.2.0 | increase | ^1.2.0 |
^1.0.0 | 1.0.0 | 1.2.0 | increase-if-necessary | ^1.0.0 |
^1.0.0 | 1.0.0 | 2.0.0 | widen | >=1.0.0 <3.0.0 |
^1.0.0 | 1.0.0 | 2.0.0 | increase | ^2.0.0 |
^1.0.0 | 1.0.0 | 2.0.0 | increase-if-necessary | ^2.0.0 |
使用 versioning-strategy
选项可以更改受支持的包管理器的此行为。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求,除非使用 target-branch
检查非默认分支上的版本更新。
可用的更新策略:
生态系统 | 支持的版本控制策略 | 默认策略 |
---|---|---|
bundler | auto 、increase 、increase-if-necessary 、lockfile-only | auto |
cargo | auto 、lockfile-only | auto |
composer | auto 、increase 、increase-if-necessary 、lockfile-only 、widen | auto |
docker | 空值 | 不可用 |
github-actions | 不可用 | 不可用 |
gitsubmodule | 不可用 | 不可用 |
gomod | 不可用 | 不可用 |
gradle | 不可用 | 不可用 |
maven | 不可用 | 空值 |
mix | auto 、lockfile-only | auto |
npm | auto 、increase 、increase-if-necessary 、lockfile-only 、widen | auto |
nuget | 空值 | 空值 |
pip | auto 、increase 、increase-if-necessary 、lockfile-only | auto |
pub | auto 、increase 、increase-if-necessary 、widen | auto |
terraform | 空值 | 空值 |
备注:N/A
指示包管理器尚不支持配置 versioning-strategy
参数。 策略代码是开放源代码,因此,如果你希望特定生态系统支持新策略,随时欢迎在 https://github.com/dependabot/dependabot-core/ 中提交拉取请求。
# Example configuration for customizing the manifest version strategy
version: 2
updates:
- package-ecosystem: "composer"
directory: "/"
schedule:
interval: "weekly"
# Increase the version requirements for Composer only when required
versioning-strategy: increase-if-necessary
私人注册的配置选项
顶级 registries
项是可选的。 它允许您指定 Dependabot 可用于访问私人包注册表的身份验证详细信息。
可以通过指定 git
的 type
来授予 Dependabot 对 GitLab 或 Bitbucket 托管的私有包注册表的访问权限。 有关详细信息,请参阅 git
。
registries
项的值是一个关联阵列,其中每个元素由一个标识特定注册表的键和一个为关联阵列的值组成,该值指定访问该注册表所需的设置。 下列 dependabot.yml
文件会在文件的 registries
部分配置一个标识为 dockerhub
的注册表,然后在文件的 updates
部分中引用该注册表。
# Minimal settings to update dependencies in one private registry
version: 2
registries:
dockerhub: # Define access for a private registry
type: docker-registry
url: registry.hub.docker.com
username: octocat
password: ${{secrets.DOCKERHUB_PASSWORD}}
updates:
- package-ecosystem: "docker"
directory: "/docker-registry/dockerhub"
registries:
- dockerhub # Allow version updates for dependencies in this registry
schedule:
interval: "monthly"
您使用以下选项来指定访问设置。 注册表设置必须包含 type
和 url
,并且通常包含 username
和 password
组合或 token
。
选项 | 说明 |
---|---|
type | 识别注册表的类型。 有关可用注册表类型的详细信息,请参阅“registries ”。有关专用注册表配置的更多详细信息,请参阅“专用注册表的配置选项”。 |
url | 用于访问此注册表中的依赖项的 URL。 协议是可选的。 如果未指定,则假定为 https:// 。 Dependabot 根据需要添加或忽略尾随斜线。 |
username | Dependabot 用于访问注册表的用户名。username 是帐户的用户名或电子邮件地址。 |
password | 引用包含指定用户密码的 Dependabot 机密。 有关详细信息,请参阅“为 Dependabot 配置对专用注册表的访问权限”。password 是为该用户名所指定用户帐户的密码。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。 |
key | 引用包含此注册表访问密钥的 Dependabot 机密。 有关详细信息,请参阅“为 Dependabot 配置对专用注册表的访问权限”。 |
token | 引用包含此注册表访问令牌的 Dependabot 机密。 有关详细信息,请参阅“为 Dependabot 配置对专用注册表的访问权限”。token 用于为外部系统提供访问令牌,不应用于提供 GitHub personal access token。 要使用 GitHub personal access token,则应将其作为密码提供。 |
replaces-base | 对于注册表,如果布尔值为 true ,Dependabot 会使用指定的 URL 而不是特定生态系统的基 URL 来解析依赖项。 例如,对于包含 type: python-index 的注册表,如果布尔值为 true ,pip 会使用指定的 URL 而不是 Python 包索引的基 URL(默认为 https://pypi.org/simple )来解析依赖项。 |
你必须为指定的每个配置 type
提供必需的设置。 某些类型允许多种连接方式。 以下部分提供了每个 type
应该使用的设置的详细信息。
有关可用选项的详细信息,以及配置专用注册表时的建议,请参阅“针对 Dependabot 的专用注册表配置指南”。
cargo-registry
cargo-registry
类型支持令牌。
此注册表类型会与 url
选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据,用于访问不同的路径。 不过,如果同一主机上没有多个注册表,建议省略 url
中的路径,以便注册表的所有路径都会收到凭据。
registries:
cargo-example:
type: cargo-registry
registry: "name-of-your-registry"
url: https://cargo.cloudsmith.io/foobaruser/test/
token: "Token ${{secrets.CARGO_TOKEN}}"
我们已针对 https://cargo.cloudsmith.io
专用注册表测试此配置。
composer-repository
composer-repository
类型支持用户名和密码。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
此注册表类型会与 url
选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据,用于访问不同的路径。 不过,如果同一主机上没有多个注册表,建议省略 url
中的路径,以便注册表的所有路径都会收到凭据。
registries:
composer:
type: composer-repository
url: https://repo.packagist.com/example-company/
username: octocat
password: ${{secrets.MY_PACKAGIST_PASSWORD}}
docker-registry
Dependabot 可与实现 OCI 容器注册表规范的任何容器注册表配合使用。有关详细信息,请参阅 https://github.com/opencontainers/distribution-spec/blob/main/spec.md。 Dependabot 支持通过中央令牌服务或 HTTP 基本身份验证对专用注册表进行身份验证。有关更多详细信息,请参阅 Docker 文档中的令牌身份验证规范和维基百科上的基本访问身份验证。
docker-registry
类型支持用户名和密码。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
此注册表类型会与 url
选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据,用于访问不同的路径。 不过,如果同一主机上没有多个注册表,建议省略 url
中的路径,以便注册表的所有路径都会收到凭据。
registries:
dockerhub:
type: docker-registry
url: https://registry.hub.docker.com
username: octocat
password: ${{secrets.MY_DOCKERHUB_PASSWORD}}
replaces-base: true
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}}
replaces-base: true
git
git
类型支持用户名和密码。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
registries:
github-octocat:
type: git
url: https://github.com
username: x-access-token
password: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
hex-organization
hex-organization
类型支持组织和密钥。
此注册表类型会与 url
选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据,用于访问不同的路径。 不过,如果同一主机上没有多个注册表,建议省略 url
中的路径,以便注册表的所有路径都会收到凭据。
registries:
github-hex-org:
type: hex-organization
organization: github
key: ${{secrets.MY_HEX_ORGANIZATION_KEY}}
hex-repository
hex-repository
类型支持身份验证密钥。
repo
是必填字段,必须与依赖项声明中使用的存储库的名称匹配。
public-key-fingerprint
为可选配置字段,表示 Hex 存储库的公钥指纹。 Hex 使用 public-key-fingerprint
与专用存储库建立信任关系。 public-key-fingerprint
字段可以以纯文本形式列出,也可以存储为 Dependabot 机密。
registries:
github-hex-repository:
type: hex-repository
repo: private-repo
url: https://private-repo.example.com
auth-key: ${{secrets.MY_AUTH_KEY}}
public-key-fingerprint: ${{secrets.MY_PUBLIC_KEY_FINGERPRINT}}
maven-repository
maven-repository
类型支持用户名和密码。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
此注册表类型会与 url
选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据,用于访问不同的路径。 不过,如果同一主机上没有多个注册表,建议省略 url
中的路径,以便注册表的所有路径都会收到凭据。
registries:
maven-artifactory:
type: maven-repository
url: https://acme.jfrog.io/artifactory/my-maven-registry
username: octocat
password: ${{secrets.MY_ARTIFACTORY_PASSWORD}}
npm-registry
npm-registry
类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
使用用户名和密码时,.npmrc
的身份验证令牌可能包含 base64
编码的 _password
;但是,Dependabot 配置文件中引用的密码必须是原始(未编码)密码。
注意:使用 npm.pkg.github.com
时不包括路径。 请改用没有路径的 https://npm.pkg.github.com
URL。
registries:
npm-npmjs:
type: npm-registry
url: https://registry.npmjs.org
username: octocat
password: ${{secrets.MY_NPM_PASSWORD}} # Must be an unencoded password
replaces-base: true
registries:
npm-github:
type: npm-registry
url: https://npm.pkg.github.com
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
replaces-base: true
出于安全原因, Dependabot 不设置环境变量。 Yarn(v2 及更高版本)要求设置任何访问的环境变量。 访问 .yarnrc.yml
文件中的环境变量时,应提供回退值,例如 ${ENV_VAR-fallback}
或 ${ENV_VAR:-fallback}
。 有关详细信息,请参阅 Yarn 文档中的 Yarnrc 文件。
nuget-feed
nuget-feed
类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
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}}
pub-repository
pub-repository
类型支持 URL 和令牌。
registries:
my-pub-registry:
type: pub-repository
url: https://example-private-pub-repo.dev/optional-path
token: ${{secrets.MY_PUB_TOKEN}}
updates:
- package-ecosystem: "pub"
directory: "/"
schedule:
interval: "weekly"
registries:
- my-pub-registry
python-index
python-index
类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
此注册表类型会与 url
选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据,用于访问不同的路径。 不过,如果同一主机上没有多个注册表,建议省略 url
中的路径,以便注册表的所有路径都会收到凭据。
registries:
python-example:
type: python-index
url: https://example.com/_packaging/my-feed/pypi/example
username: octocat
password: ${{secrets.MY_BASIC_AUTH_PASSWORD}}
replaces-base: true
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}}
replaces-base: true
rubygems-server
rubygems-server
类型支持用户名和密码或者令牌。 如果帐户是 GitHub 帐户,则可以使用 GitHub personal access token 代替密码。
此注册表类型会与 url
选项中提供的路径进行前缀匹配。 这表示可以向同一主机提供多个凭据,用于访问不同的路径。 不过,如果同一主机上没有多个注册表,建议省略 url
中的路径,以便注册表的所有路径都会收到凭据。
registries:
ruby-example:
type: rubygems-server
url: https://rubygems.example.com
username: octocat@example.com
password: ${{secrets.MY_RUBYGEMS_PASSWORD}}
replaces-base: true
registries:
ruby-github:
type: rubygems-server
url: https://rubygems.pkg.github.com/octocat/github_api
token: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}
replaces-base: true
terraform-registry
terraform-registry
类型支持令牌。
registries:
terraform-example:
type: terraform-registry
url: https://terraform.example.com
token: ${{secrets.MY_TERRAFORM_API_TOKEN}}
启用对 beta 层级生态系统的支持
enable-beta-ecosystems
默认情况下,Dependabot 仅针对完全支持的生态系统更新依赖项清单和锁定文件。 使用 enable-beta-ecosystems
标志选择加入尚未正式发布的生态系统更新。
beta 中当前没有生态系统。
# Configure beta ecosystem
version: 2
enable-beta-ecosystems: true
updates:
- package-ecosystem: "beta-ecosystem"
directory: "/"
schedule:
interval: "weekly"