Skip to main content

自定义依赖项更新

您可以自定义 Dependabot 如何维护依赖项。

谁可以使用此功能?

Users with write access

Note

站点管理员必须先为 你的 GitHub Enterprise Server 实例设置 Dependabot updates,然后你才能使用此功能。 有关详细信息,请参阅“为企业启用 Dependabot”。

如果企业所有者在企业级别设置了策略,你可能无法启用或禁用 Dependabot updates。 有关详细信息,请参阅“强制实施企业的代码安全性和分析策略”。

关于自定义依赖项更新

启用版本更新后,可以通过向 dependabot.yml 文件添加更多选项来自定义 Dependabot 维护依赖项的方式。 例如,可以:

  • 指定星期几打开版本更新的拉取请求:schedule.day
  • 为每个包管理器设置审阅者、被分派人和标签:reviewersassigneeslabels
  • 创建依赖项组(每个包生态系统),以便 Dependabot 更新单个拉取请求中的依赖项组:groups
  • 为每个清单文件的更改定义版本控制策略:versioning-strategy
  • 更改为版本更新打开的最大拉取请求数(默认值为 5):open-pull-requests-limit
  • 打开版本更新的拉取请求以定位特定分支,而不是默认分支:target-branch

有关配置选项的详细信息,请参阅“dependabot.yml 文件的配置选项”。

更新存储库中的 dependabot.yml 文件后,Dependabot 会使用新配置立即进行检查。 几分钟内,你将在 Dependabot 选项卡上看到更新的依赖项列表,如果存储库有很多依赖项,可能需要更长时间。 您可能还会看到针对版本更新的新拉取请求。 有关详细信息,请参阅“列出为版本更新配置的依赖项”。

配置更改对安全更新的影响

如果自定义 dependabot.yml 文件,可能会注意到针对安全更新提出的拉取请求发生了一些更改。 这些拉取请求始终由依赖项的安全通告触发,而不是由 Dependabot 时间表触发。 但是,它们会从 dependabot.yml 文件继承相关的配置设置,除非为版本更新指定不同的目标分支。

有关示例,请参阅下面的“设置自定义标签”。

修改计划

设置 daily 更新计划后,Dependabot 会默认在 05:00 UTC 检查新版本。 可以使用 schedule.time 指定检查更新的备用时间(格式:hh:mm)。

下面的示例 dependabot.yml 文件扩展了 npm 配置,以指定 Dependabot 应何时检查依赖项的版本更新。

# `dependabot.yml` file with
# customized schedule for version updates

version: 2
updates:
  # Keep npm dependencies up to date
  - package-ecosystem: "npm"
    directory: "/"
    # Check the npm registry for updates at 2am UTC
    schedule:
      interval: "daily"
      time: "02:00"

设置审查者和受理人

默认情况下,Dependabot 会提出没有任何审查者或受理人的拉取请求。

可以使用 reviewersassignees 为针对包管理器提出的所有拉取请求指定审阅者和被分派人。 指定一个团队时,必须使用完整的团队名称,就像 @mentioning 团队(包括组织)一样。

下面的示例 dependabot.yml 文件更改了 npm 配置,使所有通过 npm 的版本和安全更新打开的拉取请求都有两个审阅者和一个被分派人。

# `dependabot.yml` file with
# reviews and an 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 reviewers
    reviewers:
      - "my-org/team-name"
      - "octocat"
    # Raise all npm pull requests with an assignee
    assignees:
      - "user-name"

设置自定义标签

默认情况下,Dependabot 会提出所有带有 dependencies 标签的拉取请求。 如果定义了多个包管理器,Dependabot 在每个拉取请求上都会包含一个附加标签。 这表示拉取请求将更新的语言或生态系统,例如:java 表示 Gradle 更新,submodules 表示 git 子模块。 Dependabot 将根据需要自动在您的仓库中创建这些默认标签。

可以使用 labels 替代默认标签,并为针对包管理器提出的所有拉取请求指定替代标签。 无法在 dependabot.yml 文件中创建新标签,因此,存储库中必须已存在替代标签。

下面的示例 dependabot.yml 文件更改了 npm 配置,使所有通过 npm 的版本和安全更新打开的拉取请求都有自定义标签。 它还会更改 Docker 配置,以针对自定义分支检查版本更新,并针对自定义分支使用自定义标签提出拉取请求。 Docker 的变更不会影响安全更新拉取请求,因为安全更新始终针对默认分支进行。

Note

新版 target-branch 必须包含要更新的 Dockerfile,否则,此变更将导致 Docker 版本更新被禁用。

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

    # Keep Docker dependencies up to date
  - package-ecosystem: "docker"
    directory: "/"
    schedule:
      interval: "weekly"
    # Raise pull requests for Docker version updates
    # against the "develop" branch. The Docker configuration
    # no longer affects security update pull requests.
    target-branch: "develop"
    # Use custom labels on pull requests for Docker version updates
    labels:
      - "Docker dependencies"
      - "triage-board"

