dependabot

Dependabot 配置与管理

概述

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

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

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

配置工作流

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

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

扫描仓库中的依赖清单文件。查找：

生态系统	YAML 值	清单文件
npm/pnpm/yarn	npm	package.json、package-lock.json、pnpm-lock.yaml、yarn.lock
pip/pipenv/poetry	pip	requirements.txt、Pipfile、pyproject.toml、setup.py
uv	uv	pyproject.toml、uv.lock
Docker	docker	Dockerfile
Docker Compose	docker-compose	docker-compose.yml
GitHub Actions	github-actions	.github/workflows/*.yml
Go modules	gomod	go.mod
Bundler (Ruby)	bundler	Gemfile
Cargo (Rust)	cargo	Cargo.toml
Composer (PHP)	composer	composer.json
NuGet (.NET)	nuget	*.csproj、packages.config
.NET SDK	dotnet-sdk	global.json
Maven (Java)	maven	pom.xml
Gradle (Java)	gradle	build.gradle
Terraform	terraform	*.tf
OpenTofu	opentofu	*.tf
Helm	helm	Chart.yaml
Hex (Elixir)	mix	mix.exs
Swift	swift	Package.swift
Pub (Dart)	pub	pubspec.yaml
Bun	bun	bun.lockb
Dev Containers	devcontainers	devcontainer.json
Git Submodules	gitsubmodule	.gitmodules
Pre-commit	pre-commit	.pre-commit-config.yaml

说明：

• pnpm 和 yarn 都使用 npm 生态系统值。
• 当存在 uv.lock 时，优先使用 uv 生态系统值；否则使用 pip。

步骤 2：映射目录位置

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

directories:
  - "/"           # root
  - "/apps/*"     # all app subdirs
  - "/packages/*" # all package subdirs
  - "/lib-*"      # dirs starting with lib-
  - "**/*"        # recursive (all subdirs)

重要：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 创建单个 PR：

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

这会为所有指定目录中的每个依赖项创建一个 PR，从而降低 CI 成本并减轻审查负担。

限制：

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

工作区之外的独立包

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

依赖分组

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

按依赖类型

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
• 未分组的依赖项会获得单独的 PR

多生态系统分组

将不同包生态系统的更新合并到单个 PR 中：

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 键是必需的。

PR 自定义

标签

labels:
  - "dependencies"
  - "npm"

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

提交信息

commit-message:
  prefix: "deps"
  prefix-development: "deps-dev"
  include: "scope"  # adds deps/deps-dev scope after prefix

负责人和里程碑

assignees: ["security-team-lead"]
milestone: 4  # numeric ID from milestone URL

分支名分隔符

pull-request-branch-name:
  separator: "-"  # default is /

目标分支

target-branch: "develop"  # PRs target this instead of default branch

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

计划优化

间隔

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

schedule:
  interval: "weekly"
  day: "monday"         # for weekly only
  time: "09:00"         # HH:MM format
  timezone: "America/New_York"

Cron 表达式

schedule:
  interval: "cron"
  cronjob: "0 9 * * 1"  # Every Monday at 9 AM

冷却期

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

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  # disables version update PRs

自动分类规则

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

PR 评论命令

使用 @dependabot 评论与 Dependabot PR 交互。

注意： 自 2026 年 1 月起，merge/close/reopen 命令已弃用。 请改用 GitHub 原生 UI、命令行（gh pr merge）或自动合并。

命令	效果
@dependabot rebase	变基该 PR
@dependabot recreate	从头重新创建该 PR
@dependabot ignore this dependency	关闭并且永不更新此依赖
@dependabot ignore this major version	忽略此主版本
@dependabot ignore this minor version	忽略此次版本
@dependabot ignore this patch version	忽略此补丁版本

对于分组 PR，还有额外命令：

• @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 如何编辑版本约束：

值	行为
auto	默认 — 对应用增加，对库放宽
increase	始终增加最低版本
increase-if-necessary	仅当当前范围排除新版本时才更改
lockfile-only	仅更新锁定文件，忽略清单文件
widen	放宽范围以同时包含旧版本和新版本

变基策略

rebase-strategy: "disabled"  # stop auto-rebasing

在提交信息中包含 [dependabot skip]，以允许在额外提交之上进行变基。

打开的 PR 限制

open-pull-requests-limit: 10  # default is 5 for version, 10 for security

设置为 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 中减少 PR 噪音？ 使用 groups 批量处理更新，使用带 glob 的 directories 来扩大覆盖范围，并使用 group-by: dependency-name 进行跨目录分组。对于低优先级的生态系统，可考虑使用 monthly 或 quarterly 间隔。

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

通过 AI 编码 Agent 进行提交前依赖扫描

若要在提交前于 AI 编码 Agent 内扫描代码变更以发现存在漏洞的依赖项，GitHub MCP Server 的 dependabot 工具集可以对照 GitHub Advisory Database 检查你新增的依赖项，并返回结构化结果，包含受影响的软件包、严重程度以及建议的修复版本。若需要更彻底的提交后检查，它还可以在本地运行 Dependabot CLI，以对比变更前后的依赖关系图。

安装 Advanced Security plugin，它提供专用的依赖扫描工具以及 /dependency-scanning 技能。

GitHub Copilot CLI（shell）：

# Enable the dependabot toolset for the GitHub MCP Server
copilot --add-github-mcp-toolset dependabot

GitHub Copilot CLI（在 copilot 内）：

> /plugin install advanced-security@copilot-plugins

Visual Studio Code：

• 将 "X-MCP-Toolsets": "dependabot" 添加到你的 GitHub MCP Server 请求头中，或在 Copilot Chat 的工具集选择器中选取 Dependabot
• 安装 advanced-security 插件，然后在 Copilot Chat 中使用 /dependency-scanning

示例提示词：

扫描我在这个分支上新增的依赖项，查找已知漏洞，并告诉我提交前应升级到哪些版本。

参见：Advanced Security Plugin — Dependency Scanning Skill

发布于 Dependency scanning with GitHub MCP Server is in public preview（2026 年 5 月）

资源

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