Merge pull request #494 from github-community-projects/support-cooldown-config

zkoppert · web-flow · commit 0f11c4f7f7cb · 2026-03-11T12:11:29.000-07:00
feat: support cooldown for new versions
diff --git a/README.md b/README.md
@@ -187,6 +187,48 @@ updates:
       - "new"
 ```
 
+### Cooldown configuration
+
+Dependabot supports a [cooldown](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/dependabot-options-reference#cooldown-) feature that delays version update pull requests for a configurable number of days after a new version is released. This is useful to avoid updating to freshly-released versions that may contain issues.
+
+> **Note:** Cooldown only applies to **version updates**, not security updates. Security updates are always created immediately.
+
+To configure cooldown, add a `cooldown` key to the `DEPENDABOT_CONFIG_FILE`:
+
+```yaml
+# Cooldown configuration (applied globally to all ecosystems)
+cooldown:
+  default-days: 3
+  semver-major-days: 7
+  semver-minor-days: 3
+  semver-patch-days: 1
+  include:
+    - 'lodash'
+    - 'react*'
+  exclude:
+    - 'critical-package'
+
+# Private registry configurations (optional, existing feature)
+npm:
+  type: "npm"
+  url: "https://yourprivateregistry/npm/"
+  username: "${{secrets.username}}"
+  password: "${{secrets.password}}"
+```
+
+#### Cooldown options
+
+| Parameter | Description |
+| --- | --- |
+| `default-days` | Default cooldown period in days for dependencies without specific rules. |
+| `semver-major-days` | Cooldown period in days for major version updates. |
+| `semver-minor-days` | Cooldown period in days for minor version updates. |
+| `semver-patch-days` | Cooldown period in days for patch version updates. |
+| `include` | List of dependency names to apply cooldown to (up to 150 items, supports `*` wildcards). |
+| `exclude` | List of dependency names excluded from cooldown (up to 150 items, supports `*` wildcards). |
+
+At least one of the `*-days` parameters must be specified. All day values must be integers between 1 and 90.
+
 ### Example workflows
 
 #### Basic
diff --git a/dependabot_file.py b/dependabot_file.py
@@ -3,6 +3,7 @@
 import base64
 import copy
 import io
+from collections.abc import Mapping
 
 import github3
 import ruamel.yaml
@@ -19,6 +20,75 @@
 stream = io.StringIO()
 
 
+COOLDOWN_DAYS_KEYS_ORDERED = (
+    "default-days",
+    "semver-major-days",
+    "semver-minor-days",
+    "semver-patch-days",
+)
+VALID_COOLDOWN_DAYS_KEYS = frozenset(COOLDOWN_DAYS_KEYS_ORDERED)
+VALID_COOLDOWN_KEYS = VALID_COOLDOWN_DAYS_KEYS | {"include", "exclude"}
+MAX_COOLDOWN_LIST_ITEMS = 150
+MIN_COOLDOWN_DAYS = 1
+MAX_COOLDOWN_DAYS = 90
+
+
+def validate_cooldown_config(cooldown):
+    """
+    Validate the cooldown configuration from the dependabot config file.
+
+    Args:
+        cooldown: dict with cooldown configuration
+
+    Raises:
+        ValueError: if the cooldown configuration is invalid
+    """
+    if not isinstance(cooldown, Mapping):
+        raise ValueError("Cooldown configuration must be a mapping")
+
+    unknown_keys = set(cooldown.keys()) - VALID_COOLDOWN_KEYS
+    if unknown_keys:
+        raise ValueError(
+            f"Unknown cooldown configuration keys: {', '.join(sorted(unknown_keys))}"
+        )
+
+    has_days = False
+    for key in VALID_COOLDOWN_DAYS_KEYS:
+        if key in cooldown:
+            value = cooldown[key]
+            if not isinstance(value, int) or isinstance(value, bool):
+                raise ValueError(
+                    f"Cooldown '{key}' must be an integer between "
+                    f"{MIN_COOLDOWN_DAYS} and {MAX_COOLDOWN_DAYS}, "
+                    f"got {type(value).__name__}"
+                )
+            if value < MIN_COOLDOWN_DAYS or value > MAX_COOLDOWN_DAYS:
+                raise ValueError(
+                    f"Cooldown '{key}' must be between "
+                    f"{MIN_COOLDOWN_DAYS} and {MAX_COOLDOWN_DAYS}"
+                )
+            has_days = True
+
+    if not has_days:
+        raise ValueError(
+            "Cooldown configuration must include at least one of: "
+            + ", ".join(sorted(VALID_COOLDOWN_DAYS_KEYS))
+        )
+
+    for list_key in ("include", "exclude"):
+        if list_key in cooldown:
+            items = cooldown[list_key]
+            if not isinstance(items, list):
+                raise ValueError(f"Cooldown '{list_key}' must be a list")
+            if len(items) > MAX_COOLDOWN_LIST_ITEMS:
+                raise ValueError(
+                    f"Cooldown '{list_key}' must have at most {MAX_COOLDOWN_LIST_ITEMS} items"
+                )
+            for item in items:
+                if not isinstance(item, str):
+                    raise ValueError(f"Cooldown '{list_key}' items must be strings")
+
+
 def make_dependabot_config(
     ecosystem,
     group_dependencies,
@@ -27,9 +97,12 @@ def make_dependabot_config(
     labels,
     dependabot_config,
     extra_dependabot_config,
-) -> str:
+    cooldown=None,
+) -> None:
     """
-    Make the dependabot configuration for a specific package ecosystem
+    Make the dependabot configuration for a specific package ecosystem.
+
+    Mutates dependabot_config in place by appending an update entry.
 
     Args:
         ecosystem: the package ecosystem to make the dependabot configuration for
@@ -39,9 +112,7 @@ def make_dependabot_config(
         labels: the list of labels to be added to dependabot configuration
         dependabot_config: extra dependabot configs
         extra_dependabot_config: File with the configuration to add dependabot configs (ex: private registries)
-
-    Returns:
-        str: the dependabot configuration for the package ecosystem
+        cooldown: optional cooldown configuration dict to delay version update PRs
     """
 
     dependabot_config["updates"].append(
@@ -97,7 +168,17 @@ def make_dependabot_config(
             }
         )
 
-    return yaml.dump(dependabot_config, stream)
+    if cooldown:
+        cooldown_config = {}
+        for key in COOLDOWN_DAYS_KEYS_ORDERED:
+            if key in cooldown:
+                cooldown_config[key] = cooldown[key]
+        for list_key in ("include", "exclude"):
+            if list_key in cooldown:
+                cooldown_config[list_key] = [
+                    SingleQuotedScalarString(item) for item in cooldown[list_key]
+                ]
+        dependabot_config["updates"][-1].update({"cooldown": cooldown_config})
 
 
 def build_dependabot_file(
@@ -110,6 +191,7 @@ def build_dependabot_file(
     schedule_day,
     labels,
     extra_dependabot_config,
+    cooldown=None,
 ) -> str | None:
     """
     Build the dependabot.yml file for a repo based on the repo contents
@@ -124,6 +206,7 @@ def build_dependabot_file(
         schedule_day: the day of the week to run dependabot ex: "monday" if schedule is "daily"
         labels: the list of labels to be added to dependabot configuration
         extra_dependabot_config: File with the configuration to add dependabot configs (ex: private registries)
+        cooldown: optional cooldown configuration dict to delay version update PRs
 
     Returns:
         str: the dependabot.yml file for the repo
@@ -203,6 +286,7 @@ def build_dependabot_file(
                         labels,
                         dependabot_file,
                         extra_dependabot_config,
+                        cooldown,
                     )
                     break
             except OptionalFileNotFoundError:
@@ -224,6 +308,7 @@ def build_dependabot_file(
                         labels,
                         dependabot_file,
                         extra_dependabot_config,
+                        cooldown,
                     )
                     break
         except github3.exceptions.NotFoundError:
@@ -243,6 +328,7 @@ def build_dependabot_file(
                         labels,
                         dependabot_file,
                         extra_dependabot_config,
+                        cooldown,
                     )
                     break
         except github3.exceptions.NotFoundError:
@@ -262,6 +348,7 @@ def build_dependabot_file(
                         labels,
                         dependabot_file,
                         extra_dependabot_config,
+                        cooldown,
                     )
                     break
         except github3.exceptions.NotFoundError:
diff --git a/evergreen.py b/evergreen.py
@@ -10,7 +10,7 @@
 import github3
 import requests
 import ruamel.yaml
-from dependabot_file import build_dependabot_file
+from dependabot_file import build_dependabot_file, validate_cooldown_config
 from exceptions import OptionalFileNotFoundError, check_optional_file
 
 
@@ -162,6 +162,16 @@ def main():  # pragma: no cover
             # If no dependabot configuration file is present set the variable empty
             extra_dependabot_config = None
 
+        # Extract cooldown config if present (it's not a registry/ecosystem key)
+        cooldown = None
+        if extra_dependabot_config and "cooldown" in extra_dependabot_config:
+            cooldown = extra_dependabot_config.pop("cooldown")
+            try:
+                validate_cooldown_config(cooldown)
+            except ValueError as e:
+                print(f"Invalid cooldown configuration: {e}")
+                cooldown = None
+
         print(f"Checking {repo.full_name} for compatible package managers")
         # Try to detect package managers and build a dependabot file
         dependabot_file = build_dependabot_file(
@@ -174,6 +184,7 @@ def main():  # pragma: no cover
             schedule_day,
             labels,
             extra_dependabot_config,
+            cooldown,
         )
 
         yaml = ruamel.yaml.YAML()
diff --git a/test_cooldown.py b/test_cooldown.py
@@ -0,0 +1,123 @@
+"""Tests for the cooldown validation in dependabot_file.py."""
+
+import unittest
+
+from dependabot_file import validate_cooldown_config
+from ruamel.yaml import YAML
+
+
+class TestValidateCooldownConfig(unittest.TestCase):
+    """Test the validate_cooldown_config function."""
+
+    def test_valid_default_days_only(self):
+        """Test valid cooldown with just default-days"""
+        validate_cooldown_config({"default-days": 3})
+
+    def test_valid_ruamel_commented_map(self):
+        """Test that ruamel.yaml CommentedMap is accepted as a valid mapping"""
+        yaml = YAML()
+        cooldown = yaml.load(b"default-days: 5\nsemver-major-days: 14\n")
+        validate_cooldown_config(cooldown)
+
+    def test_valid_all_days(self):
+        """Test valid cooldown with all day parameters"""
+        validate_cooldown_config(
+            {
+                "default-days": 3,
+                "semver-major-days": 7,
+                "semver-minor-days": 3,
+                "semver-patch-days": 1,
+            }
+        )
+
+    def test_valid_with_include_exclude(self):
+        """Test valid cooldown with include and exclude lists"""
+        validate_cooldown_config(
+            {
+                "default-days": 5,
+                "include": ["lodash", "react*"],
+                "exclude": ["critical-pkg"],
+            }
+        )
+
+    def test_valid_zero_days(self):
+        """Test that zero is below the minimum and raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": 0})
+
+    def test_valid_boundary_min(self):
+        """Test that 1 day is the minimum valid value"""
+        validate_cooldown_config({"default-days": 1})
+
+    def test_valid_boundary_max(self):
+        """Test that 90 days is the maximum valid value"""
+        validate_cooldown_config({"default-days": 90})
+
+    def test_invalid_not_a_dict(self):
+        """Test that non-dict cooldown raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config("not a dict")
+
+    def test_invalid_no_days_keys(self):
+        """Test that cooldown without any days key raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"include": ["lodash"]})
+
+    def test_invalid_negative_days(self):
+        """Test that negative days raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": -1})
+
+    def test_invalid_days_exceed_max(self):
+        """Test that days above 90 raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": 91})
+
+    def test_invalid_days_not_int(self):
+        """Test that non-integer days raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": "three"})
+
+    def test_invalid_days_bool(self):
+        """Test that boolean days raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": True})
+
+    def test_invalid_unknown_key(self):
+        """Test that unknown keys raise ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": 3, "unknown-key": 1})
+
+    def test_invalid_include_not_list(self):
+        """Test that non-list include raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": 3, "include": "lodash"})
+
+    def test_invalid_include_item_not_string(self):
+        """Test that non-string include items raise ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config({"default-days": 3, "include": [123]})
+
+    def test_invalid_include_too_many_items(self):
+        """Test that include with more than 150 items raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config(
+                {
+                    "default-days": 3,
+                    "include": [f"pkg-{i}" for i in range(151)],
+                }
+            )
+
+    def test_invalid_exclude_too_many_items(self):
+        """Test that exclude with more than 150 items raises ValueError"""
+        with self.assertRaises(ValueError):
+            validate_cooldown_config(
+                {
+                    "default-days": 3,
+                    "exclude": [f"pkg-{i}" for i in range(151)],
+                }
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/test_dependabot_file.py b/test_dependabot_file.py
