dependabot.yml 文件的配置选项

关于 `dependabot.yml` 文件

Dependabot 配置文件 dependabot.yml 使用 YAML 语法。如果您不熟悉 YAML 并想了解更多信息，请参阅“五分钟学会 YAML”。

您必须将此文件存储在存储库的 .github 目录中的默认分支中。当您添加或更新 dependabot.yml 文件时，这会触发立即检查版本更新。有关更多信息和示例，请参阅“配置 Dependabot 版本更新”。

任何也影响安全更新的选项将在下次安全警报触发针对安全更新的拉取请求时使用。有关更多信息，请参阅“配置 Dependabot 安全更新”。

注意

您无法使用 dependabot.yml 文件配置 Dependabot 警报。

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`			启用具有公共预览级别支持的生态系统
`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，否则为真）并为易受攻击的清单指定 package-ecosystem 和 directory 时，安全更新的拉取请求将使用相关选项。

通常，安全更新使用任何影响拉取请求的配置选项，例如添加元数据或更改其行为。有关安全更新的更多信息，请参阅“配置 Dependabot 安全更新”。

`package-ecosystem`

必需。为每个您希望 Dependabot 监视新版本的包管理器添加一个 package-ecosystem 元素。存储库还必须包含每个这些包管理器的依赖项清单或锁定文件。

如果您希望为支持供应商的包管理器启用供应商功能，则供应商依赖项必须位于所需的目录中。有关更多信息，请参阅下面 vendor 部分。

如果您希望允许 Dependabot 在执行版本更新时访问私有包注册表，则可以在配置文件中包含 registries 设置。有关更多信息，请参阅下面 registries 部分。

包管理器	YAML 值	支持的版本	私有注册表	供应商
Bundler	`bundler`	v2
Cargo	`cargo`	v1
Composer	`composer`	v1, v2
开发容器	`devcontainers`	不适用
Docker	`docker`	v1		不适用
Hex	`mix`	v1
elm-package	`elm`	v0.19
git 子模块	`gitsubmodule`	不适用		不适用
GitHub Actions	`github-actions`	不适用		不适用
Go 模块	`gomod`	v1
Gradle	`gradle`	不适用
Maven	`maven`	不适用
npm	`npm`	v6, v7, v8, v9
NuGet	`nuget`	<=6.12.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	`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 安全更新的生态系统支持的更多信息，另请参阅“依赖关系图支持的包生态系统”。

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 镜像的维护者必须将其 Dockerfile 添加 org.opencontainers.image.source 标签，并包含源存储库的 URL。此外，维护者必须使用与已发布的 Docker 镜像相同的标签标记存储库。例如，请参阅 dependabot-fixtures/docker-with-source 存储库。有关 Docker 标签的更多信息，请参阅 Docker 文档中的扩展镜像标签和 BUILDX_GIT_LABELS。

Dependabot 可以更新 Kubernetes 清单中的 Docker 镜像标签。为包含引用 Docker 镜像标签的 Kubernetes 清单的每个目录的 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 容器注册表 URL。例如，不支持使用 docker:// 语法引用 Docker 容器操作。
Dependabot 支持 GitHub Actions 的公共和私有存储库。有关私有注册表配置选项，请参阅“dependabot.yml 文件的配置选项”中的“git”。

有关将 Dependabot 版本更新与 GitHub Actions 结合使用的更多信息，请参阅“使用 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 使用依赖项的 pom.xml 文件中的信息在更新拉取请求中添加指向发布信息的链接。如果从 pom.xml 文件中省略了信息，则它无法包含在 Dependabot 拉取请求中，请参阅“优化 Java 包以进行 Dependabot 更新”。

对于 Dependabot 安全更新，Gradle 支持仅限于使用依赖项提交 API 手动上传依赖项图数据。有关依赖项提交 API 的更多信息，请参阅“使用依赖项提交 API”。

注意

当您使用依赖项提交 API 将 Gradle 依赖项上传到依赖项图时，所有项目依赖项都会被上传，即使是在任何依赖项文件中未明确提及的传递依赖项也是如此。当在传递依赖项中检测到警报时，Dependabot 无法在存储库中找到易受攻击的依赖项，因此不会为该警报创建安全更新。
但是，当父依赖项在项目的清单文件中明确声明为直接依赖项时，Dependabot 版本更新将创建拉取请求。

Maven

Dependabot 不运行 Maven，但支持更新 pom.xml 文件。

NuGet CLI

Dependabot 不运行 NuGet CLI，但支持大多数功能，直到版本 6.8.0。

pip 和 pip-compile

除了支持更新 requirements.txt 文件外，Dependabot 还支持更新 pyproject.toml 文件（如果它们遵循 PEP 621 标准）。

pub

当 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 及更高版本中的供应商依赖项。

三个包管理器的基本设置示例

# 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"

使用 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"

提示

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 更新应用于多个目录。
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 安全更新触发。有关更多信息，请参阅“关于 Dependabot 版本更新”和“关于 Dependabot 安全更新”。

有时，由于配置错误或不兼容的版本，您可能会看到 Dependabot 运行失败。在 15 次失败运行后，Dependabot 版本更新将跳过后续的计划运行，直到您从依赖关系图手动触发更新检查。Dependabot 安全更新将照常运行。

`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。

