diff --git a/content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md b/content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md index bac7dab425e6..428371fca003 100644 --- a/content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md +++ b/content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md @@ -737,3 +737,127 @@ All sensitive data used for authentication should be stored securely and referen The `url` parameter defines where to access a registry. When the optional `replaces-base` parameter is enabled (`true`), {% data variables.product.prodname_dependabot %} resolves dependencies using the value of `url` rather than the base URL of that specific ecosystem. {% data reusables.dependabot.dependabot-replaces-base-nuget %} + +## `cooldown` {% octicon "versions" aria-label="cooldown" height="24" %} + +Defines a **cooldown period** for dependency updates to delay updates for a configurable number of days. This feature enables dependabot users to customize how often they receive new version updates, offering greater control over update frequency. + +> [!NOTE] +> Cooldown is not applicable for security updates. + +### **How Cooldown Works** + +* When Dependabot runs updates as per defined schedule, it checks the **cooldown settings** to determine if new release for dependency is still within its cooldown period. +* If new version release date is within the cooldown period, dependency version update is **filtered out** and will not be updated until the cooldown period expires. +* Once the cooldown period ends for new version, the dependency update proceeds based on the standard update strategy defined in `dependabot.yml`. + +Without **`cooldown`** (default behaviour): {% data variables.product.prodname_dependabot %} + +* Dependabot checks for updates according to the scheduled defined via `schedule.interval`. +* All new versions are considered for updates **immediately**. + +With **`cooldown`** enabled: + +* Dependabot checks for updates based on the defined `schedule.interval` settings. +* **Releases within the cooldown period are ignored.** +* Dependabot updates the dependency to the latest available version **that are no longer in cooldown period** following the configured `versioning-strategy`. + +### **Cooldown Configuration** + +| Parameter | Description | +|-----------|-------------| +| `default-days` | **Default cooldown period for dependencies** without specific rules (optional). | +| `semver-major-days` | Cooldown period for **major version updates** (optional, applies only to SEMVER-supported package managers). | +| `semver-minor-days` | Cooldown period for **minor version updates** (optional, applies only to SEMVER-supported package managers). | +| `semver-patch-days` | Cooldown period for **patch version updates** (optional, applies only to SEMVER-supported package managers). | +| `include` | List of dependencies to **apply cooldown** (up to **150 items**). Supports wildcards (`*`). | +| `exclude` | List of dependencies **excluded from cooldown** (up to **150 items**). Supports wildcards (`*`). | + +### **semver versioning** + +| Package Manager | SEMVER Supported | +|-----------------------|------------------| +| **Bundler** | Yes | +| **Bun** | Yes | +| **Cargo** | Yes | +| **Composer** | Yes | +| **Devcontainers** | No | +| **Docker** | No | +| **Docker Compose** | No | +| **Dotnet SDK** | Yes | +| **Elm** | Yes | +| **Github Actions** | No | +| **Gitsubmodule** | No | +| **Gomod (Go Modules)**| Yes | +| **Gradle** | Yes | +| **Helm** | No | +| **Hex (Hex)** | Yes | +| **Maven** | Yes | +| **NPM and Yarn** | Yes | +| **Pip** | Yes | +| **Pub** | Yes | +| **Swift** | Yes | +| **Terraform** | No | +| **UV** | Yes | + +> [!NOTE] +> +> * If `semver-major-days`, `semver-minor-days`, or `semver-patch-days` are not defined, `default-days` settings take precedence for cooldown based updates. +> * `semver-major-days`, `semver-minor-days`, and `semver-patch-days` are only applicable for [supported package managers](#semver-versioning). +> * The `exclude` list always take precedence over the `include` list. If a dependency is specified in both lists, it is excluded from cooldown and will be updated immediately. + +### **Cooldown settings limitations** + +* `days` must be between 1 and 90. +* Maximum allowed items limit in `include` and `exclude` list is 150 each. + +### **Example `dependabot.yml` with cooldown** + +```yaml copy + +version: 2 +updates: + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "daily" + cooldown: + default-days: 5 + semver-major-days: 30 + semver-minor-days: 7 + semver-patch-days: 3 + include: + - "requests" + - "numpy" + - "pandas*" + - "django" + exclude: + - "pandas" +``` + +### **Expected Behavior** + +Cooldown will be active for dependencies `requests`, `numpy` and dependencies starting with `pandas`, and `django`. Dependency with exact name `pandas` will be excluded from cooldown based updates as it is present in **exclude** list. + +#### **Update days** + +Updates to new versions for included dependencies will be deferred as following: + +* **Major updates** → Delayed by **30 days** (`semver-major-days: 30`) +* **Minor updates** → Delayed by **7 days** (`semver-minor-days: 7`) +* **Patch updates** → Delayed by **3 days** (`semver-patch-days: 3`) + +**Wildcard Matching:** + +* `"pandas*"` applies cooldown to all dependencies that start with `pandas`. +* `"pandas"` in `exclude` ensures that only `"pandas"` (exact match) is excluded from cooldown. + +> [!NOTE] +> To consider all dependencies for cooldown, you can: +> +> * Omit the `include` option which applies cooldown to all dependencies. +> * Use `"*"` in `include` to apply cooldown to everything. +> +> Use **only** `exclude` setting if specific dependencies are to be excluded from cooldown. + +{% data reusables.dependabot.option-affects-security-updates %}