You signed in with another tab or window.Reload to refresh your session.You signed out in another tab or window.Reload to refresh your session.You switched accounts on another tab or window.Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates.md
+47-1Lines changed: 47 additions & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -33,7 +33,9 @@ By default, {% data variables.product.prodname_dependabot %} balances its worklo
33
33
34
34
However, to reduce distraction, or to better organize time and resources for reviewing and addressing version updates, you might find it useful to modify the frequency and timings. For example, you may prefer {% data variables.product.prodname_dependabot %} to run weekly rather than daily checks for updates, and at a time that ensures pull requests are raised before for your team's triage session.
35
35
36
-
You can use`schedule` with a combination of options to modify the frequency and timings of when {% data variables.product.prodname_dependabot %} checks for version updates
36
+
###Modifying the frequency and timings for dependency updates
37
+
38
+
You can use`schedule` with a combination of options to modify the frequency and timings of when {% data variables.product.prodname_dependabot %} checks for version updates.
37
39
38
40
The example`dependabot.yml` file below changes the npm configuration to specify that {% data variables.product.prodname_dependabot %} should check for version updates to npm dependencies every Tuesday at 02:00 Japanese Standard Time (UTC +09:00).
39
41
@@ -56,6 +58,50 @@ updates:
56
58
57
59
See also [schedule](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#schedule-).
58
60
61
+
### Setting up a cooldown period for dependency updates
62
+
63
+
You can use`cooldown` with a combination of options to control when {% data variables.product.prodname_dependabot %} creates pull requests for **version updates**.
64
+
65
+
The example `dependabot.yml` file below shows a cooldown period being applied to the dependencies `requests`, `numpy`, and those prefixed with `pandas` or `django`, but not to the dependency called `pandas` (exact match), which is excluded via the **exclude** list.
66
+
67
+
```yaml copy
68
+
version: 2
69
+
updates:
70
+
- package-ecosystem: "pip"
71
+
directory: "/"
72
+
schedule:
73
+
interval: "daily"
74
+
cooldown:
75
+
default-days: 5
76
+
semver-major-days: 30
77
+
semver-minor-days: 7
78
+
semver-patch-days: 3
79
+
include:
80
+
- "requests"
81
+
- "numpy"
82
+
- "pandas*"
83
+
- "django"
84
+
exclude:
85
+
- "pandas"
86
+
```
87
+
88
+
* The number of cooldown days must be between 1 and 90.
89
+
* The maximum allowed items limit in `include` and `exclude` lists, which can be used with `cooldown`, is 150 each.
90
+
91
+
> [!NOTE]
92
+
> To consider **all dependencies** for a cooldown period, you can:
93
+
> * Omit the `include` option which applies cooldown to all dependencies.
94
+
> * Use `"*"` in `include` to apply the cooldown settings to everything.
95
+
> We recommend the use of `exclude` to **only** exclude **specific dependencies** from cooldown settings.
96
+
97
+
SemVer is supported for most package managers. Updates to new versions for dependencies in cooldown are deferred as follows:
98
+
99
+
* Major updates: Delayed by 30 days (`semver-major-days: 30`).
100
+
* Minor updates: Delayed by 7 days (`semver-minor-days: 7`).
101
+
* Patch updates: Delayed by 3 days (`semver-patch-days: 3`).
102
+
103
+
See also [`cooldown`](/code-security/dependabot/working-with-dependabot/dependabot-options-reference#cooldown-).
104
+
59
105
## Prioritizing meaningful updates
60
106
61
107
You can use `groups` to consolidate updates for multiple dependencies into a single pull request. This helps you focus your review time on higher risk updates, and minimize the time spent reviewing minor version updates. For example, you can combine updates for minor or patch updates for development dependencies into a single pull request, and have a dedicated group for security or version updates that impact a key area of your codebase.
> `cooldown` is not available for the NuGet ecosystem.
174
+
175
+
Defines a **cooldown period** for dependency updates, allowing updates to be delayed for a configurable number of days.
176
+
177
+
This feature enables users to customize how often {% data variables.product.prodname_dependabot %} generates new version updates, offering greater control over update frequency. For examples, see [AUTOTITLE](/code-security/dependabot/dependabot-version-updates/optimizing-pr-creation-version-updates#setting-up-a-cooldown-period-for-dependency-updates).
178
+
179
+
{% data variables.product.prodname_dependabot %} default behavior:
180
+
181
+
* Check for updates according to the scheduled defined via `schedule.interval`.
182
+
* Consider all new versions **immediately** for updates.
183
+
184
+
When **`cooldown`** is defined:
185
+
186
+
1. {% data variables.product.prodname_dependabot %} checks for updates according to the defined `schedule.interval` settings.
187
+
1. {% data variables.product.prodname_dependabot %} checks for any cooldown settings.
188
+
1. If a dependency’s new release falls within its cooldown period, {% data variables.product.prodname_dependabot %} skips updating the version for that dependency.
189
+
1. Dependencies without a cooldown period, or those past their cooldown period, are updated to the latest version as per the configured `versioning-strategy` setting.
190
+
1. After a cooldown ends for a dependency, {% data variables.product.prodname_dependabot %} resumes updating the dependency following the standard update strategy defined in `dependabot.yml`.
191
+
192
+
{% data reusables.dependabot.option-affects-security-updates %}
193
+
194
+
### **Configuration of `cooldown`**
195
+
196
+
You can specify the duration of the cooldown using the options below.
197
+
198
+
| Parameter | Description |
199
+
|-----------|-------------|
200
+
| `default-days` | **Default cooldown period for dependencies** without specific rules (optional). |
201
+
| `semver-major-days` | Cooldown period for **major version updates** (optional, applies only to package managers supporting SemVer). |
202
+
| `semver-minor-days` | Cooldown period for **minor version updates** (optional, applies only to package managers supporting SemVer). |
203
+
| `semver-patch-days` | Cooldown period for **patch version updates** (optional, applies only to package managers supporting SemVer). |
204
+
| `include` | List of dependencies to **apply cooldown** (up to **150 items**). Supports wildcards (`*`). |
205
+
| `exclude` | List of dependencies **excluded from cooldown** (up to **150 items**). Supports wildcards (`*`). |
206
+
207
+
The table below shows the package managers for which SemVer is supported.
> * If `semver-major-days`, `semver-minor-days`, or `semver-patch-days` are not defined, the `default-days` settings will take precedence for cooldown-based updates.
237
+
> * 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.
**Required option**. Use to define the location of the package manifests for each package manager (for example, the _package.json_ or _Gemfile_). Without this information {% data variables.product.prodname_dependabot %} cannot create pull requests for version updates. For examples, see [Defining multiple locations for manifest files](/code-security/dependabot/dependabot-version-updates/controlling-dependencies-updated#defining-multiple-locations-for-manifest-files).
@@ -783,128 +852,3 @@ All sensitive data used for authentication should be stored securely and referen
783
852
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.
784
853
785
854
{% data reusables.dependabot.dependabot-replaces-base-nuget %}
Defines a **cooldown period** for dependency updates to delay updates for a configurable number of days. This feature enables {% data variables.product.prodname_dependabot %} users to customize how often they receive new version updates, offering greater control over update frequency.
790
-
791
-
> [!NOTE]
792
-
> Cooldown is not applicable for security updates.
793
-
>
794
-
> Cooldown is not available for the **NuGet** ecosystem
795
-
796
-
### **How Cooldown Works**
797
-
798
-
* When {% data variables.product.prodname_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.
799
-
* 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.
800
-
* Once the cooldown period ends for new version, the dependency update proceeds based on the standard update strategy defined in `dependabot.yml`.
801
-
802
-
Without **`cooldown`** (default behaviour):
803
-
804
-
* Dependabot checks for updates according to the scheduled defined via `schedule.interval`.
805
-
* All new versions are considered for updates **immediately**.
806
-
807
-
With **`cooldown`** enabled:
808
-
809
-
* {% data variables.product.prodname_dependabot %} checks for updates based on the defined `schedule.interval` settings.
810
-
* **Releases within the cooldown period are ignored.**
811
-
* {% data variables.product.prodname_dependabot %} updates the dependency to the latest available version **that are no longer in cooldown period** following the configured `versioning-strategy`.
812
-
813
-
### **Cooldown Configuration**
814
-
815
-
| Parameter | Description |
816
-
|-----------|-------------|
817
-
| `default-days` | **Default cooldown period for dependencies** without specific rules (optional). |
818
-
| `semver-major-days` | Cooldown period for **major version updates** (optional, applies only to SEMVER-supported package managers). |
819
-
| `semver-minor-days` | Cooldown period for **minor version updates** (optional, applies only to SEMVER-supported package managers). |
820
-
| `semver-patch-days` | Cooldown period for **patch version updates** (optional, applies only to SEMVER-supported package managers). |
821
-
| `include` | List of dependencies to **apply cooldown** (up to **150 items**). Supports wildcards (`*`). |
822
-
| `exclude` | List of dependencies **excluded from cooldown** (up to **150 items**). Supports wildcards (`*`). |
823
-
824
-
### **semver versioning**
825
-
826
-
| Package Manager | SEMVER Supported |
827
-
|-----------------------|------------------|
828
-
| **Bundler** | Yes |
829
-
| **Bun** | Yes |
830
-
| **Cargo** | Yes |
831
-
| **Composer** | Yes |
832
-
| **Devcontainers** | No |
833
-
| **Docker** | No |
834
-
| **Docker Compose** | No |
835
-
| **Dotnet SDK** | Yes |
836
-
| **Elm** | Yes |
837
-
| **{% data variables.product.prodname_actions %}** | No |
838
-
| **Gitsubmodule** | No |
839
-
| **Gomod (Go Modules)**| Yes |
840
-
| **Gradle** | Yes |
841
-
| **Helm** | No |
842
-
| **Hex (Hex)** | Yes |
843
-
| **Maven** | Yes |
844
-
| **NPM and Yarn** | Yes |
845
-
| **Pip** | Yes |
846
-
| **Pub** | Yes |
847
-
| **Swift** | Yes |
848
-
| **Terraform** | No |
849
-
| **UV** | Yes |
850
-
851
-
> [!NOTE]
852
-
>
853
-
> * If `semver-major-days`, `semver-minor-days`, or `semver-patch-days` are not defined, `default-days` settings take precedence for cooldown based updates.
854
-
> * `semver-major-days`, `semver-minor-days`, and `semver-patch-days` are only applicable for [supported package managers](#semver-versioning).
855
-
> * 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.
856
-
857
-
### **Cooldown settings limitations**
858
-
859
-
* `days` must be between 1 and 90.
860
-
* Maximum allowed items limit in `include` and `exclude` list is 150 each.
861
-
862
-
### **Example `dependabot.yml` with cooldown**
863
-
864
-
```yaml copy
865
-
version: 2
866
-
updates:
867
-
- package-ecosystem: "pip"
868
-
directory: "/"
869
-
schedule:
870
-
interval: "daily"
871
-
cooldown:
872
-
default-days: 5
873
-
semver-major-days: 30
874
-
semver-minor-days: 7
875
-
semver-patch-days: 3
876
-
include:
877
-
- "requests"
878
-
- "numpy"
879
-
- "pandas*"
880
-
- "django"
881
-
exclude:
882
-
- "pandas"
883
-
```
884
-
885
-
### **Expected Behavior**
886
-
887
-
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.
888
-
889
-
#### **Update days**
890
-
891
-
Updates to new versions for included dependencies will be deferred as following:
892
-
893
-
* **Major updates** → Delayed by **30 days** (`semver-major-days: 30`)
894
-
* **Minor updates** → Delayed by **7 days** (`semver-minor-days: 7`)
895
-
* **Patch updates** → Delayed by **3 days** (`semver-patch-days: 3`)
896
-
897
-
**Wildcard Matching:**
898
-
899
-
* `"pandas*"` applies cooldown to all dependencies that start with `pandas`.
900
-
* `"pandas"` in `exclude` ensures that only `"pandas"` (exact match) is excluded from cooldown.
901
-
902
-
> [!NOTE]
903
-
> To consider all dependencies for cooldown, you can:
904
-
>
905
-
> * Omit the `include` option which applies cooldown to all dependencies.
906
-
> * Use `"*"` in `include` to apply cooldown to everything.
907
-
>
908
-
> Use **only** `exclude` setting if specific dependencies are to be excluded from cooldown.
909
-
910
-
{% data reusables.dependabot.option-affects-security-updates %}