Customizing Dependabot pull requests to fit your processes

Learn how to tailor your Dependabot pull requests to better suit your own internal workflows.

Who can use this feature?

Users with write access

In this article

There are various ways to customize your Dependabot pull requests so that they better suit your own internal processes.

For example, to integrate Dependabot's pull requests into your CI/CD pipelines, it can apply custom labels to pull requests, which you can then use to trigger action workflows.

There are several different customization options which can all be used in combination, and tailored per package ecosystem.

Automatically adding assignees

By default, Dependabot raises pull requests without any assignees.

To automatically assign pull requests to a designated security team, you can use assignees to set these values per package ecosystem.

The example dependabot.yml file below changes the npm configuration so that all pull requests opened with version and security updates for npm have:

  • An individual ("user-name") automatically assigned to the pull requests.
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"

Automatically adding reviewers

By default, Dependabot raises pull requests without any reviewers.

To ensure your project's security updates get addressed promptly by the appropriate team, you can automatically add reviewers to Dependabot pull requests using a CODEOWNERS file. See About code owners.

Labeling pull requests with custom labels

By default, Dependabot raises pull requests with the dependencies label.

Dependabot also applies an ecosystem label, such as java, npm, or github-actions, to pull requests. Dependabot adds both the dependencies label and the ecosystem label to all pull requests, including single-ecosystem updates, to improve filtering and triaging.

Dependabot creates the default labels it applies to pull requests if they do not already exist in the repository. If you want to use custom labels instead of the defaults, you can set the labels option in your dependabot.yml file per package ecosystem; this overrides the defaults. For more information, see Managing labels and labels.

If semantic version (SemVer) labels are present in the repository, Dependabot will also automatically apply them to indicate the type of version update (major, minor, or patch). These labels are applied in addition to any custom labels you define.

You can use labels to override the default labels and specify your own custom labels per package ecosystem. This is useful if, for example, you want to:

  • Use labels to assign a priority to certain pull requests.
  • Use labels to trigger another workflow, such as automatically adding the pull request onto a project board.

The example dependabot.yml file below changes the npm configuration so that all pull requests opened with version and security updates for npm have custom labels.

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"

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

See also labels.

Adding a prefix to commit messages

By default, Dependabot attempts to detect your commit message preferences and use similar patterns. In addition, Dependabot populates the titles of pull requests based on the commit messages.

You can specify your own prefix for Dependabot's commit messages (and pull request titles) for a specific package ecosystem. This can be useful if, for example, you're running automations that process commit messages or pull requests titles.

To specify your preferences explicitly, use commit-message together with the following supported options:

  • prefix:
    • Specifies a prefix for all commit messages.
    • Prefix is also added to the start of the pull request title.
  • prefix-development:
    • Specifies a separate prefix for all commit messages that update development dependencies, as defined by the package manager or ecosystem.
    • Supported for bundler, composer, mix, maven, npm, pip, and uv.
  • include: "scope":
    • Specifies that any prefix is followed by the dependency types (deps or deps-dev) updated in the commit.

The example below shows several different options, tailored per package ecosystem:

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"

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

See also commit-message.

Associating pull requests with a milestone

Milestones help you track the progress of groups of pull requests (or issues) towards a project goal or release. With Dependabot, you can use the milestone option to associate pull requests for dependency updates with a specific milestone.

You must specify the numeric identifier of the milestone and not its label. To find the numeric identifier, check the final part of the page URL, after milestone. For example, for https://github.com/<org>/<repo>/milestone/3, "3" is the numeric identifier of the milestone.

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

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

See also milestone and About milestones.

Customizing pull request branch names

Dependabot generates a branch for each pull request. Each branch name includes dependabot, as well as the name of the package manager and the dependency to be updated. By default, these parts of the branch name are separated by a / symbol, for example:

  • dependabot/npm_and_yarn/next_js/acorn-6.4.1

You can customize branch names using the pull-request-branch-name option with the following parameters: separator, prefix, max-length, word-separator, branch-name-case, and template. All options are composable, and you can combine any of them. For the full reference of each parameter, see pull-request-branch-name.

Combining formatting options

You can combine separator, word-separator, branch-name-case, max-length, and template to produce branch names that meet your system's requirements. For example, Docker tag compatibility, Azure Container Registry naming, or Kubernetes branch length limits.

When template is set alongside other options, formatting is applied as post-processing after template rendering in this order: separator replacement, word-separator replacement, case transformation, then max-length truncation.

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
  • Before (default): dependabot/npm_and_yarn/Lodash-4.17.21
  • After (with above config): dependabot-npm-and-yarn-lodash-4.17.21

When a branch name exceeds max-length, it is truncated with a hash suffix to preserve uniqueness.

Full example with multi-ecosystem groups

The following dependabot.yml demonstrates all available options across different ecosystems, including multi-ecosystem group configuration:

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"

This configuration produces the following branch names:

ScenarioStrategyBranch name
lodash npm updateSolodependabot-npm-and-yarn-lodash-4.17.21
npm frontend-deps group updateGroupeddependabot-npm-and-yarn-frontend-deps-fc93691fd4
nginx solo Docker updateSolodependabot/docker/nginx-1.25.0
pip Django updateSolodeps/pip/django-4.2.1
pip django-deps group updateGroupeddeps/pip/django-deps-a1b2c3d4e5
Cross-ecosystem infrastructure group (Docker + Terraform)Multi-ecosystemdependabot/infra/infrastructure-fc93691fd4

Note

For multi-ecosystem groups:

  • The pull-request-branch-name on the multi-ecosystem-groups entry controls the grouped cross-ecosystem PR branch name.
  • Individual updates entries that specify multi-ecosystem-group cannot have their own pull-request-branch-name. The group-level configuration takes precedence and is the only one used for those entries.
  • {package_manager} is not available in multi-ecosystem group templates because the group spans multiple ecosystems.
  • A content digest is always auto-appended to multi-ecosystem group branches to guarantee uniqueness.

How branch name configuration applies

  • Configuration is per-update entry: Each standalone package-ecosystem entry can have its own branch name configuration. Entries assigned to a multi-ecosystem group use the group-level configuration instead.
  • Existing PRs are not affected: Changes only apply to newly created PRs.
  • Default behavior is unchanged: If you don't configure any options, branch names remain exactly as they are today.

Setting this option will also affect pull requests for security updates to the manifest files of this package manager, unless you use target-branch to check for version updates on a non-default branch.

Targeting pull requests against a non-default branch

By default, Dependabot checks for manifest files on the default branch and raises pull requests for updates against the default branch.

Generally, it makes most sense to keep Dependabot's checks and updates on the default branch. However, there may be some cases where you may need to specify a different target branch. If, for example, your team's processes require you to first test and validate updates on a non-production branch, you can use target-branch to specify a different branch for Dependabot to raise pull requests against.

Note

Dependabot raises pull requests for security updates against the default branch only. If you use target-branch, then as a result, all configuration settings for that package manager will then only apply to version updates, and not security updates.

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"

See also target-branch.