Dependabot 配置与管理

概述

Dependabot 是 GitHub 内置的依赖管理工具，具有三大核心功能：

1. Dependabot 警报 — 当依赖项存在已知漏洞（CVE）时发出通知
2. Dependabot 安全更新 — 自动创建拉取请求以修复存在漏洞的依赖项
3. Dependabot 版本更新 — 自动创建拉取请求以使依赖项保持最新

所有配置都位于默认分支上的单个文件中：.github/dependabot.yml。GitHub 不支持每个仓库有多个 dependabot.yml 文件。

配置工作流程

在创建或优化 dependabot.yml 时，请遵循以下流程：

步骤 1：检测所有生态系统

扫描仓库以查找依赖清单。查找：

注意：pnpm 和 yarn 都使用 npm 生态系统值。

步骤 2：映射目录位置

对于每个生态系统，确定清单文件所在的位置。对 monorepo 使用带有 glob 模式的 directories（复数）：

directories:
  - "/"           # 根目录
  - "/apps/*"     # 所有应用子目录
  - "/packages/*" # 所有包子目录
  - "/lib-*"      # 以 lib- 开头的目录
  - "**/*"        # 递归（所有子目录）

重要提示：directory（单数）不支持 glob 模式。使用 directories（复数）来处理通配符。

步骤 3：配置每个生态系统条目

每个条目至少需要：

- package-ecosystem: "npm"
  directory: "/"
  schedule:
    interval: "weekly"

步骤 4：使用分组、标签和调度进行优化

请参阅下文各部分了解每种优化技术。

Monorepo 策略

用于工作区覆盖的 Glob 模式

对于包含许多包的 monorepo，使用 glob 模式来避免列出每个目录：

- package-ecosystem: "npm"
  directories:
    - "/"
    - "/apps/*"
    - "/packages/*"
    - "/services/*"
  schedule:
    interval: "weekly"

跨目录分组

使用 group-by: dependency-name 在多个目录中更新相同的依赖项时创建单个拉取请求：

groups:
  monorepo-deps:
    group-by: dependency-name

这会在所有指定目录中为每个依赖项创建一个拉取请求，从而减少 CI 成本和审查负担。

限制：

• 所有目录必须使用相同的包生态系统
• 仅适用于版本更新
• 不兼容的版本约束会创建单独的拉取请求

工作区之外的独立包

如果某个目录有自己的锁文件且不属于工作区（例如，.github/ 中的脚本），请为其创建一个单独的生态系统条目。

依赖项分组

通过将相关依赖项分组到单个拉取请求中来减少拉取请求噪音。

按依赖类型分组

groups:
  dev-dependencies:
    dependency-type: "development"
    update-types: ["minor", "patch"]
  production-dependencies:
    dependency-type: "production"
    update-types: ["minor", "patch"]

按名称模式分组

groups:
  angular:
    patterns: ["@angular*"]
    update-types: ["minor", "patch"]
  testing:
    patterns: ["jest*", "@testing-library*", "ts-jest"]

针对安全更新

groups:
  security-patches:
    applies-to: security-updates
    patterns: ["*"]
    update-types: ["patch", "minor"]

关键行为：

• 匹配多个组的依赖项将进入第一个匹配的组
• applies-to 在未指定时默认为 version-updates
• 未分组的依赖项会获得单独的拉取请求

多生态系统分组

将来自不同包生态系统的更新合并到一个拉取请求中：

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"
    labels: ["infrastructure", "dependencies"]

updates:
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis"]
    multi-ecosystem-group: "infrastructure"

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

使用 multi-ecosystem-group 时，patterns 键是必需的。

拉取请求自定义

标签

labels:
  - "dependencies"
  - "npm"

设置 labels: [] 可禁用包括默认标签在内的所有标签。如果仓库中存在语义化版本标签（major、minor、patch），则会始终应用这些标签。

提交消息

commit-message:
  prefix: "deps"
  prefix-development: "deps-dev"
  include: "scope"  # 在前缀后添加 deps/deps-dev 作用域

指派人和里程碑

assignees: ["security-team-lead"]
milestone: 4  # 来自里程碑 URL 的数字 ID

分支名称分隔符

pull-request-branch-name:
  separator: "-"  # 默认为 /

目标分支

target-branch: "develop"  # 拉取请求目标分支，而非默认分支

