GitHub Dependabot：自动化依赖更新

第三方依赖是漏洞的主要入口，手动追踪更新既耗时又容易遗漏——Log4Shell 爆发时，不少项目就栽在一个长期没人更新的 log4j 老版本上。

GitHub Dependabot（github.com/apps/dependabot）是 GitHub 原生集成的依赖更新工具，以 Pull Request 形式自动提交更新建议，把安全补丁和版本迭代变成可审查的 PR 流程。

下文覆盖工作原理、dependabot.yml 配置、安全更新、版本更新、实践建议与常见问题。

学习目标

读完本文后，你应该能够：

1. 解释 Dependabot 的 Version Updates 和 Security Updates 两条链路的工作机制
2. 写出一个适合团队规模的 dependabot.yml 配置，包括分组策略和忽略规则
3. 判断什么时候用 Dependabot、什么时候切到 Renovate
4. 为 Dependabot PR 配置 CI 验证流程，确保更新不会引入回归
5. 排查 Dependabot 不工作、PR 过多等常见问题

目录

1. Dependabot 是什么
2. 工作原理详解
3. 完整配置：dependabot.yml
4. Security Updates 进阶配置
5. Version Updates 实践建议
6. 与 CI/CD 流水线的集成
7. 常见问题（FAQ）
8. 替代方案对比
9. 自检清单
10. 参考链接
11. 自测题
12. 练习
13. 进阶路径

1. Dependabot 是什么

Dependabot 是 GitHub 官方维护的自动化依赖更新应用（GitHub App），于 2019 年被 GitHub 收购并深度集成到 GitHub 平台。它能够：

• 监控 项目依赖清单文件（如 package.json、Gemfile、requirements.txt、go.mod 等）
• 检测 可用的新版本和已知安全漏洞
• 自动创建 Pull Request，包含更新说明和 changelog 摘要
• 可选地 自动合并（auto-merge）经过验证的更新

Dependabot 分为两大更新类型：

支持的生态

Dependabot 支持主流包管理器的依赖清单文件：

⚠️ 注意：GitHub Advisory Database 中收录的漏洞才触发 Security Updates。部分小众生态可能仅支持 Version Updates。

2. 工作原理详解

2.1 Version Updates 流程

┌─────────────────────────────────────────────┐
│  Dependabot 引擎（GitHub 云端）             │
│                                             │
│  1. 读取仓库的 dependabot.yml 配置           │
│  2. 按 schedule 扫描依赖清单文件             │
│  3. 查询生态 registry（npm/pypi/etc.）      │
│  4. 检测可用更新版本                         │
│  5. 生成 CHANGELOG 摘要                     │
│  6. 创建 PR（target: 分支，base: main）     │
│  7. 等待 review / auto-merge                │
└─────────────────────────────────────────────┘

关键行为细节：

• 版本解析：遵循语义版本（SemVer）。默认遵循 ">= 1.0.0" 一类的版本约束，但也允许配置 ignore 规则
• 分组策略：可配置 groups 将同一生态的多个依赖合并到一个 PR 中，减少 PR 数量
• 版本上限：可设置 open-pull-requests-limit 控制同时打开的 PR 数量
• 更新范围：支持指定更新的 directory 和 package-ecosystem，便于 monorepo 项目精细控制

2.2 Security Updates 流程

GitHub Advisory Database 发布新漏洞
            │
            ▼
    GitHub 检测哪些仓库受影响
            │
            ▼
    Dependabot 自动创建 Security PR
    （PR 标题包含 🔐 标识）
            │
            ▼
    通知仓库维护者（可通过配置改变通知行为）

Security Updates 在 Dependabot 面板中单独显示为 “Dependabot security updates”，且标签为 dependencies、security 的 PR 会获得特殊处理逻辑。

2.3 Pull Request 内容

每个 Dependabot PR 包含：

1. 更新的版本信息（旧版本 → 新版本）
2. CHANGELOG 片段（从 upstream registry 获取）
3. 依赖的发布说明链接（如有）
4. dependabot-bot 作为贡献者的信息
5. CI 状态（自动运行工作流，可配置）

3. 完整配置：dependabot.yml

将配置文件放在仓库的 .github/dependabot.yml 中（路径固定，不可更改）。

