自定义 Dependabot 拉取请求以适应你的流程

了解如何定制你的 Dependabot 拉取请求以更好地适应你自己的内部工作流。

谁可以使用此功能？

Users with write access

在本文中

可通过多种方式自定义 Dependabot 拉取请求，以便它们更适合自己的内部进程。

例如，若要将拉取请求集成到 DependabotCI/CD 管道中，它可以将 自定义标签 应用于拉取请求，然后可以使用拉取请求来触发操作工作流。

可以组合使用几种不同的自定义选项，并根据包生态系统进行定制。

自动添加被分派人

默认情况下，Dependabot 创建拉取请求时不会指定任何受理人。

若要自动将拉取请求分配给指定的安全团队，可以使用 assignees 为每个包生态系统设置这些值。

下面的示例 dependabot.yml 文件更改了 npm 配置，使所有因版本更新和安全更新而打开的拉取请求都具有：

  • 自动分配给拉取请求的个人（“user-name”）。
YAML
# `dependabot.yml` file with
#  assignee for all npm pull requests

version: 2
updates:
  # Keep npm dependencies up to date
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # Raise all npm pull requests with assignees
    assignees:
      - "user-name"

自动添加审阅者

默认情况下， Dependabot 在没有任何审阅者的情况下引发拉取请求。

为了确保项目的安全更新能够由相应团队及时处理，可以使用 CODEOWNERS 文件自动为 Dependabot 拉取请求添加审阅者。 请参阅“关于代码所有者”。

使用自定义标签标记拉取请求

默认情况下，Dependabot 创建带有 dependencies 标签的拉取请求。

Dependabot 还会为拉取请求添加生态系统标签，例如 java、npm 或 github-actions。 Dependabot 会将 dependencies 标签和生态系统标签添加到所有拉取请求（包括单生态系统更新）以改进筛选和会审。

Dependabot 创建它应用于拉取请求的默认标签（如果存储库中尚不存在）。 如果要使用自定义标签而不是默认值，可以在每个包生态系统的文件中labels设置dependabot.yml选项;这将替代默认值。 有关详细信息，请参阅 管理标签 和 labels。

如果存储库中存在语义版本（SemVer）标签，Dependabot则也会自动应用它们来指示版本更新的类型（major或minor``patch）。 除了您定义的任何自定义标签外，还会应用这些标签。

可以使用 labels 替代默认标签，并为每个包生态系统指定自己的自定义标签。 例如，如果你想要执行以下操作，这将非常有用：

  • 使用标签将优先级分配给某些拉取请求。
  • 使用标签触发另一个工作流，例如自动将拉取请求添加到项目板上。

下面的示例 dependabot.yml 文件更改了 npm 配置，使所有针对 npm 的版本和安全更新打开的拉取请求都具有自定义标签。

YAML
# `dependabot.yml` file with
# customized npm configuration

version: 2
updates:
  # Keep npm dependencies up to date
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # Raise all npm pull requests with custom labels
    labels:
      - "npm dependencies"
      - "triage-board"

设置此选项还会影响此包管理器的清单文件安全更新拉取请求，除非使用 target-branch 检查非默认分支上的版本更新。

另请参阅labels。

为提交消息添加前缀

默认情况下， Dependabot 尝试检测提交消息首选项并使用类似的模式。 此外， Dependabot 根据提交消息填充拉取请求的标题。

您可以针对特定的软件包生态系统，为 Dependabot 的提交消息（以及拉取请求标题）指定自定义前缀。 例如，如果您正在运行处理提交消息或拉取请求标题的自动化程序，这可能会非常有用。

若要显式指定首选项，请将 commit-message 与以下受支持的选项一起使用：

  • prefix:
    • 指定所有提交消息的前缀。
    • 前缀也会添加到 pull request 标题的开头。
  • prefix-development:
    • 为更新开发依赖项的所有提交消息指定单独的前缀，由包管理器或生态系统定义。
    • 支持 bundler、composer、mix、maven、npm 和 pip。
  • include: "scope":
    • 指定任何前缀都后跟提交中更新的依赖项类型（deps 或 deps-dev）。

下面的示例展示了根据包生态系统定制的几个不同的选项：

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

设置此选项还会影响此包管理器的清单文件安全更新拉取请求，除非使用 target-branch 检查非默认分支上的版本更新。

另请参阅commit-message。

将拉取请求与里程碑关联

里程碑可帮助你跟踪拉取请求（或问题）组实现项目目标或发布的进度。 借助 Dependabot，您可以使用 milestone 选项将依赖项更新的拉取请求关联到特定里程碑。

必须指定里程碑的数字标识符，而不是其标签。 若要查找数字标识符，请查看页面 URL 的最后一部分，在 milestone 之后。 例如，对于 https://github.com/<org>/<repo>/milestone/3，“3”即是里程碑的数字标识符。

YAML
# Specify a milestone for pull requests

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # Associate pull requests with milestone "4"
    milestone: 4

设置此选项还会影响此包管理器的清单文件安全更新拉取请求，除非使用 target-branch 检查非默认分支上的版本更新。

