awesome-copilot/skills/dependabot/references/dependabot-yml-reference.md

Dependabot YAML Options Reference

Complete reference for all configuration options in .github/dependabot.yml.

File Structure

version: 2                    # Required, always 2

registries:                   # Optional: private registry access
  REGISTRY_NAME:
    type: "..."
    url: "..."

multi-ecosystem-groups:       # Optional: cross-ecosystem grouping
  GROUP_NAME:
    schedule:
      interval: "..."

updates:                      # Required: list of ecosystem configurations
  - package-ecosystem: "..."  # Required
    directory: "/"            # Required (or directories)
    schedule:                 # Required
      interval: "..."

Required Keys

version

Always 2. Must be at the top level.

package-ecosystem

Defines which package manager to monitor. One entry per ecosystem (can have multiple entries for the same ecosystem with different directories).

Package Manager	YAML Value	Manifest Files
Bazel	bazel	MODULE.bazel, WORKSPACE
Bun	bun	bun.lockb
Bundler (Ruby)	bundler	Gemfile, Gemfile.lock
Cargo (Rust)	cargo	Cargo.toml, Cargo.lock
Composer (PHP)	composer	composer.json, composer.lock
Conda	conda	environment.yml
Dev Containers	devcontainers	devcontainer.json
Docker	docker	Dockerfile
Docker Compose	docker-compose	docker-compose.yml
.NET SDK	dotnet-sdk	global.json
Elm	elm	elm.json
Git Submodules	gitsubmodule	.gitmodules
GitHub Actions	github-actions	.github/workflows/*.yml
Go Modules	gomod	go.mod, go.sum
Gradle	gradle	build.gradle, build.gradle.kts
Helm	helm	Chart.yaml
Hex (Elixir)	mix	mix.exs, mix.lock
Julia	julia	Project.toml, Manifest.toml
Maven	maven	pom.xml
npm/pnpm/yarn	npm	package.json, lockfiles
NuGet	nuget	*.csproj, packages.config
OpenTofu	opentofu	*.tf
pip/pipenv/poetry/uv	pip	requirements.txt, Pipfile, pyproject.toml
Pre-commit	pre-commit	.pre-commit-config.yaml
Pub (Dart/Flutter)	pub	pubspec.yaml
Rust Toolchain	rust-toolchain	rust-toolchain.toml
Swift	swift	Package.swift
Terraform	terraform	*.tf
uv	uv	uv.lock, pyproject.toml
vcpkg	vcpkg	vcpkg.json

directory / directories

Location of package manifests relative to repo root.

• directory — single path (no glob support)
• directories — list of paths (supports * and ** globs)

# Single directory
directory: "/"

# Multiple directories with globs
directories:
  - "/"
  - "/apps/*"
  - "/packages/*"

For GitHub Actions, use / — Dependabot automatically searches .github/workflows/.

schedule

How often to check for updates.

Parameter	Values	Notes
interval	daily, weekly, monthly, quarterly, semiannually, yearly, cron	Required
day	monday–sunday	Weekly only
time	HH:MM	UTC by default
timezone	IANA timezone string	e.g., America/New_York
cronjob	Cron expression	Required when interval is cron

schedule:
  interval: "weekly"
  day: "tuesday"
  time: "09:00"
  timezone: "Europe/London"

Grouping Options

groups

Group dependencies into fewer PRs.

Parameter	Purpose	Values
IDENTIFIER	Group name (used in branch/PR title)	Letters, pipes, underscores, hyphens
applies-to	Update type	version-updates (default), security-updates
dependency-type	Filter by type	development, production
patterns	Include matching names	List of strings with * wildcard
exclude-patterns	Exclude matching names	List of strings with * wildcard
update-types	SemVer filter	major, minor, patch
group-by	Cross-directory grouping	dependency-name

groups:
  dev-deps:
    dependency-type: "development"
    update-types: ["minor", "patch"]
  angular:
    patterns: ["@angular*"]
    exclude-patterns: ["@angular/cdk"]
  monorepo:
    group-by: dependency-name

multi-ecosystem-groups (top-level)

Group updates across different ecosystems into one PR.

multi-ecosystem-groups:
  GROUP_NAME:
    schedule:
      interval: "weekly"
    labels: ["infrastructure"]
    assignees: ["@platform-team"]

Assign ecosystems with multi-ecosystem-group: "GROUP_NAME" in each updates entry. The patterns key is required in each ecosystem entry when using this feature.

Filtering Options

allow

Explicitly define which dependencies to maintain.

Parameter	Purpose
dependency-name	Match by name (supports * wildcard)
dependency-type	direct, indirect, all, production, development

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

ignore

Exclude dependencies or versions from updates.

Parameter	Purpose
dependency-name	Match by name (supports * wildcard)
versions	Specific versions or ranges (e.g., ["5.x"], [">=2.0.0"])
update-types	SemVer levels: version-update:semver-major, version-update:semver-minor, version-update:semver-patch

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

Rule: if a dependency matches both allow and ignore, it is ignored.

exclude-paths

Ignore specific directories or files during manifest scanning.

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

Supports glob patterns: * (single segment), ** (recursive), specific file paths.

PR Customization Options

labels

labels:
  - "dependencies"
  - "npm"

Set labels: [] to disable all labels. SemVer labels are always applied if they exist in the repo.

assignees

assignees:
  - "user1"
  - "user2"

Assignees must have write access (or read access for org repos).

milestone

milestone: 4  # numeric ID from milestone URL

commit-message

commit-message:
  prefix: "deps"              # up to 50 chars; colon auto-added if ends with letter/number
  prefix-development: "deps-dev"  # separate prefix for dev dependencies
  include: "scope"            # adds deps/deps-dev after prefix

pull-request-branch-name

pull-request-branch-name:
  separator: "-"  # options: "-", "_", "/"

target-branch

target-branch: "develop"

When set, version update config only applies to version updates. Security updates always target the default branch.

Scheduling & Rate Limiting

cooldown

Delay version updates for newly released versions:

Parameter	Purpose
default-days	Default cooldown (1–90 days)
semver-major-days	Cooldown for major updates
semver-minor-days	Cooldown for minor updates
semver-patch-days	Cooldown for patch updates
include	Dependencies to apply cooldown (up to 150, supports *)
exclude	Dependencies exempt from cooldown (up to 150, takes precedence)

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

open-pull-requests-limit

open-pull-requests-limit: 10  # default: 5 for version updates

Set to 0 to disable version updates entirely. Security updates have a separate internal limit of 10.

Advanced Options

versioning-strategy

Supported by: bundler, cargo, composer, mix, npm, pip, pub, uv.

Value	Behavior
auto	Default: increase for apps, widen for libraries
increase	Always increase minimum version
increase-if-necessary	Only change if current range excludes new version
lockfile-only	Only update lockfiles
widen	Widen range to include old and new versions

rebase-strategy

rebase-strategy: "disabled"

Default behavior: Dependabot auto-rebases PRs on conflicts. Rebasing stops 30 days after PR opens.

Allow Dependabot to force push over extra commits by including [dependabot skip] in commit messages.

vendor

Supported by: bundler, gomod.

vendor: true  # maintain vendored dependencies

Go modules auto-detect vendored dependencies.

insecure-external-code-execution

Supported by: bundler, mix, pip.

insecure-external-code-execution: "allow"

Allows Dependabot to execute code in manifests during updates. Required for some ecosystems that run code during resolution.

Private Registries

Top-Level Registry Definition

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

  maven-central:
    type: maven-repository
    url: https://repo.maven.apache.org/maven2
    username: ""
    password: ""

  docker-ghcr:
    type: docker-registry
    url: https://ghcr.io
    username: ${{secrets.GHCR_USER}}
    password: ${{secrets.GHCR_TOKEN}}

  python-private:
    type: python-index
    url: https://pypi.example.com/simple
    token: ${{secrets.PYPI_TOKEN}}

Associating Registries with Ecosystems

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

Use registries: "*" to allow access to all defined registries.