3.1 最小配置

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"

这会每周一次检查项目根目录的 package.json 并创建更新 PR。

3.2 完整生产级配置

# .github/dependabot.yml
version: 2

updates:
  # ── npm: 前端依赖 ──────────────────────────────
  - package-ecosystem: "npm"
    directory: "/frontend"
    schedule:
      interval: "daily"
      time: "09:00"
      timezone: "Asia/Shanghai"
    open-pull-requests-limit: 10
    groups:
      production-dependencies:
        dependency-type: "production"
        update-types:
          - "version-update:semver-major"
      development-dependencies:
        dependency-type: "development"
        update-types:
          - "version-update:semver-minor"
          - "version-update:semver-patch"
    ignore:
      - dependency-name: "lodash"
        versions: ["4.x"]
      - dependency-name: "react"
        update-types: ["version-update:semver-major"]
    commit-message:
      prefix: "deps"
      include: "scope"
    labels:
      - "dependencies"
      - "npm"

  # ── GitHub Actions ──────────────────────────
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    commit-message:
      prefix: "ci"
    labels:
      - "ci"

  # ── Go modules ─────────────────────────────
  - package-ecosystem: "gomod"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      - dependency-name: "golang.org/x/*"
        update-types: ["version-update:semver-major"]
    commit-message:
      prefix: "deps"
    labels:
      - "dependencies"
      - "go"

  # ── Python pip ─────────────────────────────
  - package-ecosystem: "pip"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 5
    commit-message:
      prefix: "py"
    labels:
      - "dependencies"
      - "python"

  # ── Docker 容器镜像 ─────────────────────
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
    labels:
      - "dependencies"
      - "docker"

3.3 配置字段详解

3.4 commit-message 选项

commit-message:
  prefix: "deps"           # 所有 commit 以 "deps:" 开头
  prefix-development: "dev-deps"  # 开发依赖用不同前缀
  include: "scope"        # 包含更新范围，如 "deps: update lodash to 4.17.21"
  # 其他选项：signoff, "scope,signoff"

4. Security Updates 进阶配置

安全更新（Security Updates）和版本更新（Version Updates）是两条独立链路。安全更新针对有已知漏洞的依赖自动创建 PR，开关在仓库设置里，不依赖 dependabot.yml；版本更新则必须由 dependabot.yml 定义生态和目录才能运行。

两者可在同一生态并存：给某个 package-ecosystem 写了配置后，该生态既按计划跑版本更新，也响应安全更新。安全更新不按 schedule 排队，漏洞在 GitHub Advisory Database 收录后即创建 PR。

dependabot.yml 里的大部分选项（labels、reviewers、assignees、commit-message、allow、ignore、groups）对安全更新同样生效，只是应用到下一次安全 PR 创建时。

有两点要分清楚：不能用 dependabot.yml 配置 alerts 本身；安全更新只在能解析到"处于版本范围之内、且已修复"的版本时才会建 PR，否则只会告警、不会动作。

4.1 只开安全更新，不跑常规版本更新

想让"只在有漏洞时收到更新 PR、不做每周例行升级"，直接的做法是不配置常规版本更新的生态条目：

1. 在仓库 Settings → Code security and analysis 开启 Dependabot alerts 和 Dependabot security updates。
2. 不为常规依赖写 dependabot.yml 的 version updates 条目（或只给少数确需跟进的生态配置）。

开关在仓库设置里完成，不需要 YAML。只有想给安全 PR 打标签、分审核人，或约束哪些依赖参与更新，才需要 dependabot.yml：

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "daily"
    # 以下选项同时作用于安全更新 PR
    labels: ["dependencies", "security"]
    open-pull-requests-limit: 3

不要把"只收安全更新"写成 allow 的 update-types: ["security"]——update-types 只接受 version-update:semver-patch、version-update:semver-minor、version-update:semver-major 三种值，security 不是合法取值。限制安全更新，靠的是仓库设置里单独的安全更新开关。

4.2 私有注册表支持

依赖来自私有 npm registry、Python index 或 Docker Registry 时，先在顶层配置 registries 认证，再在对应 updates 条目里引用：