dependency-type—用于允许更新特定类型的依赖项。

依赖项类型	受包管理器支持	允许更新
`direct`	所有	所有显式定义的依赖项。
`indirect`	`bundler`、`pip`、`composer`、`cargo`、`gomod`	直接依赖项的依赖项（也称为子依赖项或瞬态依赖项）。
`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 版本更新和 Dependabot 安全更新进行分组。

注意

如果 Dependabot 版本更新的分组拉取请求包含易受攻击的包，Dependabot 安全更新仍将尝试创建单独的拉取请求以将易受攻击的包更新到安全版本。为安全更新创建单独的拉取请求可确保您能够了解包漏洞。

默认情况下，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

具有自定义 Bundler 配置的 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 文件已配置，以便将与模式 @angular* 匹配的任何包（其中最高可解析版本为 minor 或 patch）组合在一起。对于任何与模式不匹配或未更新到 minor 或 patch 版本的包，Dependabot 将创建一个单独的拉取请求。由于使用了 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 条件来排除对 @angular* 包的 major 版本的更新。指定了两条分组规则，一条用于版本更新，另一条用于安全更新。

# `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 更新应用于多个目录。
dependabot.yml 文件中的 groups 选项创建 Dependabot 要放在同一单个拉取请求中的依赖项集（每个包管理器）。

如果您希望在存储库中同时使用这两个功能，则需要使用上面描述的两个键独立且明确地启用这些功能。有关多目录支持的更多信息，请参阅“directories”。

`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 版本更新。

但是，如果 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 会自动防止外部代码执行，在这种情况下，版本更新可能会失败。您可以选择覆盖此行为并允许 bundler、mix 和 pip 包管理器执行外部代码，方法是将 insecure-external-code-execution 设置为 allow。

# 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"

您可以明确拒绝外部代码执行，无论此更新配置是否具有 registries 设置，方法是将 insecure-external-code-execution 设置为 deny。

`labels`

默认情况下，Dependabot 会为所有拉取请求添加 `dependencies` 标签。如果定义了多个包管理器，Dependabot 会在每个拉取请求上添加额外的标签。这指示了拉取请求将更新哪个语言或生态系统，例如：Gradle 更新使用 `java` 标签，git 子模块更新使用 `submodules` 标签。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` 可以将包管理器触发的所有拉取请求与里程碑关联。您需要指定里程碑的数字标识符，而不是其标签。如果您查看某个里程碑，页面 URL 的最后部分（在 `milestone` 之后）就是标识符。例如：`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` 可以更改此限制。这还提供了一种简单的方法来临时禁用包管理器的版本更新。

此选项对安全更新没有影响，安全更新有单独的内部限制，最多可打开十个拉取请求。

# 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 打开的拉取请求。使用 `rebase-strategy` 可以禁用此行为。

注意

如果拉取请求在 30 天内未合并，Dependabot 将停止 rebase 该拉取请求。您仍然可以手动 rebase 并合并拉取请求。

可用的 rebase 策略

auto 使用默认行为，并在检测到更改时 rebase 打开的拉取请求。
disabled 禁用自动 rebase。

当 `rebase-strategy` 设置为 `auto` 时，Dependabot 会在以下情况下尝试 rebase 拉取请求。

当您使用 Dependabot 版本更新时，对于任何打开的 Dependabot 拉取请求，当您的计划运行时。
当您重新打开已关闭的 Dependabot 拉取请求时。
当您更改 Dependabot 配置文件中的 `target-branch` 值时。有关此字段的更多信息，请参阅“target-branch”。
当 Dependabot 检测到在最近向目标分支推送后，Dependabot 拉取请求存在冲突时。

当 `rebase-strategy` 设置为 `disabled` 时，Dependabot 会停止 rebase 拉取请求。

注意

此行为仅适用于与目标分支发生冲突的拉取请求。Dependabot 将继续 rebase 在更改 `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` 文件中，您可以使用 `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` 可以为包管理器触发的所有拉取请求指定单个审阅者或审阅者团队。您必须使用完整的团队名称，包括组织，就像您要 @提及团队一样。

设置此选项也将影响对该包管理器清单文件的安全更新的拉取请求，除非您使用 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 维护的时区数据库。有关更多信息，请参阅时区数据库时区列表。

# 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 在更新依赖项时对其进行 vendor 化。如果您使用的是 `gomod`，请不要使用此选项，因为 Dependabot 会自动检测此工具的 vendor 化。

# 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 仅更新存储库中特定目录中的 vendor 化依赖项。

包管理器	vendor 化依赖项所需的文件路径	更多信息
`bundler`	依赖项必须位于 `vendor/cache` 目录中。不支持其他文件路径。	`bundle cache` 文档
`gomod`	没有路径要求（依赖项通常位于 `vendor` 目录中）	`go mod vendor` 文档

`versioning-strategy`

当 Dependabot 编辑清单文件以更新版本时，有几种不同的潜在版本控制策略