将 Dependabot updates 分组到一个拉取请求

默认情况下,Dependabot 为每个需要更新到较新版本的依赖项提出单个拉取请求。 可以使用 groups 创建依赖项集(每个包管理器),以便 Dependabot 打开单个拉取请求以同时更新多个依赖项。

还可以根据更新如何影响特定生态系统来指定分组设置并遵循语义版本控制 (SemVer)。 这意味着你可以将所有修补程序更新组合在一起。 此方法可帮助 Dependabot 创建尽可能少的拉取请求,同时降低意外接受可能导致问题的更改的可能性。 如果包遵循 SemVer,则次要更新和修补更新向后兼容的几率更高(但不能保证)。

Note

SemVer 是用于定义软件包版本的接受标准,格式为 x.y.z。 Dependabot 假设此形式的版本始终为 major.minor.patch

Dependabot 按组在 dependabot.yml 文件中出现的顺序创建组。 如果依赖项更新可以属于多个组,则只会将它分配给与之匹配的第一个组。

只能为 Dependabot version updates 创建组。 Dependabot security updates 不支持分组更新。 此外,如果存在针对某个易受攻击包的分组拉取请求,则 Dependabot security updates 将始终尝试创建单独的拉取请求,即使现有组拉取请求针对相同或更高版本的更新。

必须为每个包生态系统配置组。

groups 的示例配置

示例 1

dependabot.yml 文件配置使用 patternsdependency-type 选项来包括组中的特定依赖项,并使用 exclude-patterns 从组中排除一个依赖项(或多个依赖项)。

# `dependabot.yml` file using the `dependency-type` option to group updates
# in conjunction with `patterns` and `exclude-patterns`.

groups:
  production-dependencies:
    dependency-type: "production"
  development-dependencies:
    dependency-type: "development"
    exclude-patterns:
    - "rubocop*"
  rubocop:
    patterns:
    - "rubocop*"

示例 2

一个具有自定义捆绑程序配置的 dependabot.yml 文件,已对其进行修改以创建一组依赖项。 配置会指定与一个依赖项(或多个依赖项)的名称匹配的 patterns(字符串),以便将依赖项包含在组中。

# `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.

version: 2
updates:
  # Keep bundler dependencies up to date
  - package-ecosystem: "bundler"
    directory: "/"
    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)
          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 文件进行了配置,以便与最高可解析版本为 minorpatch 的模式 @angular* 匹配的任何包都将分到同一个组。 Dependabot 将为任何不匹配模式的包,或者没有更新到 minorpatch 版本的包创建一个单独的拉取请求。

# `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.

version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      angular:
        patterns:
        - "@angular*"
        update-types:
        - "minor"
        - "patch"

示例 4

dependabot.yml 文件使用 ignore 条件来排除对 major 版本 @angular* 包的更新。

# `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.

groups:
  angular:
    patterns:
    - "@angular*"
    update-types:
    - "minor"
    - "patch"
ignore:
  - dependency-name: "@angular*"
    update-types: ["version-update:semver-major"]

有关在 dependabot.yml 文件中配置依赖项组的详细信息,请参阅“dependabot.yml 文件的配置选项”。

忽略 Dependabot version updates 的特定依赖项

如果尚未准备好采用项目中的依赖项更改,可以将 Dependabot 配置为在打开版本更新拉取请求时忽略这些依赖项。 可使用以下方法之一来执行此操作。

  • dependabot.yml 文件中的依赖项配置 ignore 选项。 可以使用此选项来忽略特定依赖项、版本和更新类型的更新。 有关详细信息,请参阅“dependabot.yml 文件的配置选项”。
  • 对 Dependabot 拉取请求使用 @dependabot ignore 注释命令进行版本更新。 可以使用注释命令来忽略特定依赖项和版本的更新。 有关详细信息,请参阅“管理依赖项更新的所有拉取请求”。

如果要取消忽略依赖项或忽略条件,可以从 dependabot.yml 文件中删除忽略条件或重新打开拉取请求。

对于已分组版本更新的拉取请求,还可以使用 @dependabot unignore 注释命令。 @dependabot unignore 注释命令可通过注释 Dependabot 拉取请求来执行以下操作:

  • 取消忽略特定忽略条件
  • 取消忽略特定依赖项
  • 取消忽略 Dependabot 拉取请求中所有依赖项的所有忽略条件

Note

@dependabot unignore 注释命令仅适用于对已分组版本更新的拉取请求。

有关详细信息,请参阅“管理依赖项更新的所有拉取请求”。

更多示例

有关更多示例,请参阅“dependabot.yml 文件的配置选项”。