注意：设置 target-branch 时，安全更新仍以默认分支为目标；所有生态系统配置仅适用于版本更新。

调度优化

时间间隔

支持的值：daily、weekly、monthly、quarterly、semiannually、yearly、cron

schedule:
  interval: "weekly"
  day: "monday"         # 仅适用于 weekly
  time: "09:00"         # HH:MM 格式
  timezone: "America/New_York"

Cron 表达式

schedule:
  interval: "cron"
  cronjob: "0 9 * * 1"  # 每周一上午 9 点

冷却期

推迟新发布版本的更新，以避免早期采用者问题：

cooldown:
  default-days: 5
  semver-major-days: 30
  semver-minor-days: 7
  semver-patch-days: 3
  include: ["*"]
  exclude: ["critical-lib"]

冷却期仅适用于版本更新，不适用于安全更新。

安全更新配置

通过仓库设置启用

设置 → 高级安全 → 启用 Dependabot 警报、安全更新和分组安全更新。

在 YAML 中对安全更新进行分组

groups:
  security-patches:
    applies-to: security-updates
    patterns: ["*"]
    update-types: ["patch", "minor"]

禁用版本更新（仅安全更新）

open-pull-requests-limit: 0  # 禁用版本更新拉取请求

自动分类规则

GitHub 预设会自动忽略针对开发依赖项的低影响警报。自定义规则可以按严重性、包名称、CWE 等进行过滤。在仓库设置 → 高级安全中配置。

拉取请求评论命令

使用 @dependabot 评论与 Dependabot 拉取请求进行交互。

注意： 截至 2026 年 1 月，合并/关闭/重新打开命令已被弃用。
请改用 GitHub 的原生 UI、CLI（gh pr merge）或自动合并。

对于分组拉取请求，还有额外的命令：

• @dependabot ignore DEPENDENCY_NAME — 忽略组中的特定依赖项
• @dependabot unignore DEPENDENCY_NAME — 清除忽略，使用更新重新打开
• @dependabot unignore * — 清除组中所有依赖项的所有忽略
• @dependabot show DEPENDENCY_NAME ignore conditions — 显示当前忽略条件

有关完整的命令参考，请参阅 references/pr-commands.md。

忽略和允许规则

忽略特定依赖项

ignore:
  - dependency-name: "lodash"
  - dependency-name: "@types/node"
    update-types: ["version-update:semver-patch"]
  - dependency-name: "express"
    versions: ["5.x"]

仅允许特定类型

allow:
  - dependency-type: "production"
  - dependency-name: "express"

规则：如果依赖项同时匹配 allow 和 ignore，则会被忽略。

排除路径

exclude-paths:
  - "vendor/**"
  - "test/fixtures/**"

高级选项

版本控制策略

控制 Dependabot 如何编辑版本约束：

变基策略

rebase-strategy: "disabled"  # 停止自动变基

通过在提交消息中包含 [dependabot skip] 来允许在额外提交之上进行变基。

开放拉取请求数量限制

open-pull-requests-limit: 10  # 默认为 5（版本更新），10（安全更新）

设置为 0 可完全禁用版本更新。

私有注册表

registries:
  npm-private:
    type: npm-registry
    url: https://npm.example.com
    token: ${{secrets.NPM_TOKEN}}

updates:
  - package-ecosystem: "npm"
    directory: "/"
    registries:
      - npm-private

常见问题

我可以有多个 dependabot.yml 文件吗？
不可以。GitHub 只支持一个位于 .github/dependabot.yml 的文件。在该文件中使用多个 updates 条目来处理不同的生态系统和目录。

Dependabot 支持 pnpm 吗？
支持。使用 package-ecosystem: "npm" — Dependabot 会自动检测 pnpm-lock.yaml。

如何减少 monorepo 中的拉取请求噪音？
使用 groups 批量处理更新，使用带 glob 模式的 directories 实现覆盖，以及使用 group-by: dependency-name 进行跨目录分组。对于低优先级的生态系统，考虑使用 monthly 或 quarterly 间隔。

如何处理工作区之外的依赖项？
为其创建一个单独的生态系统条目，其中 directory 指向该位置。

参考资料

• references/dependabot-yml-reference.md — 完整的 YAML 选项参考
• references/pr-commands.md — 完整的拉取请求评论命令参考
• references/example-configs.md — 真实世界配置示例