选项	操作
`auto`	尝试区分应用程序和库。对应用程序使用 `increase`，对库使用 `widen`。
`increase`	始终将最低版本要求增加到与新版本匹配。如果已存在范围，则通常仅增加下限。
`increase-if-necessary`	如果原始约束允许新版本，则保留约束，否则，提高约束。
`lockfile-only`	仅创建更新锁定文件的拉取请求。忽略任何需要更改包清单的新版本。
`widen`	尽可能扩大允许的版本要求，以包括新版本和旧版本。通常，这只会增加允许的最大版本要求。
N/A	某些包管理器尚不支持配置 `versioning-strategy` 参数。

下表显示了如何使用 `versioning-strategy` 的示例。

当前约束	当前版本	新版本	策略	新约束
^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`	N/A	N/A
`github-actions`	N/A	N/A
`gitsubmodule`	N/A	N/A
`gomod`	N/A	N/A
`gradle`	N/A	N/A
`maven`	N/A	N/A
`mix`	`auto`、`lockfile-only`	`auto`
`npm`	`auto`、`increase`、`increase-if-necessary`、`lockfile-only`、`widen`	`auto`
`nuget`	N/A	N/A
`pip`	`auto`、`increase`、`increase-if-necessary`、`lockfile-only`	`auto`
`pub`	`auto`、`increase`、`increase-if-necessary`、`widen`	`auto`
`terraform`	N/A	N/A

注意

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

版本控制标签

表示软件发布生命周期中的阶段，例如 alpha、beta 和稳定版本。
允许发布者更有效地分发其软件包。
指示版本的稳定性，并传达用户在功能和稳定性方面应该期望什么。

Dependabot 识别各种预发布版本、稳定版本和自定义标签的版本控制标签，这些标签遍布不同的生态系统。

dependabot.yml 文件不控制您可以使用的版本控制标签，但您可以在配置选项（例如 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 更稳定，但可能仍然存在错误。
canary：定期更新的预发布版本，用于测试。
dev：表示开发版本。
experimental：具有实验性功能的版本。
latest：最新的稳定版本。
legacy：较旧或已弃用的版本。
next：即将发布的版本。
nightly：每晚构建的版本；通常包含最新的更改。
rc：候选版本，接近稳定版本。
release：正式发布版本。
stable：最可靠的、可用于生产环境的版本。

私有注册表的配置选项

顶层 `registries` 键是可选的。它允许您指定 Dependabot 可以用来访问私有包注册表的身份验证详细信息。

您可以通过指定类型为 git 来授予 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 个人访问令牌代替密码。
`key`	对包含此注册表访问密钥的 Dependabot 密钥的引用。有关更多信息，请参阅“为 Dependabot 配置对私有注册表的访问。”
`token`	对包含此注册表访问令牌的 Dependabot 密钥的引用。有关更多信息，请参阅“为 Dependabot 配置对私有注册表的访问。” `token` 用于提供外部系统的访问令牌，不应将其用于提供 GitHub 个人访问令牌。如果要使用 GitHub 个人访问令牌，则应将其作为密码提供。
`replaces-base`	对于注册表，如果布尔值为 `true`，则 Dependabot 将通过使用指定的 URL 而不是该特定生态系统的基本 URL 来解析依赖项。例如，对于 `type: python-index` 的注册表，如果布尔值为 `true`，则 pip 将通过使用指定的 URL 而不是 Python 包索引的基本 URL（默认情况下为 `https://pypi.ac.cn/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 个人访问令牌代替密码。

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 个人访问令牌代替密码。

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 个人访问令牌代替密码。

registries:
  github-octocat:
    type: git
    url: https://github.com
    username: x-access-token
    password: ${{secrets.MY_GITHUB_PERSONAL_TOKEN}}

`hex-organization`

hex-organization 类型支持组织和密钥。

registries:
  github-hex-org:
    type: hex-organization
    organization: github
    key: ${{secrets.MY_HEX_ORGANIZATION_KEY}}

`hex-repository`

hex-repository 类型支持身份验证密钥。

repo 是必需字段，必须与依赖项声明中使用的存储库名称匹配。

public-key-fingerprint 是一个可选的配置字段，表示 Hex 存储库的公钥指纹。public-key-fingerprint 用于 Hex 建立与私有存储库的信任关系。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 个人访问令牌代替密码。

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 个人访问令牌代替密码。

使用用户名和密码时，您的 .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 个人访问令牌代替密码。

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 个人访问令牌代替密码。

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 个人访问令牌代替密码。

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

启用对公共预览级生态系统的支持

`enable-beta-ecosystems`

默认情况下，Dependabot 仅更新完全支持的生态系统的依赖项清单和锁定文件。使用 enable-beta-ecosystems 标志选择加入尚未普遍提供的生态系统的更新。

目前没有公共预览中的生态系统。

# Configure public preview ecosystem

version: 2
enable-beta-ecosystems: true
updates:
  - package-ecosystem: "beta-ecosystem"
    directory: "/"
    schedule:
      interval: "weekly"

谁可以使用此功能？

本文内容