# Dependabot 选项参考
所有可用于自定义 Dependabot 维护存储库方式的选项详细信息。
本文提供有关`dependabot.yml`文件中可用配置选项的参考信息。 使用这些选项自定义 Dependabot 如何监视包生态系统、安排更新和创建拉取请求。 有关`dependabot.yml`文件及其工作原理的概述，请参阅[关于 dependabot.yml 文件](/zh/code-security/concepts/supply-chain-security/about-the-dependabot-yml-file)。
标有 图标的所有选项也会更改 Dependabot 创建安全更新拉取请求的方式，除非使用 `target-branch`。
### 必需的密钥
| Key | 位置 | 目的 |
| --------- | -- | -- |
| `version` | 顶层 | |
```
Dependabot 要使用的配置语法。 始终：`2`。|
```
\| `updates` | 顶层| 定义每个 `package-ecosystem` 以进行更新的部分。|
\| [`package-ecosystem`](#package-ecosystem-) | （位于 `updates` 下面） | 定义要更新的包管理器。 |
\| [
`directories` 或 `directory`](#directories-or-directory--) | 在每个 `package-ecosystem` 项下 | 定义要更新的清单文件或其他定义文件的位置。 |
\| [`schedule.interval`](#schedule-) | 在每个 `package-ecosystem` 项下 | 定义是否查找版本更新：`daily`、、`weekly`、`monthly``quarterly`、`semiannually`、或。 `yearly``cron` |
（可选）你还可以包含一个顶层 `registries` 密钥，以定义专用注册表的访问详情，请参阅[顶层 `registries` 密钥](#top-level-registries-key)。
```yaml copy
# Basic `dependabot.yml` file with
# minimum configuration for two package managers
version: 2
updates:
# Enable version updates for npm
- package-ecosystem: "npm"
# Look for `package.json` and `lock` files in the `root` directory
directory: "/"
# Check the npm registry for updates every day (weekdays)
schedule:
interval: "daily"
# Enable version updates for Docker
- package-ecosystem: "docker"
# Look for a `Dockerfile` in the `root` directory
directory: "/"
# Check for updates once a week
schedule:
interval: "weekly"
```
要查看关于文件的实际示例，请参阅自己的配置文件。
##
```
`allow`
```
用于精确定义要为包生态系统维护的依赖项。 通常与 [`ignore`](#ignore--) 选项配合使用。 有关示例，请参阅“[控制 Dependabot 更新的依赖项](/zh/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#allowing-specific-dependencies-to-be-updated)”。
```
Dependabot 默认行为：
```
* 清单中显式定义的所有依赖项都由版本更新保持最新。
* 在具有易受攻击依赖项的锁文件中定义的所有依赖项都由安全更新更新。
当`allow`被指定时，Dependabot使用以下过程：
1. 检查所有明确**允许**的依赖项。
2. 然后筛选掉所有被**忽略**的依赖项或版本。
如果某个依赖项同时匹配 `allow` 和 `ignore` 语句，则会被**忽略**。
| 参数 | 目的 |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- |
| `dependency-name` | 允许名称匹配的依赖项进行更新，可选使用 `*` 匹配零个或多个字符。 |
| `dependency-type` | 允许特定类型的依赖项进行更新。 |
| | |
| `update-types` | 允许更新一个或多个语义版本控制级别。 支持的值：`version-update:semver-patch`、`version-update:semver-minor`和 `version-update:semver-major`。 |
| | |
###
```
`dependency-name`（`allow`）
```
对于大多数包管理器，应定义一个值，使其与锁定文件或清单文件中指定的依赖项名称匹配。 少数系统有更复杂的要求。
| 程序包管理器 | 所需格式 | Example |
| -------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Gradle 和 Maven | `groupId:artifactId` | `org.kohsuke:github-api` |
| 用于映像标签的 Docker | 存储库的全名 | 对于 `.dkr.ecr.us-west-2.amazonaws.com/base/foo/bar/ruby:3.1.0-focal-jemalloc` 的映像标签，请使用 `base/foo/bar/ruby`。 |
###
```
`dependency-type`（`allow`）
```
| 依赖项类型 | 支持的包管理器 | 允许更新 |
| ---------- | ------- | ----------- |
| `direct` | All | 所有明确定义的依赖项。 |
| `indirect` | | |
```
`bundler`、、`pip``composer`、`cargo`、`gomod`、`uv` | 直接依赖项的依赖项（也称为子依赖项或传递依赖项）。|
```
\| `all` | All | 所有明确定义的依赖项。 对于 `bundler`、`pip`、`composer`、`cargo`、`gomod`、`uv`，还包括直接依赖项的依赖项。|
\| `production` |
`bundler`、、`composer``mix`、`maven`、`npm`、、`pip`（ `uv` 不是所有经理） | 仅适用于包管理器定义为生产依赖项的依赖项。 |
\| `development`|
`bundler`、、`composer``mix`、`maven`、`npm`、、`pip`（ `uv` 不是所有经理） | 仅适用于包管理器定义为开发依赖项的依赖项。 |
###
```
`update-types`（`allow`）
`update-types` 仅影响 _版本_ 更新，而不会影响 _安全更新_。
```
指定要允许的语义版本（SemVer）。
SemVer 是定义软件包版本的公认标准，格式为 `x.y.z`。
Dependabot 假定以这种形式的版本始终为 `major.minor.patch`。 该值 `update-types` 是一个或多个字符串的列表。
* 使用 `version-update:semver-patch` 以允许修补程序发布。
* 使用 `version-update:semver-minor` 允许小版本发布。
* 使用 `version-update:semver-major` 以允许主要版本发布。
如果 `update-types` 从 `allow` 规则中省略，则允许该规则使用所有更新类型。
可以结合`update-types``dependency-name`或`dependency-type`进一步缩小允许的更新范围。 有关如何合并这些选项的示例，请参阅 [控制 Dependabot 更新的依赖项](/zh/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/controlling-dependencies-updated#allowing-specific-semantic-versioning-levels-for-updates)。
##
```
`assignees`
```
为针对包生态系统提出的所有所有拉取请求指定单个代理人。 有关示例，请参阅“[自定义 Dependabot 拉取请求以适应你的流程](/zh/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs)”。
```
Dependabot 默认行为：
```
* 创建的拉取请求不含任何代理人。
当定义 `assignees` 时：
* 所有版本更新的拉取请求都由指定的指派者创建。
* 所有安全更新拉取请求均使用选定的受理人创建，除非 `target-branch` 定义了对非默认分支的更新。
代理人必须具有对仓库的写入访问权限。 对于组织拥有的存储库，具有读取权限的组织成员也是有效的代理人。
##
```
`commit-message`
```
定义提交消息的格式。 由于拉取请求的标题基于提交消息编写，因此此设置也会影响拉取请求的标题。 有关示例，请参阅“[自定义 Dependabot 拉取请求以适应你的流程](/zh/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs)”。
```
Dependabot 默认行为：
```
* 提交消息遵循与存储库中检测到的模式类似的模式。
当定义 `commit-message` 时：
* 所有提交消息都遵循定义的模式。
* 所有提交消息都遵循定义的模式，除非 `target-branch` 定义对非默认分支的更新。
| 参数 | 目的 |
| -------------------- | ----------------------------------- |
| `prefix` | 为所有提交消息和拉取请求标题定义前缀。 |
| `prefix-development` | 在受支持的系统上，为更新“开发依赖项组”中依赖项的提交定义不同的前缀。 |
| `include` | 在提交信息前缀后面添加附加信息。 |
> \[!TIP]
> 当为分组更新提出拉取请求时，分支名称和拉取请求标题由组 `IDENTIFIER` 定义，请参阅 [`groups`](#groups--)。
### `prefix`
* 用于所有提交消息，除非还定义了 `prefix-development`。
* 值最多可包含 50 个字符。
* Dependabot 当值以字母、数字、右括号或右括号结尾时，在添加主提交消息之前，在前缀后面插入冒号。
* 以空格字符结束该值，可避免添加冒号。
### `prefix-development`
支持：`bundler`、、`composer`、`mix`、`maven``npm`、、 `pip`和`uv`。
* 仅用于更新“开发依赖项组”中依赖项的提交消息。
* 否则，该参数的行为与 `prefix` 参数完全相同。
### `include`
* 仅支持值 `scope`
* 当定义时，任何前缀将后跟提交中更新的依赖项类型：`deps` 或 `deps-dev`。
##
```
`cooldown`
```
定义依赖项更新的冷却期，允许更新延迟指定天数\*\*\*\*。 此选项 `cooldown` 仅适用于 *版本* 更新，而不适用于 *安全更新* 。
此功能使用户能够自定义生成新版本更新的频率 Dependabot ，从而更好地控制更新频率。 有关示例，请参阅“[优化 Dependabot 版本更新的拉取请求创建](/zh/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates#setting-up-a-cooldown-period-for-dependency-updates)”。
```
Dependabot 默认行为：
```
* 根据通过 `schedule.interval` 定义的计划更新检查更新。
* 立即将所有新版本纳入更新考虑范围\*\*\*\*。
当定义 **`cooldown`** 时：
1. ```
Dependabot 根据定义的 `schedule.interval` 设置检查更新。
```
2. ```
Dependabot 检查是否有任何冷却设置。
```
3. 如果依赖项的新版本在其冷却期内， Dependabot 则跳过更新该依赖项的版本。
4. 没有冷却期的依赖项，或已过冷却期的依赖项，会根据已配置的 `versioning-strategy` 设置更新至最新版本。
5. 在依赖项的冷却结束之后， Dependabot 按照定义的 `dependabot.yml`标准更新策略恢复更新依赖项。
###
```
**
`cooldown` 的配置**
```
可以使用以下选项指定冷却的持续时间。
| 参数 | Description |
| ------------------- | -------------------------------------------------------- |
| `default-days` | 无特定规则的**依赖项的默认冷却期**（可选）。 |
| `semver-major-days` | 主要版本更新的冷却期（可选，仅适用于支持 SemVer 的包管理器）\*\*\*\*。 |
| `semver-minor-days` | 次要版本更新的冷却期（可选，仅适用于支持 SemVer 的包管理器）\*\*\*\*。 |
| `semver-patch-days` | 补丁版本更新的冷却期（可选，仅适用于支持 SemVer 的包管理器）\*\*\*\*。 |
| `include` | 需要应用冷却期的依赖项的列表（最多 150 项）\*\*\*\*\*\*\*\*。 支持使用通配符 (`*`)。 |
| `exclude` | 排除在冷却期之外的依赖项列表（最多 150 项）\*\*\*\*\*\*\*\*。 支持使用通配符 (`*`)。 |
下表显示了支持 SemVer 的包管理器。
| 程序包管理器 | 支持 SemVer |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| | |
| 巴泽尔 | |
| | |
| Bundler | |
| Bun | |
| Cargo | |
| Composer | |
| DevContainer | |
| Docker | |
| Docker Compose | |
| Dotnet SDK | |
| Elm | |
| GitHub Actions | |
| Gitsubmodule | |
| Gomod（Go 模板） | |
| Gradle | |
| Helm | |
| 十六进制 | |
| | |
| Julia | |
| | |
| Maven | |
| NPM 和 Yarn | |
| NuGet | |
| | |
| OpenTofu | |
| | |
| Pip | |
| Pub | |
| Swift | |
| Terraform | |
| UV | |
> \[!NOTE]
>
> * 如果未定义 `semver-major-days`、`semver-minor-days` 或 `semver-patch-days`，则 `default-days` 设置优先于基于冷却期的更新。
> *
```
`exclude` 列表始终优先于 `include` 列表。 如果在两个列表同时指定了某个依赖项，则该依赖项将排除在冷却期之外，并将立即更新****。
```
##
```
`directories` 或 `directory`
**必需选项**。 用于定义每个包管理器的包清单位置（例如 _package.json_ 或 _Gemfile_）。 如果没有此信息 Dependabot ，则无法为版本更新创建拉取请求。 有关示例，请参阅[针对清单文件定义多个位置](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-multiple-locations-for-manifest-files)。
```
* 使用 `directory` 定义单个清单目录。
* 使用 `directories` 定义多个清单目录的列表。
* 为大多数包管理器定义相对于仓库根目录的目录。
* 对于 GitHub Actions，请使用值 `/`。
Dependabot 将搜索 `/.github/workflows` 目录以及 `action.yml/action.yaml` 根目录中的文件。
如果需要在配置文件中使用多个块来定义生态系统的单个目标分支的更新，必须确保所有值都是唯一的，并且定义的目录没有重叠。
> \[!NOTE]
```
`directories` 键支持通配和通配符 `*`。
```
```
`directory` 键不支持这些功能。
```
##
```
`enable-beta-ecosystems`
```
当前未使用。
##
```
`groups`
```
定义规则以创建包管理器管理的一组或多组依赖项，以将更新分组到针对性更弱的拉取请求中。 有关示例，请参阅“[优化 Dependabot 版本更新的拉取请求创建](/zh/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates)”。
```
Dependabot 默认行为：
```
* 针对版本更新和安全更新，为每个需要更新到较新版本的依赖项打开单个拉取请求。
当使用 `groups` 定义规则时：
* 所有匹配某一规则的依赖项更新会合并到同一个拉取请求中。
* 如果依赖项与多个规则匹配，则它包含在匹配的第一个组中。
* 所有与规则不匹配的过时依赖项将在单独的拉取请求中更新。
| 参数 | 目的 |
| ------------------ | ---------------------------------------------------------------------- |
| `IDENTIFIER` | 定义组的标识符，用于分支名称和拉取请求标题。 该名称必须以字母开头，可包含字母、竖线 `\|`、字下线 `_` 或短划线 `-`。 |
| `applies-to` | 指定组适用的更新类型。 未定义时，默认为版本更新。 支持的值：`version-updates` 或 `security-updates`。 |
| `dependency-type` | 将组限制为一个类型。 支持的值：`development` 或 `production`。 |
| `exclude-patterns` | 定义一个或多个模式，以从组中排除依赖项。 |
| | |
| `group-by` | 对多个目录中的更新进行分组。 支持的值：`dependency-name`。 |
| | |
| `patterns` | 定义一个或多个模式，以包含名称匹配的依赖项。 |
| `update-types` | 将组限制为一个或多个语义化版本控制级别。 支持的值：`minor`、`patch`和 `major`。 |
###
```
`dependency-type`（`groups`）
```
受以下类型支持：`bundler`、`composer`、`mix`、`maven`、`npm` 和 `pip`。
默认情况下，一个组将包含所有类型的依赖项。
* 使用 `development` 以仅包含“开发依赖项组”中的依赖项。
* 使用 `production` 以仅包含“生产依赖项组”中的依赖项。
###
```
`group-by`（`groups`）
```
请使用 `groups..group-by` 指定如何在 monorepo 的多个目录中对 Dependabot 进行更新分组。
* **类型：** 字符串
* **接受的值：**`dependency-name`
* **适用于：** 指定了多个目录的配置
设置为 `dependency-name`时， Dependabot 将为所有指定目录的每个依赖项更新创建单个拉取请求，而不是为每个目录创建单独的拉取请求。
```
**跨目录分组的限制**
```
使用 `group-by: dependency-name` 时：
* 所有目录都必须使用相同的包生态系统（例如，全部 `npm` 或全部 `bundler`）
* **仅适用于版本更新**
* 如果目录对依赖项具有不兼容的版本约束， Dependabot 将创建单独的拉取请求
有关`group-by`用法的示例，请参阅[优化 Dependabot 版本更新的拉取请求创建](/zh/code-security/tutorials/secure-your-dependencies/optimizing-pr-creation-version-updates#grouping-updates-across-directories-in-a-monorepo)。
###
```
`patterns` 和 `exclude-patterns`（`groups`）
```
这两个选项均支持使用 `*` 作为通配符来定义依赖项名称匹配。 如果某个依赖项同时匹配包含模式和排除模式，则会从组中排除。
###
```
`update-types`（`groups`）
```
默认情况下，组将包含所有语义化版本 (SemVer) 的更新。 SemVer 是定义软件包版本的公认标准，格式为 `x.y.z`。 Dependabot 假定此格式的版本始终为 `major.minor.patch`。
* 使用 `patch` 以包含补丁发布。
* 使用 `minor` 以包含次要发布。
* 使用 `major` 以包含主要发布。
有关示例，请参阅“[控制 Dependabot 更新的依赖项](/zh/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#specifying-the-semantic-versioning-level-to-ignore)”。
##
```
`ignore`
```
与 [`allow`](#allow--) 选项配合使用，以精确定义要为包生态系统维护的依赖项。
Dependabot 检查所有允许的依赖项，然后筛选掉任何忽略的依赖项或版本。 因此，同时被允许和忽略规则匹配的依赖项将被忽略。 有关示例，请参阅“[控制 Dependabot 更新的依赖项](/zh/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#ignoring-specific-dependencies)”。
```
Dependabot 默认行为：
```
* 清单中显式定义的所有依赖项都由版本更新保持最新。
* 在具有易受攻击依赖项的锁文件中定义的所有依赖项都由安全更新更新。
使用`ignore`时Dependabot使用以下过程：
1. 检查所有明确**允许**的依赖项。
2. 然后筛选掉所有被**忽略**的依赖项或版本。
如果某个依赖项同时匹配 `allow` 和 `ignore` 语句，则会被**忽略**。
| 参数 | 目的 |
| ----------------- | --------------------------------------------------------------------------------------------------------------------- |
| `dependency-name` | 忽略名称匹配的依赖项的更新，可选使用 `*` 匹配零个或多个字符。 |
| `versions` | 忽略特定版本或版本范围。 |
| `update-types` | 忽略一个或多个语义化版本控制级别的更新。 支持的值：`version-update:semver-patch`、`version-update:semver-minor`和 `version-update:semver-major`。 |
###
```
`dependency-name`（`ignore`）
```
对于大多数包管理器，应定义一个值，使其与锁定文件或清单文件中指定的依赖项名称匹配。 少数系统有更复杂的要求。
| 程序包管理器 | 所需格式 | Example |
| -------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Gradle 和 Maven | `groupId:artifactId` | `org.kohsuke:github-api` |
| 用于映像标签的 Docker | 存储库的全名 | 对于 `.dkr.ecr.us-west-2.amazonaws.com/base/foo/bar/ruby:3.1.0-focal-jemalloc` 的映像标签，请使用 `base/foo/bar/ruby`。 |
###
```
`versions`（`ignore`）
```
用于忽略特定版本或版本范围。 如果要定义范围，请使用包管理器的标准模式。 例如：
* npm：使用 `^1.0.0`
* Bundler：使用 `~> 2.0`
* Docker：使用 Bundler 版本语法
* NuGet：使用 `7.*`
* Maven：使用 `[1.4,)`
有关示例，请参阅“[控制 Dependabot 更新的依赖项](/zh/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#ignoring-specific-versions-or-ranges-of-versions)”。
###
```
`update-types`（`ignore`）
```
指定要忽略的语义化版本 (SemVer)。 SemVer 是定义软件包版本的公认标准，格式为 `x.y.z`。
Dependabot 假定以这种形式的版本始终为 `major.minor.patch`。
* 使用 `version-update:semver-patch` 以包含补丁发布。
* 使用 `version-update:semver-minor` 以包含次要发布。
* 使用 `version-update:semver-major` 以包含主要发布。
##
```
`insecure-external-code-execution`
```
受以下类型支持：`bundler`、`mix` 和 `pip`。
允许 Dependabot 在更新期间在清单中执行外部代码。 有关示例，请参阅[允许外部代码执行](/zh/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configuring-access-to-private-registries-for-dependabot#allowing-external-code-execution)。
```
Dependabot 默认行为：
```
* 授予 Dependabot 对一个或多个注册表的访问权限时，会自动禁用外部代码执行，以保护代码免受包泄露的影响。
* 若无法执行代码，版本更新可能会失败。
当你允许 `insecure-external-code-execution` 时：
* Dependabot 将在清单中执行代码作为版本更新过程的一部分。
* 该代码仅能访问与该`updates`设置关联的注册表中的包管理器。 不允许访问顶级 `registries` 配置中定义的任何注册表。
* 这应能使更新成功，但也可能允许受损包窃取凭据或访问已配置的注册表。
支持的值：`allow`。
##
```
`labels`
```
为针对包管理器提出的所有拉取请求指定自定义标签。 有关示例，请参阅“[自定义 Dependabot 拉取请求以适应你的流程](/zh/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs)”。
```
Dependabot 默认行为：
```
* 所有拉取请求均带有 `dependencies` 标签。
* 如果定义了多个包管理器，每个拉取请求会额外添加一个生态系统或语言标签。 例如：`java` 用于 Gradle 更新，`submodules` 用于 Git 子模块更新。
* 如果存储库中存在语义版本（SemVer）标签，它们将自动应用以指示版本更新的类型（`major`或`minor``patch`）。
* Dependabot 根据需要在存储库中自动创建这些默认标签。
当定义 `labels` 时：
* 指定的标签将替代默认标签。
* 除定义的任何自定义标签外，SemVer 标签（如果存在于存储库中）仍将应用。
* 如果其中任何标签未在仓库中定义，将被忽略。
* 可使用 `labels: [ ]` 禁用所有标签（包括默认标签）。
设置此选项还会影响此包管理器的清单文件安全更新拉取请求，除非使用 `target-branch` 检查非默认分支上的版本更新。
##
```
`milestone`
```
将针对包管理器提出的所有拉取请求与里程碑关联。 有关示例，请参阅“[自定义 Dependabot 拉取请求以适应你的流程](/zh/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs)”。
```
Dependabot 默认行为：
```
* 不使用任何里程碑。
当定义 `milestone` 时：
* 该包管理器的所有拉取请求都会添加到该里程碑。
支持的值：里程碑的数字标识符。
> \[!TIP]
> 如果查看里程碑，则 `milestone` 之后的页面 URL 的最后一部分是标识符。 有关示例 `https://github.com///milestone/3`，请参阅 [查看里程碑的进度](/zh/issues/using-labels-and-milestones-to-track-work/viewing-your-milestones-progress)。
##
```
`multi-ecosystem-groups`
```
定义跨多个包生态系统的组，以获取单个 Dependabot 拉取请求，更新所有受支持的包生态系统。 此方法有助于减少收到的拉取请求数 Dependabot 并简化依赖项更新工作流。
```
Dependabot 默认行为：
```
* 为具有依赖项更新的每个包生态系统创建单独的拉取请求。
使用 `multi-ecosystem-groups` 时：
* 同一组中跨多个包生态系统的更新会被合并到一个拉取请求中。
* 各组拥有独立的计划，可以继承或替代单个生态系统设置。
### `multi-ecosystem-group`
要将单个包生态系统分配到多生态系统组中，可以在 `multi-ecosystem-group` 配置中使用 `updates` 参数。
> \[!IMPORTANT]
> 多生态系统更新需要特定的配置模式，并且具有唯一的参数合并行为。 有关完整的设置说明、配置示例和详细参数参考，请参阅“AUTOTITLE”[](/zh/code-security/tutorials/secure-your-dependencies/configuring-multi-ecosystem-updates)。
```yaml copy
# Basic `dependabot.yml` file defining a multi-ecosystem-group
version: 2
multi-ecosystem-groups:
infrastructure:
schedule:
interval: "weekly"
updates:
- package-ecosystem: "docker"
directory: "/"
patterns: ["nginx", "redis"]
multi-ecosystem-group: "infrastructure"
- package-ecosystem: "terraform"
directory: "/"
patterns: ["aws"]
multi-ecosystem-group: "infrastructure"
```
##
```
`open-pull-requests-limit`
```
更改任何时候可打开的版本更新拉取请求的最大数量限制。
```
Dependabot 默认行为：
```
* 如果有五个版本更新拉取请求处于打开状态，在其中部分请求合并或关闭前，不会再提出新的拉取请求。
* 安全更新有单独的内部限制，最多可打开十个拉取请求，该限制无法更改。
当定义 `open-pull-requests-limit` 时：
* Dependabot 打开的拉取请求数量最多为定义的整数值。 可以设置一个大值，以有效取消打开的拉取请求限制。
* 可以通过将此选项设置为零来暂时禁用包管理器的版本更新，请参阅 [“禁用 Dependabot version updates](/zh/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#disabling-dependabot-version-updates)”。
##
```
`package-ecosystem`
```
```
**必需选项。** 为每个希望 `package-ecosystem` 监视新版本的包管理器定义一个 Dependabot 元素。 存储库还必须包含每个包管理器的依赖项清单或锁定文件，请参阅[示例 `dependabot.yml` 文件](/code-security/dependabot/dependabot-version-updates/configuring-dependabot-version-updates#example-dependabotyml-file)。
```
| 程序包管理器 | YAML 值 | 支持的版本 |
| ------- | --------- | :------: |
| | | |
| 巴泽尔 | `bazel` | v7、v8、v9 |
| | | |
| | | |
| Bun | `bun` | >=v1.2.5 |
| | | |
| Bundler | `bundler` | |
```
v2 |
```
\| Cargo | `cargo` | v1 |
\| Composer | `composer` | v2 |
\| |
\| Conda | `conda` | 不適用 |
\| |
\| 开发容器 | `devcontainers` | 不適用 |
\| Docker | `docker` | v1 |
\| |
\| Docker Compose | `docker-compose` | V2 和 V3 |
\| |
\| |
\| .NET SDK | `dotnet-sdk` | >=.NET Core 3.1 |
\| |
\| |
\| Helm 图表 | `helm` | v3 |
\| |
\| Hex | `mix` | v1 |
\| |
\| Julia | `julia` | >=v1.10 |
\| |
\| elm-package | `elm` | v0.19 |
\| git 子模块 | `gitsubmodule` | 不適用 |
\| GitHub Actions | `github-actions` | 不適用 |
\| Go 模块 | `gomod` | v1 |
\| Gradle | `gradle` | 不適用 |
\| Maven | `maven` | 不適用 |
\| |
\| Nix 碎片 | `nix` | 不適用 |
\| |
\| npm | `npm` | v7、v8、v9、v10 |
\| NuGet | `nuget` |
<=6.12.0 |
\| |
\| OpenTofu | `opentofu` | 不適用 |
\| |
\| pip | `pip` | 24.2 |
\| pip-compile | `pip` | 7.5.3 |
\| pipenv | `pip` | <= 2024.4.1 |
\| pnpm | `npm` | v7、v8
v9、v10（仅版本更新） |
\| poetry | `pip` | v2 |
\| |
\| pre-commit | `pre-commit` | 不適用 |
\| |
\| 酒馆 | `pub` | v2 |
\| |
\| Rust 工具链 | `rust-toolchain` | 不適用 |
\| |
\| Swift | `swift` | v5 |
\| Terraform | `terraform` | >= 0.13，<= 1.10.x |
\| |
\| uv | `uv` | v0 |
\| |
\| |
\| vcpkg | `vcpkg` | 不適用 |
\| |
\| yarn | `npm` | v1、v2、v3、v4 |
##
```
`pull-request-branch-name.separator`
```
指定生成分支名称时使用的分隔符。 有关示例，请参阅“[自定义 Dependabot 拉取请求以适应你的流程](/zh/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs)”。
```
Dependabot 默认行为：
```
* 生成以下格式的分支名称：`dependabot/PACKAGE_MANAGER/DEPENDENCY`
当定义 `pull-request-branch-name.separator` 时：
* 使用指定字符替代 `/`。
支持的值：`"-"`、`_`、`/`
> \[!TIP]
> 连字符必须转义，以免被解释为开始空 YAML 列表。
##
```
`rebase-strategy`
```
禁用 Dependabot 发起的拉取请求的自动变基。
```
Dependabot 默认行为是在 Dependabot 检测到版本或安全更新拉取请求有任何更改时，对打开的拉取请求执行变基。
Dependabot 会在以下情况下检查更改：
```
* 你的计划运行以检查版本更新。
* 您重新打开了已关闭的Dependabot拉取请求。
* 你在 `target-branch` 配置文件中更改的 Dependabot 值，请参阅[`target-branch`](#target-branch-)。
* 最近推送到目标分支后，Dependabot 拉取请求出现冲突。
当 `rebase-strategy` 设置为 `disabled` 时，Dependabot 将停止对拉取请求执行变基。
> \[!NOTE]
> 禁用变基**前**已打开的拉取请求将继续进行变基，直至打开后 30 天。 这会影响所有与目标分支存在冲突的拉取请求以及所有版本更新拉取请求。
##
```
`registries`
```
配置对专用包注册表的访问以允许 Dependabot 更新更广泛的依赖项，请参阅 [为 Dependabot 配置对专用注册表的访问权限](/zh/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configuring-access-to-private-registries-for-dependabot) 和 [针对 Dependabot 的专用注册表配置指南](/zh/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/guidance-for-the-configuration-of-private-registries-for-dependabot)。
```
`dependabot.yml` 文件中有 2 个位置可以使用 `registries` 密钥：
```
1. 在顶层定义要使用的专用注册表及其访问信息，请参阅 [为 Dependabot 配置对专用注册表的访问权限](/zh/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configuring-access-to-private-registries-for-dependabot)。
2. 在 `updates` 块中，可指定每个包管理器应使用的专用注册表。
```
Dependabot 默认行为是仅引发拉取请求，以更新存储在可公开访问的注册表中的依赖项。
Dependabot当配置文件具有顶级`registries`部分（定义对一个或多个专用注册表的访问权限）时，可以将每个`package-ecosystem`注册表配置为使用其中一个或多个专用注册表。
```
当为包管理器定义 `registries` 时：
* 会检查为该包管理器指定的每个专用注册表是否有版本更新和安全更新。
* Dependabot 使用顶级 `registries` 部分中定义的访问详细信息。
支持的值：`REGISTRY_NAME` 或 `"*"`
##
```
`schedule`
**必需选项。** 通过 `interval` 参数定义你配置的每个包管理器检查新版本的频率。 （可选）对于每日和每周间隔，你可自定义 Dependabot 检查更新的时间。 有关示例，请参阅“[AUTOTITLE](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates)”。
```
| 参数 | 目的 |
| ----------------------- | -- |
| [`interval`](#interval) | |
```
**必填。** 为Dependabot定义频率。 |
```
\| [`day`](#day) | 为**每周**间隔指定运行日期。 |
\| [`time`](#time) | 指定运行时间。 |
\| |
\| [`cronjob`](#cronjob) | 如果间隔类型为 `cron`，则定义 cron 表达式。 |
\| |
\| [`timezone`](#timezone) | 指定 `time` 值的时区。 |
### `interval`
支持的值：`daily`、`weekly`、`monthly`、`quarterly`、`semiannually`、`yearly` 或 `cron`
每个包管理器必须定义计划间隔\*\*\*\*。
* 使用 `daily` 在每个工作日（周一至周五）运行。
* 使用 `weekly` 每周运行一次，默认在周一。
* 使用 `monthly` 在每月的第一天运行。
* 使用 `quarterly` 在每个季度（1 月、4 月、7 月和 10 月）的第一天运行。
* 使用 `semiannually` 在 1 月和 7 月的第一天每隔六个月运行一次。
* 使用 `yearly` 在 1 月的第一天运行。
* 对基于 cron 表达式的计划选项使用 `cron` 。 请参阅 [`cronjob`](#cronjob)。
> \[!NOTE]
> 支持的值 `quarterly`、`semiannually` 和 `yearly` 仅在版本 3.19 的 GitHub Enterprise Server 中可用。
默认情况下， Dependabot 随机分配一个时间以应用配置文件中的所有更新。 可以使用 `time` 和 `timezone` 参数为所有间隔设置特定的运行时。\
如果使用间隔 `cron` ，可以使用表达式定义更新时间 `cronjob` 。
### `day`
支持的值：`monday`、`tuesday`、`wednesday`、`thursday`、`friday`、`saturday` 或 `sunday`
（可选）为包管理器在一周的特定日期运行**每周**更新。
### `time`
格式：`hh:mm`
（可选）为包管理器在一天的特定时间运行所有更新。 默认情况下，时间解释为 UTC。
### `cronjob`
支持的值：采用 cron 语法的有效 cron 表达式或自然语言表达式。
计划任务语法有五个字段，中间用空格分隔，每个字段代表一个时间单位。
```text
┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of the month (1 - 31)
│ │ │ ┌───────────── month (1 - 12 or JAN-DEC)
│ │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
│ │ │ │ │
* * * * *
```
示例：`0 9 * * *`、`every day at 5pm`
```
`0 9 * * *` 等同于“每天上午 9 点”。
`every day at 5pm` 等效于 `0 17 * * *`。
```
> \[!NOTE]
>
> * 必须在参数中 [`timezone`](#timezone) 指定时区，而不是在 `cronjob`.
> * 使用 `cronjob` 间隔需要 `cron` 类型计划。
```yaml copy
# Basic `dependabot.yml` file for cronjob
version: 2
updates:
# Enable version updates for npm
- package-ecosystem: "npm"
# Look for `package.json` and `lock` files in the `root` directory
directory: "/"
# Check the npm registry for updates based on `cronjob` value
schedule:
interval: "cron"
cronjob: "0 9 * * *"
```
### `timezone`
指定 `time` 值的时区。 默认时区为 `UTC`。
时区标识符必须与 [iana](https://www.iana.org/time-zones) 维护的数据库中的时区匹配，请参阅 [tz 数据库时区列表](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)。
##
```
`target-branch`
```
定义用于检查版本更新并作为版本更新拉取请求目标的特定分支。 有关示例，请参阅“[自定义 Dependabot 拉取请求以适应你的流程](/zh/code-security/dependabot/dependabot-version-updates/customizing-dependabot-prs)”。
```
Dependabot 默认行为：
```
* Dependabot 使用存储库的默认分支，请参阅 [“关于默认分支](/zh/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches#about-the-default-branch)”。
当定义 `target-branch` 时：
* 仅检查目标分支上的清单文件是否有版本更新。
* 会打开针对指定分支的版本更新的所有拉取请求。
* 为此 `package-ecosystem` 定义的选项不再适用于安全更新，因为安全更新始终使用仓库的默认分支。
##
```
`exclude-paths`
```
用于指定在扫描清单和依赖项时应忽略的目录和文件 Dependabot 的路径。 当你希望阻止特定位置（例如测试资源、供应商代码或特定文件）的依赖项更新时，此选项非常实用。
```
Dependabot 默认行为：
```
* 指定 `directory` 中的所有目录和文件均会包括在更新扫描中，除非通过此选项将其排除。
当定义 `exclude-paths` 时：
* 在针对给定 `package-ecosystem` 条目的更新扫描期间，所有与指定路径匹配的文件和目录都会被忽略。
| 参数 | 目的 |
| --------------- | --------------------- |
| `exclude-paths` | 要忽略的文件或目录的 glob 模式列表。 |
支持 Glob 模式，例如用于递归匹配的 `**` 和单段通配符匹配的 `*`。 模式路径相对于更新配置中指定的 `directory`。 每个生态系统都可以拥有其自己的 `exclude-paths` 设置。
### Example
```yaml copy
version: 2
updates:
- package-ecosystem: "npm"
directory: "/"
schedule:
interval: "daily"
exclude-paths:
- "src/test/assets"
- "vendor/**"
- "src/*.js"
- "src/test/helper.js"
# Sample patterns that can be used-
# Pattern: docs/*.json
# Matches: docs/foo.json, docs/bar.json
# Pattern: *.lock
# Matches: Gemfile.lock, package.lock, foo.lock (in any directory)
# Pattern: test/**
# Matches: test/foo.rb, test/bar/baz.rb, test/any/depth/file.txt
# Pattern: config/settings.yml
# Matches: config/settings.yml
# Pattern: **/*.md
# Matches: README.md, docs/guide.md, any/depth/file.md
# Pattern: src/*
# Matches: src/main.rb, src/app.js
# Does NOT match: src/utils/helper.rb
# Pattern: hidden/.*
# Matches: hidden/.env, hidden/.secret
```
在此示例中，扫描更新时将忽略Dependabot目录、`src/test/assets`目录下的所有文件、直接位于`vendor/`下的所有 JavaScript 文件，以及特定文件`src/`和`src/test/helper.js`。
##
```
`vendor`
```
受以下类型支持：仅 `bundler` 和 `gomod`。
告知 Dependabot 维护你供应商化的依赖项以及清单文件定义的依赖项。 当你将代码存储在存储库中时，该依赖项被称为“vendored 依赖项”或“缓存依赖项”，请参阅 [`bundle cache` 文档](https://bundler.io/man/bundle-cache.1.html)和 [`go mod vendor` 文档](https://golang.org/ref/mod#go-mod-vendor)。
有关示例，请参阅“[控制 Dependabot 更新的依赖项](/zh/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#updating-vendored-dependencies)”。
```
Dependabot 默认行为：
```
* 仅维护为 Bundler 标识的清单文件和锁定文件中记录的依赖项。
* 提出安全更新和版本更新拉取请求，以更新清单文件和锁定文件中记录的版本号。
* 对于 Go 模块，所有 vendored 依赖项都会被自动识别和维护，如同启用了 `vendor` 一样。
启用 `vendor` 时：
* Dependabot 还维护存储在存储库中的 `_vendor/cache_` 目录内的 Bundler 依赖项。
* 拉取请求有时会包含对存储在存储库中的依赖项的更新。
支持的值：`true` 或 `false`
##
```
`versioning-strategy`
```
支持：`bundler`、、、`cargo`、`composer``mix`、`npm`、 `pip``pub`和`uv`
请确定如何使用Dependabot编辑manifest文件。 有关示例，请参阅“[控制 Dependabot 更新的依赖项](/zh/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-a-versioning-strategy)”。
```
Dependabot 默认行为：
```
* 尝试区分应用依赖项和库依赖项。
* 对于应用，始终提高最低版本要求以匹配新版本。 即 `increase` 策略。
* 对于库，尽可能放宽允许的版本要求，以同时包含新旧版本。 即 `widen` 策略。
定义`versioning-strategy`之后，Dependabot 采用指定的策略。
| 价值 | 行为 |
| ----------------------- | ----------------------------------------------------- |
| `auto` | 默认行为。 |
| `increase` | 始终增加最低版本要求以匹配新版本。 如果范围已存在，通常这只会增加下限。 |
| `increase-if-necessary` | 如果版本要求已经允许新的发布，则保持不变（Dependabot 仍更新已解析的版本）。 否则，扩大该要求。 |
| `lockfile-only` | 仅创建用于更新 lockfiles 的拉取请求。 忽略任何需要包清单更改的新版本。 |
| `widen` | 尽可能放宽允许的版本要求，以包括新旧版本。 通常，这只会增加允许的最大版本要求。 |
例如，如果当前版本为 `1.0.0` 且当前约束为 `^1.0.0`，则不同策略会提出以下更新：
新版本 `1.2.0`
* `increase`：新约束 `^1.2.0`
* `increase-if-necessary`：新约束 `^1.0.0`
* `widen`：新约束 `^1.0.0`
新版本 `2.0.0`
* `increase`：新约束 `^2.0.0`
* `increase-if-necessary`：新约束 `^2.0.0`
* `widen`：新约束 `>=1.0.0 <3.0.0`
> \[!NOTE]
> 如果使用的包管理器尚不支持配置 `versioning-strategy` 参数，或者不支持所需的值，则策略代码open source，因此，如果希望特定生态系统支持新策略，则始终欢迎在 中提交拉取请求。
### 版本控制标签
* 代表软件发布生命周期的阶段，例如 alpha、beta 和稳定版本。
* 使发布者能更有效地分发其包。
* 指示版本的稳定性，并告知用户在功能和稳定性方面可预期的内容。
Dependabot 可识别用于不同生态系统的预发行版本、稳定版本的各种版本控制标记以及自定义标记。
```
`dependabot.yml` 文件不控制用户可使用的版本控制标记，用户可在配置选项中定义，例如 [`ignore`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#ignore--) 要忽略其更新的受支持的版本控制标记。
```
#### 支持的版本控制标记
\| **包管理器** | YAML 值\*\*\*\* | 支持的标记\*\*\*\* |
**示例** |
\|---------------------|----------------|--------------------|--------------|
\| Maven | `maven` | `alpha, a, beta, b, milestone, m, rc, cr, sp, ga, final, release, snapshot` |
`spring-security-web@5.6.0-SNAPSHOT`、`spring-core@5.2.0.RELEASE` |
\| npm | `npm` |
`alpha`、`beta`、`canary`、`dev`、`experimental`、`latest`、`legacy`、`next`、`nightly`、`rc`、`release`、`stable` |
`lodash@beta`、`react@latest`、`express@next` |
\| pnpm | `npm` |
`alpha`、`beta`、`canary`、`dev`、`experimental`、`latest`、`legacy`、`next`、`nightly`、`rc`、`release`、`stable` |
`lodash@1.2.0-alpha`、`react@alpha`、`vue@next` |
\| yarn | `npm` |
`alpha`、`beta`、`canary`、`dev`、`experimental`、`latest`、`legacy`、`next`、`nightly`、`rc`、`release`、`stable` |
`lodash@1.2.0-alpha`、`axios@latest`、`moment@nightly` |
#### 版本控制标签术语表
***
```
`alpha`：** 早期版本，可能不稳定且功能不完整。
```
***
```
`beta`：** 比 alpha 更稳定，但可能仍存在 bug。
```
***
```
`canary`：** 定期更新的预发布测试版本。
```
***
```
`dev`：** 代表开发版本。
```
***
```
`experimental`：** 包含实验性功能的版本。
```
***
```
`latest`：** 最新稳定版本。
```
***
```
`legacy`：** 较旧或已弃用的版本。
```
***
```
`next`：** 即将发布的版本。
```
***
```
`nightly`：** 夜间构建版本；通常包含最新更改。
```
***
```
`rc`：** 候选发布版本，接近稳定版本。
```
***
```
`release`：** 正式发布版本。
```
***
```
`stable`：** 最可靠、可用于生产环境的版本。
```
## 顶层 `registries` 密钥
指定 Dependabot 可以使用的身份验证详细信息，以访问专用包注册表，包括 GitLab 或 Bitbucket 托管的注册表。
```
`registries` 项的值是一个关联阵列，其中每个元素由一个标识特定注册表的键和一个为关联阵列的值组成，该值指定访问该注册表所需的设置。 以下 `dependabot.yml` 文件在文件的 `dockerhub` 部分配置一个标识为 `registries` 的注册表，然后在文件的 `updates` 部分中引用该注册表。
```
```yaml copy
# Minimal settings to update dependencies stored 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`。
| 参数 | 用途 |
| :-------------- | :----------------------------------------------------------------------------------- |
| `REGISTRY_NAME` | **必需：** 定义注册表的标识符。 |
| `type` | **必需：** 确定注册表的类型。 |
| 身份验证详细信息 | **必需：** 提供身份验证详细信息所支持的参数因不同类型的注册表而异。 |
| `url` | **必需：** 用于访问此注册表中的依赖项的 URL。 协议是可选的。 如果未指定，则假定为 `https://`。 Dependabot 根据需要添加或忽略尾随斜线。 |
| `replaces-base` | 如果布尔值为 `true`，Dependabot 会使用指定的 `url` 而不是该生态系统的基 URL 来解析依赖项。 |
有关可用选项的详细信息，以及配置专用注册表时的建议，请参阅“[针对 Dependabot 的专用注册表配置指南](/zh/code-security/dependabot/working-with-dependabot/guidance-for-the-configuration-of-private-registries-for-dependabot)”。
###
```
`type` 和身份验证详情
```
用于提供访问专用注册表的身份验证详情的参数因注册表 `type` 而异。
| 注册表 `type` | 必需的身份验证参数 |
| --------------------- | --------- |
| `cargo-registry` | `token` |
| `composer-repository` | |
```
`username` 和 `password`
或 OIDC 以及 `tenant-id` 和 `client-id` |
```
\| `docker-registry` |
`username` 和 `password`
或 OIDC 以及 `tenant-id` 和 `client-id` |
\| `git` |
`username` 和 `password`
或 OIDC 以及 `tenant-id` 和 `client-id` |
\| `hex-organization` |
`organization` 和 `key` |
\| `hex-repository` |
`repo` 和 `auth-key` 以及相应的 `public-key-fingerprint`（可选） |
\| `maven-repository` |
`username` 和 `password`
或 OIDC 以及 `tenant-id` 和 `client-id` |
\| `npm-registry` |
`username` 和 `password`
或 `token`
或 OIDC 以及 `tenant-id` 和 `client-id` |
\| `nuget-feed` |
`username` 和 `password`
或 `token`
或 OIDC 以及 `tenant-id` 和 `client-id` |
\| `pub-registry` | `token` |
\| `python-index` |
`username` 和 `password`
或 `token`
或 OIDC 以及 `tenant-id` 和 `client-id` |
\| `rubygems-server` |
`username` 和 `password`
或 `token`
或 OIDC 以及 `tenant-id` 和 `client-id` |
\| `terraform-registry` | `token` |
所有用于身份验证的敏感数据都应安全存储，并从该安全位置引用，请参阅 [为 Dependabot 配置对专用注册表的访问权限](/zh/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configuring-access-to-private-registries-for-dependabot)。
> \[!TIP]
> 如果帐户是 GitHub 帐户，则可以使用 GitHub personal access token 代替密码。
有关 Dependabot 的 OIDC 支持的详细信息，请参阅 [OpenID Connect](/zh/actions/concepts/security/openid-connect#oidc-support-for-dependabot) 和 [为 Dependabot 配置对专用注册表的访问权限](/zh/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/configuring-access-to-private-registries-for-dependabot#using-oidc-for-authentication)。
###
```
`url` 和 `replaces-base`
`url` 参数定义了访问注册表的位置。 启用 `replaces-base` 参数（可选）时，`true` 使用 Dependabot 的值来解析依赖项，而不是使用该特定生态系统的基 URL。
```