Configuring multi-ecosystem updates for Dependabot

About multi-ecosystem updates

Multi-ecosystem updates allow you to create groups that span multiple package ecosystems and get a single Dependabot pull request with updates across all supported ecosystems. This approach helps reduce the number of Dependabot pull requests you receive and streamlines your dependency update workflow.

Multi-ecosystem updates are particularly useful for:

• Infrastructure projects that use multiple technologies (Docker, Terraform, Python scripts).
• Full-stack applications with frontend and backend dependencies that should be updated together.
• Cross-platform libraries that need synchronized protocol versions across languages.

Getting Started

You should follow these instructions to set up your first multi-ecosystem group.

1. Add multi-ecosystem-groups to your .github/dependabot.yml file

Start by defining a group with a schedule in the top-level multi-ecosystem-groups section:

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"

updates:
  # Your existing package ecosystems will go here

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"

updates:
  # Your existing package ecosystems will go here

2. Assign ecosystems to groups with patterns

1. Add the multi-ecosystem-group key.
2. Add patterns to your package ecosystem configurations.

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"

updates:
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"
  
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"

updates:
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"
  
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"

3. Commit and watch for consolidated pull requests

Once you commit the changes to your dependabot.yml file, Dependabot will:

• Check for updates according to the group's schedule
• Check for updates according to the group's schedule.
• Create a single pull request containing updates for all the ecosystems specified in the group.
• Use the group identifier in the branch name and the pull request title.

4. Customize with additional keys (optional)

Add assignees, labels, and other settings to your groups:

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

updates:
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"
  
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"

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

updates:
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"
  
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"

Multi-ecosystem specific configuration

Multi-ecosystem updates use a two-level configuration structure to provide flexibility and control over how updates are grouped and managed:

• Group-level (multi-ecosystem-groups): This is where you define the overall group behavior, scheduling, and shared settings that apply to all package ecosystems in the group.
• Ecosystem-level (updates): Configure individual package managers within the group, including which dependencies to include and ecosystem-specific settings.

This structure allows you to set consistent policies at the group level while maintaining fine-grained control over individual package ecosystems.

multi-ecosystem-groups

Define groups that span multiple package ecosystems. Each group requires:

• Group identifier: Used in branch names and pull request titles.
• Schedule: How often to check for updates. See schedule for all available options.

multi-ecosystem-group

Assign a package ecosystem to a multi-ecosystem group. Requires the patterns key to specify which dependencies to include.

For more information about patterns, see patterns and exclude-patterns.

Additional configuration options

All standard Dependabot configuration options can be used with multi-ecosystem groups. See package-ecosystem, directory, allow, ignore, and registries in Referencia de opciones de Dependabot.

Key configuration

When using multi-ecosystem groups, keys are configured at two levels. Here's a complete breakdown of which keys can be used where:

Group-level (multi-ecosystem-groups)

The following table shows the configuration keys available at the group level, along with their behavior types. For more information, see Configuration behavior.

Ecosystem-level (updates)

The following table shows the configuration keys available at the ecosystem level, along with their behavior types. For more information, see Configuration behavior.

Configuration behavior

Additive keys

Additive keys merge values from both the group level and individual ecosystem level rather than one overriding the other. This allows you to set consistent team-wide configurations at the group level while adding specific ecosystem expertise at the individual level.

• assignees - All assignees from both group and ecosystem levels are assigned
• labels - All labels from both group and ecosystem levels are applied

This table shows how Dependabot combines values from both group and ecosystem levels for Docker pull requests in the example below:

multi-ecosystem-groups:
  infrastructure:
    assignees: ["@platform-team", "@security-lead"]
    labels: ["infrastructure", "dependencies"]

updates:
  - package-ecosystem: "docker"
    assignees: ["@docker-admin"]
    labels: ["docker", "containers"]
    multi-ecosystem-group: "infrastructure"

multi-ecosystem-groups:
  infrastructure:
    assignees: ["@platform-team", "@security-lead"]
    labels: ["infrastructure", "dependencies"]

updates:
  - package-ecosystem: "docker"
    assignees: ["@docker-admin"]
    labels: ["docker", "containers"]
    multi-ecosystem-group: "infrastructure"

Group-only keys

