NEW_ECOSYSTEMS.md
This guide walks you through the process of adding support for a new package ecosystem to Dependabot. Contributing a new ecosystem is a significant undertaking that requires coordination with the Dependabot team.
Before you begin, research and decide on the following:
Before starting any implementation work, check if there's already an existing issue in the dependabot-core repository for the ecosystem you want to add. If there is an existing issue, you can use that issue to coordinate your contribution instead of creating a new one, since all interested users are likely already following the existing issue.
This allows the Dependabot team to be in the loop with your plans and provide early feedback before you invest significant time in implementation.
Adding a new ecosystem involves several phases:
dependabot-coreFork the dependabot-core repository and create a new branch for your ecosystem.
Using the Quick Create Rake Task (Recommended)
To quickly generate a complete ecosystem with both scaffolding and infrastructure updates in one command:
rake ecosystem:create[your_ecosystem_name]
This single command will:
Using Individual Rake Tasks
Alternatively, you can run the scaffold and infrastructure update tasks separately:
# Step 1: Generate the ecosystem structure
rake ecosystem:scaffold[your_ecosystem_name]
# Step 2: Update supporting infrastructure
rake ecosystem:update_infrastructure[your_ecosystem_name]
What Gets Created
The scaffold task automatically creates:
Overwrite Modes
If the ecosystem directory already exists, you can control how existing files are handled with the overwrite mode parameter:
# Interactive mode (default) - prompts for each existing file
rake ecosystem:create[your_ecosystem_name]
rake ecosystem:create[your_ecosystem_name,ask]
# Skip mode - preserves all existing files without prompting
rake ecosystem:create[your_ecosystem_name,skip]
# Force mode - overwrites all existing files without prompting
rake ecosystem:scaffold[your_ecosystem_name,force]
After scaffolding, you'll need to:
Manual Setup
Alternatively, you can create the structure manually. Create a new top-level ecosystem directory. Your ecosystem should be implemented as a standalone ecosystem rather than piggybacking off existing ones. You'll need to implement several key classes:
You must implement these four core classes for your ecosystem:
file_fetcher.rb): Handles fetching manifest and lockfiles from repositories, inherits from Dependabot::FileFetchers::Basefile_parser.rb): Parses manifest files to extract dependency information, inherits from Dependabot::FileParsers::Baseupdate_checker.rb): Checks for available updates to dependencies, inherits from Dependabot::UpdateCheckers::Basefile_updater.rb): Updates manifest and lockfiles with new dependency versions, inherits from Dependabot::FileUpdaters::BaseYou may also implement these additional classes based on your ecosystem's needs:
Dependabot::MetadataFinders::BaseDependabot::RequirementDependabot::Versionnew_ecosystem/lib/dependabot/
├── new_ecosystem.rb # Main registration file
└── new_ecosystem/
├── file_fetcher.rb # Required
├── file_parser.rb # Required
├── update_checker.rb # Required
├── file_updater.rb # Required
├── metadata_finder.rb # Optional
├── requirements_updater.rb # Optional
├── version.rb # Optional
├── requirement.rb # Optional
└── helpers/
└── (any helper classes)
Main Registration File
Create a main registration file at new_ecosystem/lib/dependabot/new_ecosystem.rb that requires all your classes and registers them with Dependabot. For an example, see the Docker ecosystem registration file.
This file serves as the entry point for your ecosystem and ensures all classes are properly loaded and registered with Dependabot's internal lookup systems.
Beta Feature Flag Implementation
Implement beta feature flag: Hide file fetching behind the allow_beta_ecosystems? feature flag function to ensure your ecosystem only operates when beta ecosystems are enabled. This method will be available in your FileFetcher class since it inherits from Dependabot::FileFetchers::Base.
Add comprehensive unit tests for all your classes as part of the core implementation:
# Example test structure
spec/dependabot/your_ecosystem/
├── file_fetcher_spec.rb
├── file_parser_spec.rb
├── file_updater_spec.rb
├── update_checker_spec.rb
├── metadata_finder_spec.rb (if implemented)
└── fixtures/
└── (test fixtures)
Ensure your tests cover:
Your ecosystem implementation requires updates to numerous supporting files throughout the repository.
Automated Infrastructure Updates (Recommended)
After scaffolding your ecosystem, you can automatically update most supporting infrastructure files using the provided Rake task:
bundle exec rake ecosystem:update_infrastructure[your_ecosystem_name]
This automated task will update the following files:
The task is idempotent and will skip files that already contain your ecosystem configuration.
Rollback Strategy for Testing
When testing the scaffold and infrastructure automation tasks locally, you may want to rollback changes:
For CI Environments:
For Local Development:
# Option 1: Reset to clean state
git reset --hard HEAD # Revert tracked files
git clean -fd # Remove untracked files and directories
# Option 2: Stash and restore
git stash -u # Save all current changes including untracked files
rake ecosystem:scaffold[test_ecosystem]
rake ecosystem:update_infrastructure[test_ecosystem]
# Run validation/tests
git reset --hard HEAD # Revert tracked files
git clean -fd # Remove untracked files
git stash pop # Restore previous changes
Manual Updates (If Needed)
For files not covered by the automated task or requiring ecosystem-specific customization:
cd omnibus && bundle install
cd ../updater && bundle install
Some ecosystems require native helpers for complex operations like dependency resolution. If your ecosystem needs this:
As part of contributing a new ecosystem, you should also implement support for Dependabot's cooldown feature, which allows users to delay updates for a specified period after a new version is released.
The cooldown feature addresses two major problems:
Users can configure cooldowns in their dependabot.yml:
version: 2
updates:
- package-ecosystem: "your-ecosystem"
directory: "/"
schedule:
interval: "daily"
# Cooldown configuration
cooldown:
default-days: 5
semver-major-days: 30
semver-minor-days: 7
semver-patch-days: 3
include:
- "package-name"
- "package-pattern*"
exclude:
- "excluded-package"
Your ecosystem implementation must support cooldown logic in the UpdateChecker class:
UpdateChecker must be able to determine when a version was releasedWhen adding a new ecosystem, you should validate your implementation locally before opening a PR. Dependabot provides a bin/dry-run.rb script that allows you to simulate update checks against real repositories.
The dry-run script can be run in your bin/docker-dev-shell your-new-ecosystem-name [--rebuild]
Create (or fork) a public repository with representative manifest and lockfiles for your ecosystem. Then run:
# Run all updates
bin/dry-run.rb your-ecosystem your-github-user/your-sample-repo --enable-beta-ecosystems
You can also simulate security advisories by setting the SECURITY_ADVISORIES environment variable and use the --security-updates-only flag:
# Security updates only
SECURITY_ADVISORIES='[{"dependency-name":"numpy","patched-versions":["1.28.0"],"unaffected-versions":[],"affected-versions":["< 1.27.0"]}]'
bin/dry-run.rb your-ecosystem your-github-user/your-sample-repo --enable-beta-ecosystems --security-updates-only
You can structure your test repo with subfolders containing different manifest scenarios and run targeted dry-runs using --dir:
REPO="your-org/your-sample-repo"
BASE_CMD="bin/dry-run.rb your-ecosystem $REPO --enable-beta-ecosystems"
$BASE_CMD --dir="/special-cases/private-repository"
$BASE_CMD --dir="/tier1-full-support/project-a"
This allows you to easily validate edge cases and multiple manifest types.
For convenience, you can wrap your dry-run tests in a shell script inside the dependabot-core-dev shell:
#!/bin/bash
REPO="your-org/your-sample-repo"
BASE_CMD="bin/dry-run.rb your-ecosystem $REPO --enable-beta-ecosystems"
echo "Running Tier 1 tests..."
$BASE_CMD --dir="/tier1/project-one"
$BASE_CMD --dir="/tier1/project-two"
echo "Running Special Cases..."
$BASE_CMD --dir="/special-cases/custom-lockfiles"
By default, the dry-run script runs without authentication and may hit GitHub API rate limits. To avoid this, set a personal access token:
export LOCAL_GITHUB_ACCESS_TOKEN=ghp_yourtokenhere
This will be automatically picked up by the dry-run script and give you higher rate limits.
Add smoke tests to the dependabot/smoke-tests repository. See the repository documentation for detailed instructions on creating and running smoke tests for your ecosystem.
Since ecosystem support requires changes to Dependabot's API and deployment infrastructure, you'll need to coordinate with the Dependabot team:
The Dependabot team will need to:
Your ecosystem needs to be added to:
Your ecosystem will be released behind a feature flag that the Dependabot team will configure. As part of your implementation, you must ensure that file fetching is properly hidden behind the allow_beta_ecosystems? feature flag function so your ecosystem only operates when beta ecosystems are enabled.
Initially, your ecosystem will be marked as beta. Users will need to:
# .github/dependabot.yml
version: 2
enable-beta-ecosystems: true
updates:
- package-ecosystem: "your-ecosystem"
directory: "/"
schedule:
interval: "daily"
# Test cooldown functionality during beta
cooldown:
default-days: 3
semver-major-days: 7
Create a test repository with:
Engage with the community to test your ecosystem:
After successful beta testing:
For a complete example, review the Helm ecosystem implementation which demonstrates:
Adding a new ecosystem timeline varies depending on the contributor and ecosystem complexity:
The timeline can vary significantly based on ecosystem complexity, cooldown implementation requirements, and the need for native helpers or special infrastructure.
Contributing a new ecosystem to Dependabot is a significant contribution to the open source community. Thank you for considering this contribution, and we look forward to working with you to expand Dependabot's ecosystem support!