另请参阅“milestone”和“关于里程碑”。

自定义拉取请求分支名称

Dependabot 为每个拉取请求创建一个分支。 每个分支名称都包括 dependabot，以及要更新的包管理器和依赖项的名称。 默认情况下，分支名称的这些部分由 / 符号分隔，例如：

  • dependabot/npm_and_yarn/next_js/acorn-6.4.1

可以使用具有以下pull-request-branch-name参数的选项自定义分支名称：separator、、prefix、max-length``word-separator、和branch-name-case``template。 所有选项都是可组合的，你可以组合其中任何选项。 有关每个参数的完整参考，请参阅 pull-request-branch-name。

组合格式选项

可以合并separator、word-separator、branch-name-case生成max-length``template满足系统要求的分支名称。 例如，Docker 标记兼容性、Azure 容器注册表命名或 Kubernetes 分支长度限制。

当 template 与其他选项一起设置时，格式化会在模板渲染后作为后处理按以下顺序应用：分隔符替换、词分隔符替换、大小写转换，然后是最大长度截断。

YAML
# Combine template with formatting options

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      template: "{prefix}/{package_manager}/{dependency}-{version}"
      separator: "-"
      word-separator: "-"
      branch-name-case: "lowercase"
      max-length: 80
  • 之前 （默认值）： dependabot/npm_and_yarn/Lodash-4.17.21
  • 采用上述配置后：dependabot-npm-and-yarn-lodash-4.17.21

分支名称超出 max-length时，会用哈希后缀截断该名称以保留唯一性。

包含多生态系统组的完整示例

下面 dependabot.yml 演示了不同生态系统的所有可用选项，包括多生态系统组配置：

YAML
# Full example demonstrating all branch name options

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      template: "{prefix}/infra/{name}"
      word-separator: "-"
      branch-name-case: "lowercase"

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      separator: "-"
      word-separator: "-"
      branch-name-case: "lowercase"
    groups:
      frontend-deps:
        patterns: ["react*", "next*"]

  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "monthly"
    pull-request-branch-name:
      template: "{prefix}/{package_manager}/{dependency}-{version}"
      max-length: 60

  - package-ecosystem: "pip"
    directory: "/backend"
    schedule:
      interval: "weekly"
    pull-request-branch-name:
      prefix: "deps"
      branch-name-case: "lowercase"
    groups:
      django-deps:
        patterns: ["django*"]

  # These entries participate in the "infrastructure" multi-ecosystem group
  - package-ecosystem: "docker"
    directory: "/infra"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"

  - package-ecosystem: "terraform"
    directory: "/infra"
    patterns: ["hashicorp/*"]
    multi-ecosystem-group: "infrastructure"

此配置生成以下分支名称：

ScenarioStrategy分支名称
lodash 的 npm 更新单独dependabot-npm-and-yarn-lodash-4.17.21
npm frontend-deps 组的更新已分组dependabot-npm-and-yarn-frontend-deps-fc93691fd4
nginx solo Docker 更新单人dependabot/docker/nginx-1.25.0
pip Django 更新单人deps/pip/django-4.2.1
pip django-deps 组的更新分组deps/pip/django-deps-a1b2c3d4e5
跨生态系统基础结构组 （Docker + Terraform）多生态系统dependabot/infra/infrastructure-fc93691fd4

注意

对于多生态系统组： * multi-ecosystem-groups 条目中的 pull-request-branch-name 用于控制分组的跨生态系统 PR 分支名称。

  • 各个指定了multi-ecosystem-groupcannot的updates条目都不能拥有自己的pull-request-branch-name。 组级配置优先，是唯一用于这些条目的配置。

{package_manager} 在多生态系统组模板中不可用，因为该组跨越多个生态系统。

  • 内容摘要始终自动追加到多生态系统组分支，以确保唯一性。

分支名称配置的应用方式

  • 配置按每个更新条目单独设置：每个独立的 package-ecosystem 条目都可以有自己的分支名称配置。 分配给多生态系统组的条目改用组级配置。
  • 现有 PR 不受影响：更改仅适用于新建的 PR。
  • 默认行为保持不变：如果未配置任何选项，则分支名称与当前完全相同。

设置此选项还会影响此包管理器的清单文件安全更新拉取请求，除非使用 target-branch 检查非默认分支上的版本更新。

针对非默认分支的拉取请求

默认情况下，Dependabot 会检查默认分支上的清单文件，并针对默认分支上的更新发起拉取请求。

通常情况下，将 Dependabot 的检查和更新保留在默认分支上是最合理的。 但是，在某些情况下，你可能需要指定不同的目标分支。 例如，如果你们团队的流程要求你先在非生产分支上测试并验证更新，则可以使用 target-branch 为 Dependabot 指定一个不同的分支，以便其针对该分支创建拉取请求。

注意

Dependabot仅针对默认分支引发安全更新的拉取请求。 如果使用 target-branch，那么该包管理器的所有配置设置将仅适用于版本更新，而不适用于安全更新。__

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

另请参阅target-branch。