Skip to content

Commit f81d1f2

Browse files
sachin-sandhusachin-sandhu
committed
adds cooldown options to reference
1 parent f94af77 commit f81d1f2

File tree

1 file changed

+124
-0
lines changed

1 file changed

+124
-0
lines changed

‎content/code-security/dependabot/working-with-dependabot/dependabot-options-reference.md

Lines changed: 124 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -737,3 +737,127 @@ All sensitive data used for authentication should be stored securely and referen
737737
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.
738738

739739
{% data reusables.dependabot.dependabot-replaces-base-nuget %}
740+
741+
## `cooldown` {% octicon "versions" aria-label="cooldown" height="24" %}
742+
743+
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.
744+
745+
> [!NOTE]
746+
> Cooldown is not applicable for security updates.
747+
748+
### **How Cooldown Works**
749+
750+
* 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.
751+
* 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.
752+
* Once the cooldown period ends for new version, the dependency update proceeds based on the standard update strategy defined in `dependabot.yml`.
753+
754+
Without **`cooldown`** (default behaviour): {% data variables.product.prodname_dependabot %}
755+
756+
* Dependabot checks for updates according to the scheduled defined via `schedule.interval`.
757+
* All new versions are considered for updates **immediately**.
758+
759+
With **`cooldown`** enabled:
760+
761+
* Dependabot checks for updates based on the defined `schedule.interval` settings.
762+
* **Releases within the cooldown period are ignored.**
763+
* Dependabot updates the dependency to the latest available version **that are no longer in cooldown period** following the configured `versioning-strategy`.
764+
765+
### **Cooldown Configuration**
766+
767+
| Parameter | Description |
768+
|-----------|-------------|
769+
| `default-days` | **Default cooldown period for dependencies** without specific rules (optional). |
770+
| `semver-major-days` | Cooldown period for **major version updates** (optional, applies only to SEMVER-supported package managers). |
771+
| `semver-minor-days` | Cooldown period for **minor version updates** (optional, applies only to SEMVER-supported package managers). |
772+
| `semver-patch-days` | Cooldown period for **patch version updates** (optional, applies only to SEMVER-supported package managers). |
773+
| `include` | List of dependencies to **apply cooldown** (up to **150 items**). Supports wildcards (`*`). |
774+
| `exclude` | List of dependencies **excluded from cooldown** (up to **150 items**). Supports wildcards (`*`). |
775+
776+
### **semver versioning**
777+
778+
| Package Manager | SEMVER Supported |
779+
|-----------------------|------------------|
780+
| **Bundler** | Yes |
781+
| **Bun** | Yes |
782+
| **Cargo** | Yes |
783+
| **Composer** | Yes |
784+
| **Devcontainers** | No |
785+
| **Docker** | No |
786+
| **Docker Compose** | No |
787+
| **Dotnet SDK** | Yes |
788+
| **Elm** | Yes |
789+
| **Github Actions** | No |
790+
| **Gitsubmodule** | No |
791+
| **Gomod (Go Modules)**| Yes |
792+
| **Gradle** | Yes |
793+
| **Helm** | No |
794+
| **Hex (Hex)** | Yes |
795+
| **Maven** | Yes |
796+
| **NPM and Yarn** | Yes |
797+
| **Pip** | Yes |
798+
| **Pub** | Yes |
799+
| **Swift** | Yes |
800+
| **Terraform** | No |
801+
| **UV** | Yes |
802+
803+
> [!NOTE]
804+
>
805+
> * If `semver-major-days`, `semver-minor-days`, or `semver-patch-days` are not defined, `default-days` settings take precedence for cooldown based updates.
806+
> * `semver-major-days`, `semver-minor-days`, and `semver-patch-days` are only applicable for [supported package managers](#semver-versioning).
807+
> * 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.
808+
809+
### **Cooldown settings limitations**
810+
811+
* `days` must be between 1 and 90.
812+
* Maximum allowed items limit in `include` and `exclude` list is 150 each.
813+
814+
### **Example `dependabot.yml` with cooldown**
815+
816+
```yaml copy
817+
818+
version: 2
819+
updates:
820+
- package-ecosystem: "pip"
821+
directory: "/"
822+
schedule:
823+
interval: "daily"
824+
cooldown:
825+
default-days: 5
826+
semver-major-days: 30
827+
semver-minor-days: 7
828+
semver-patch-days: 3
829+
include:
830+
- "requests"
831+
- "numpy"
832+
- "pandas*"
833+
- "django"
834+
exclude:
835+
- "pandas"
836+
```
837+
838+
### **Expected Behavior**
839+
840+
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.
841+
842+
#### **Update days**
843+
844+
Updates to new versions for included dependencies will be deferred as following:
845+
846+
* **Major updates** → Delayed by **30 days** (`semver-major-days: 30`)
847+
* **Minor updates** → Delayed by **7 days** (`semver-minor-days: 7`)
848+
* **Patch updates** → Delayed by **3 days** (`semver-patch-days: 3`)
849+
850+
**Wildcard Matching:**
851+
852+
* `"pandas*"` applies cooldown to all dependencies that start with `pandas`.
853+
* `"pandas"` in `exclude` ensures that only `"pandas"` (exact match) is excluded from cooldown.
854+
855+
> [!NOTE]
856+
> To consider all dependencies for cooldown, you can:
857+
>
858+
> * Omit the `include` option which applies cooldown to all dependencies.
859+
> * Use `"*"` in `include` to apply cooldown to everything.
860+
>
861+
> Use **only** `exclude` setting if specific dependencies are to be excluded from cooldown.
862+
863+
{% data reusables.dependabot.option-affects-security-updates %}

0 commit comments

Comments
 (0)