version: 2
registries:
  private-npm:
    type: "npm-registry"
    url: "https://registry.mycompany.com"
    username: "${{ secrets.REGISTRY_USERNAME }}"
    password: "${{ secrets.REGISTRY_PASSWORD }}"
    replaces-base: true   # 替换默认 registry 的 base URL

  private-pypi:
    type: "python-index"
    url: "https://pypi.mycompany.com/simple"
    username: "${{ secrets.PYPI_USERNAME }}"
    password: "${{ secrets.PYPI_PASSWORD }}"

updates:
  - package-ecosystem: "npm"
    directory: "/"
    registries:
      - private-npm
    schedule:
      interval: "weekly"

凭证通过 GitHub 的 secrets 引用，不要把明文写进仓库。

5. Version Updates 实践建议

5.1 分组策略

不给依赖分组时，每一个依赖的更新都会产生一个独立 PR，极端情况下一个中型前端项目可能同时冒出上百个 PR。合理分组是关键：

groups:
  # 生产依赖的大版本更新单独处理（风险更高）
  major-production:
    dependency-type: "production"
    update-types:
      - "version-update:semver-major"
  # 次要版本和 patch 版本打包处理
  minor-patch-production:
    dependency-type: "production"
    update-types:
      - "version-update:semver-minor"
      - "version-update:semver-patch"
  # 开发依赖放一起
  development:
    dependency-type: "development"

5.2 忽略策略

ignore:
  # 完全忽略（永不需要更新）
  - dependency-name: "lodash"
  # 忽略特定版本
  - dependency-name: "axios"
    versions: ["0.21.0"]
  # 忽略某类更新类型
  - dependency-name: "react"
    update-types: ["version-update:semver-major"]  # 手动处理 React 大版本

5.3 自动合并（Auto-Merge）

结合 GitHub branch protection rules 和 Required status checks，实现零干预合并：

步骤 1：开启 Auto-Merge

在 GitHub 仓库设置中：

Settings → General → Allow auto-merge

步骤 2：配置 branch protection rule

Settings → Branches → Add rule
  - Branch name pattern: main
  - Require pull request reviews before merging: ✓
  - Require status checks to pass before merging: ✓
  - Choose required checks: e.g. "test", "lint"
  - Require branches to be up to date before merging: ✓ (可选，建议关闭以避免 CI 队列问题)

步骤 3：配置 dependabot 允许 auto-merge（可选，通过 GitHub API 设置）

# .github/dependabot.yml 中可设置 auto-label-body

实际开启 auto-merge 需要仓库管理员在 PR 界面手动点一次 “Enable auto-merge”，或者通过 GitHub API 设置：

# 通过 GitHub CLI 开启单个 PR 的 auto-merge
gh pr merge --admin --merge
gh api graphql -f query='
mutation {
  enablePullRequestAutoMerge(input: {
    pullRequestId: "xxx"
  }) {
    pullRequest { title }
  }
}'

⚠️ 注意：Auto-merge 前务必确保 CI 流程覆盖了足够的测试。盲目开启会在更新破坏性依赖时造成生产事故。

5.4 使用 allow 精细控制

allow 只能写一次，用多个条目并列（不要重复 allow: 键）。它和 ignore 常常配合使用：

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # 只跟进白名单里的依赖（未列出的一律不更新）
    allow:
      - dependency-name: "lodash"
      - dependency-name: "axios"

按更新级别收窄，用 ignore 更直接（update-types 只接受 version-update:semver-*，没有 security 值）：

updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    ignore:
      - dependency-name: "*"
        update-types: ["version-update:semver-major"]  # 大版本手动处理

6. 与 CI/CD 流水线的集成

6.1 触发条件运行测试

Dependabot PR 触发 CI 后，可针对性运行测试：

# .github/workflows/dependabot-tests.yml
name: Dependabot Tests

on:
  pull_request:
    types: [opened, synchronize, reopened]
  # 仅 Dependabot PR 触发
  schedule:
    - cron: "0 3 * * *"  # 备用：定期测试