• milestone - Integer milestone number
• commit-message - Commit message templates
• target-branch - Target branch for pull requests
• pull-request-branch-name - Branch naming configuration

Example:

This table shows how Dependabot combines values from both group and ecosystem levels for Docker pull requests in the example below:

multi-ecosystem-groups:
  infrastructure:
    assignees: ["@platform-team"]
    labels: ["infrastructure"]

updates:
  - package-ecosystem: "docker"
    assignees: ["@docker-admin"]
    labels: ["docker", "containers"]
    multi-ecosystem-group: "infrastructure"

multi-ecosystem-groups:
  infrastructure:
    assignees: ["@platform-team"]
    labels: ["infrastructure"]

updates:
  - package-ecosystem: "docker"
    assignees: ["@docker-admin"]
    labels: ["docker", "containers"]
    multi-ecosystem-group: "infrastructure"

Use cases and examples

Multi-ecosystem updates are particularly useful for projects that use multiple package managers and want to coordinate updates across them. Here are common scenarios:

Infrastructure projects

Scenario: Your infrastructure code uses multiple technologies - Docker containers, Terraform for cloud resources, and Python scripts for automation. You want all infrastructure-related updates grouped together for easier review and deployment coordination.

Why group these together: Infrastructure changes often need to be deployed together, and having separate PRs for each technology creates coordination overhead.

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"  # Weekly updates to avoid disruption

updates:
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"
  - package-ecosystem: "pip"
    directory: "/"
    patterns: ["boto3", "requests", "pyyaml"]
    multi-ecosystem-group: "infrastructure"

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"  # Weekly updates to avoid disruption

updates:
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    multi-ecosystem-group: "infrastructure"
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"
  - package-ecosystem: "pip"
    directory: "/"
    patterns: ["boto3", "requests", "pyyaml"]
    multi-ecosystem-group: "infrastructure"

Result: One weekly pull request containing updates for Docker images, Terraform providers, and Python dependencies used in infrastructure automation.

Full-stack applications

Scenario: You have a web application with a React frontend and Rails backend. You want frontend and backend dependencies updated together to ensure compatibility and streamline testing.

Why group these together: Frontend and backend often depend on each other, and updating them together ensures you can test the full application stack in one go.

multi-ecosystem-groups:
  app-dependencies:
    schedule:
      interval: "daily"  # More frequent updates for application code

updates:
  - package-ecosystem: "npm"
    directory: "/frontend"
    patterns: ["react", "lodash", "@types/*"]  # Core frontend libraries and TypeScript types
    multi-ecosystem-group: "app-dependencies"
  - package-ecosystem: "bundler"
    directory: "/backend"
    patterns: ["rails", "pg", "sidekiq"]  # Core backend framework and database
    multi-ecosystem-group: "app-dependencies"

multi-ecosystem-groups:
  app-dependencies:
    schedule:
      interval: "daily"  # More frequent updates for application code

updates:
  - package-ecosystem: "npm"
    directory: "/frontend"
    patterns: ["react", "lodash", "@types/*"]  # Core frontend libraries and TypeScript types
    multi-ecosystem-group: "app-dependencies"
  - package-ecosystem: "bundler"
    directory: "/backend"
    patterns: ["rails", "pg", "sidekiq"]  # Core backend framework and database
    multi-ecosystem-group: "app-dependencies"

Result: Daily PRs containing both frontend JavaScript/TypeScript updates and backend Ruby gem updates, allowing you to test the complete application together.

Cross-platform libraries

Scenario: You're building a library or service that uses the same protocols across different languages (like gRPC and Protocol Buffers). You want to keep the library versions synchronized across all implementations.

Why group these together: Protocol libraries need to stay compatible across different language implementations, so updating them together prevents version mismatches.

multi-ecosystem-groups:
  grpc-and-protobuf:
    schedule:
      interval: "daily"

updates:
  - package-ecosystem: "bundler"
    directory: "/grpc-proto-test/"
    patterns: ["grpc", "google-protobuf"]
    multi-ecosystem-group: "grpc-and-protobuf"
  - package-ecosystem: "npm"
    directory: "/grpc-proto-test/"
    patterns: ["@grpc/grpc-js", "google-protobuf"]
    multi-ecosystem-group: "grpc-and-protobuf"