jobs:
  test:
    if: ${{ github.actor == 'dependabot[bot]' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npm test

6.2 标签和审核人自动化

通过 Action 自动分配 reviewer 和标签：

# .github/workflows/dependabot-label.yml
name: Dependabot PR Setup

on:
  pull_request:
    types: [opened, ready_for_review]
    branches:
      - main

jobs:
  label:
    if: ${{ github.actor == 'dependabot[bot]' }}
    runs-on: ubuntu-latest
    steps:
      - name: Label PR
        run: |
          gh pr edit ${{ github.event.pull_request.number }} \
            --add-label "dependencies" \
            --add-label "automated-pr"
          gh pr edit ${{ github.event.pull_request.number }} \
            --add-reviewer "team:frontend"

7. 常见问题（FAQ）

Q1: Dependabot 没有工作，如何排查？

排查步骤：

1. 确认 .github/dependabot.yml 文件存在且路径正确（GitHub 只读取这一条固定路径）
2. 检查 GitHub App “Dependabot” 是否已安装到仓库：仓库 Settings → Integrations → Dependabot
3. 查看 Dependabot 面板：Insights → Dependency graph → Dependabot
4. 检查 “Alerts” 是否被安全设置阻止
5. 确认 package-ecosystem 和 directory 与实际清单文件路径匹配

# 验证 YAML 语法（本地测试）
python3 -c "import yaml; yaml.safe_load(open('.github/dependabot.yml'))"

Q2: Dependabot PR 太多，如何减少？

方案：

1. 启用分组策略（groups）合并同一类依赖
2. 将更新频率从 daily 调整为 weekly
3. 设置 open-pull-requests-limit 限制并发 PR 数量
4. 对稳定依赖添加 ignore 规则
5. 用 ignore 忽略 major 大版本更新，只留 patch/minor 自动跟进

Q3: 如何只接收安全更新，不做常规版本更新？

安全更新和版本更新是两套独立开关。只收安全更新，就不要为常规依赖配置版本更新条目：

1. 在仓库设置的 Code security and analysis 里开启 Dependabot alerts 和 Dependabot security updates。
2. 不为常规依赖写 dependabot.yml 的 version updates 条目（或不给对应生态写配置）。

这样只有漏洞触发时才会出现安全更新 PR，不会收到每周例行升级。注意不要用 allow 的 update-types: ["security"] 来做——这是个无效写法。如果确实想给某个生态配置 labels、审核人等，可以在 dependabot.yml 里保留条目，但安全更新的开关始终在仓库设置里。

Q4: 如何更新 GitHub Actions 自身？

- package-ecosystem: "github-actions"
  directory: "/"
  schedule:
    interval: "weekly"
  open-pull-requests-limit: 3

Actions 更新会出现在 Dependabot 面板中，可单独查看。

Q5: 企业私有包注册表如何配置？

registries:
  my-company-registry:
    type: "npm-registry"        # 或 python-index, docker-registry 等
    url: "https://npm.internal.corp"
    username: "${{ secrets.NPM_INTERNAL_USERNAME }}"
    password: "${{ secrets.NPM_INTERNAL_PASSWORD }}"

updates:
  - package-ecosystem: "npm"
    directory: "/"
    registries:
      - my-company-registry
    schedule:
      interval: "weekly"

建议将敏感凭证放在 GitHub Secrets 中，切勿硬编码。

Q6: Dependabot PR 的 CI 失败了怎么办？

1. 检查 CI 日志中失败的原因——可能是更新破坏了 API 兼容性
2. 如确认是 Dependabot 误报，在 PR 中留言 @dependabot ignore 或通过配置 ignore
3. 如更新确实需要代码适配，手动处理该 PR 后关闭 Dependabot 生成的 PR
4. 对于无法合并的 PR，@dependabot close 可关闭之

Q7: monorepo 项目如何配置？

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/packages/core"
    schedule:
      interval: "daily"
  - package-ecosystem: "npm"
    directory: "/packages/web"
    schedule:
      interval: "daily"
  - package-ecosystem: "npm"
    directory: "/packages/mobile"
    schedule:
      interval: "daily"
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"

每个子包独立配置，隔离更新 schedule 和 PR。

Q8: 如何查看 Dependabot 更新历史？

1. GitHub 面板：Insights → Dependency graph → Dependabot
2. GraphQL API：

gh api graphql -f query='
{
  repository(owner: "OWNER", name: "REPO") {
    vulnerabilityAlerts(first: 10) {
      nodes {
        vulnerableManifestFilename
        fixedIn
        securityVulnerability {
          severity
          package { name }
        }
      }
    }
  }
}'

8. 替代方案对比

Renovate vs Dependabot 功能对比

选择建议：

• 快速起步：直接用 Dependabot，功能足够
• 需要更多定制：Renovate 开源版更灵活
• 企业安全合规：Snyk 或 Renovate 企业版
• Monorepo + 自托管：Renovate 是更成熟的选择

9. 自检清单

完成配置后，建议逐一确认以下检查点：

• .github/dependabot.yml 存在且为有效 YAML
• package-ecosystem 与清单文件类型匹配
• directory 指向实际清单文件所在路径
• schedule.interval 设置合理（建议 daily 或 weekly）
• 私有依赖配置了 registries 和对应的 GitHub Secrets
• Security Updates 在仓库设置中已启用（默认启用，但需确认）
• CI 工作流在 Dependabot PR 上运行并有明确的 pass/fail 信号
• open-pull-requests-limit 限制了并发 PR 数量
• ignore 规则覆盖了需要手动处理的依赖
• groups 策略将依赖合理分组（如适用）
• branch protection 规则正确配置了 required status checks
• 如果开启 auto-merge，确认 CI 覆盖了足够的测试用例

自测题

1. Dependabot 的 Version Updates 和 Security Updates 有什么区别？触发机制分别是什么？
2. 如果你的团队维护一个 npm monorepo（/packages/core、/packages/web、/packages/mobile），dependabot.yml 该怎么写？写出关键配置片段。
3. 为什么 PR 分组（groups）在 Dependabot 配置里很重要？不给依赖分组会有什么后果？
4. 你有一个内部 npm registry 需要认证，Dependabot 怎么访问它？写出 registries 的配置思路。
5. 什么时候应该从 Dependabot 切换到 Renovate？列出至少两个信号。

练习

练习 1：给现有项目配 Dependabot（20 分钟）

找一个你正在维护的 GitHub 仓库，在 .github/dependabot.yml 里写出配置。要求：覆盖所有包管理器、设定合理的检查频率、给生产依赖和开发依赖分不同的组、为至少一个你自己想手动跟的依赖加上 ignore 规则。提交 PR 后，观察 Dependabot 是否在下一个 schedule 窗口打开了第一个更新 PR。

练习 2：模拟安全漏洞响应（15 分钟）

假设你的项目依赖 axios@0.21.0，GitHub Advisory Database 刚刚收录了一个 Critical 级别 RCE 漏洞。走一遍完整流程：Security Update PR 出现后，你该看什么、该跑什么测试、该什么时候合？写出你团队的 SLO（从漏洞公告到合入 PR 的时间上限）。

练习 3：对比 Renovate 配置（30 分钟）

把练习 1 的 Dependabot 配置翻译成一份等价的 Renovate renovate.json。做完后对比两者的表达能力：哪些配置 Dependabot 更简洁，哪些 Renovate 更强？写一段 100 字以内的选型建议。

进阶路径

阶段一：基础自动化（1 小时）

在你自己的项目里打开 Dependabot，配好 dependabot.yml，跑通第一次 Version Update PR 和 Security Update PR。确认你可以在 GitHub Insights 面板里看到 Dependabot 的状态。

阶段二：CI 集成与分组策略（2 小时）

写一个 Dependabot 专用的 GitHub Actions workflow，在所有 dependabot[bot] 的 PR 上自动跑测试和 lint。同时调优分组策略，把同时打开的 PR 数量控制在 5 个以内。

阶段三：auto-merge 与零干预流程（半天）

在保证测试覆盖率足够的前提下，配置 branch protection rules + auto-merge，让 patch 和 minor 更新自动合入。记录下你设置的"安全边界"——哪些类型的更新绝不自动合。

阶段四：规模化与策略文档（1 天）

如果你的团队有 10+ 个仓库，写一份依赖更新策略文档，统一 dependabot.yml 模板、分组策略和 auto-merge 规则。文档要回答的问题是：一个新加入的工程师应该能在 10 分钟内配好仓库的依赖自动化。

10. 参考链接

• Dependabot 官方文档
• dependabot.yml 配置参考
• GitHub Advisory Database
• Renovate 官方文档
• Snyk 官方文档