multi-ecosystem-groups:
  grpc-and-protobuf:
    schedule:
      interval: "daily"

updates:
  - package-ecosystem: "bundler"
    directory: "/grpc-proto-test/"
    patterns: ["grpc", "google-protobuf"]
    multi-ecosystem-group: "grpc-and-protobuf"
  - package-ecosystem: "npm"
    directory: "/grpc-proto-test/"
    patterns: ["@grpc/grpc-js", "google-protobuf"]
    multi-ecosystem-group: "grpc-and-protobuf"

Result: Daily PRs ensuring that Ruby and Node.js gRPC libraries stay synchronized, preventing protocol compatibility issues.

Advanced configuration example

This comprehensive example shows how a complex project might use multiple groups with different update strategies and key merging:

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"
    assignees: ["@platform-team"]           # assign platform team
    labels: ["infrastructure", "dependencies"]
    milestone: 10                           # Track in milestone
    commit-message:
      prefix: "infra"
      include: "scope"
  
  # Application code updates - daily, with development team
  full-stack:
    schedule:
      interval: "daily"
    assignees: ["@full-stack-team"]         # assign to full-stack team
    labels: ["full-stack"]

updates:
  # Docker images - infrastructure group with additional docker expertise
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    assignees: ["@docker-admin"]            # adds to @platform-team (additive)
    labels: ["docker"]                      # adds to infrastructure, dependencies (additive)
    multi-ecosystem-group: "infrastructure"
  
  # Terraform - infrastructure group with terraform specialists
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"
    
  # Frontend - full-stack group with frontend focus
  - package-ecosystem: "npm"
    directory: "/frontend"
    patterns: ["react", "lodash", "@types/*"]
    labels: ["frontend"]                    # adds to full-stack (additive)
    multi-ecosystem-group: "full-stack"
    
  # Backend - full-stack group with backend specialist
  - package-ecosystem: "bundler"
    directory: "/backend"
    patterns: ["rails", "pg", "sidekiq"]
    assignees: ["@backend-dev"]             # adds to @full-stack-team (additive)
    multi-ecosystem-group: "full-stack"

version: 2

multi-ecosystem-groups:
  infrastructure:
    schedule:
      interval: "weekly"
    assignees: ["@platform-team"]           # assign platform team
    labels: ["infrastructure", "dependencies"]
    milestone: 10                           # Track in milestone
    commit-message:
      prefix: "infra"
      include: "scope"
  
  # Application code updates - daily, with development team
  full-stack:
    schedule:
      interval: "daily"
    assignees: ["@full-stack-team"]         # assign to full-stack team
    labels: ["full-stack"]

updates:
  # Docker images - infrastructure group with additional docker expertise
  - package-ecosystem: "docker"
    directory: "/"
    patterns: ["nginx", "redis", "postgres"]
    assignees: ["@docker-admin"]            # adds to @platform-team (additive)
    labels: ["docker"]                      # adds to infrastructure, dependencies (additive)
    multi-ecosystem-group: "infrastructure"
  
  # Terraform - infrastructure group with terraform specialists
  - package-ecosystem: "terraform"
    directory: "/"
    patterns: ["aws", "terraform-*"]
    multi-ecosystem-group: "infrastructure"
    
  # Frontend - full-stack group with frontend focus
  - package-ecosystem: "npm"
    directory: "/frontend"
    patterns: ["react", "lodash", "@types/*"]
    labels: ["frontend"]                    # adds to full-stack (additive)
    multi-ecosystem-group: "full-stack"
    
  # Backend - full-stack group with backend specialist
  - package-ecosystem: "bundler"
    directory: "/backend"
    patterns: ["rails", "pg", "sidekiq"]
    assignees: ["@backend-dev"]             # adds to @full-stack-team (additive)
    multi-ecosystem-group: "full-stack"

How this configuration works

Infrastructure PRs

• schedule: weekly

Full-stack PRs

• schedule: daily

This approach ensures that the right people are involved for each type of update while maintaining consistent policies across related technologies.

Best practices

• Group related dependencies: Only group ecosystems that logically belong together.
• Use descriptive identifiers: Choose group names that clearly indicate the group's purpose.

Further reading

• Referencia de opciones de Dependabot