Dependabot can group updates by dependency name across multiple directories in a monorepo [GA] (#59726)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: mchammer01

content/code-security/reference/supply-chain-security/dependabot-options-reference.md

@@ -281,8 +281,11 @@ Parameters | Purpose |
 | `IDENTIFIER` | Define an identifier for the group to use in branch names and pull request titles. This must start and end with a letter, and can contain letters, pipes `\|`, underscores `_`, or hyphens `-`. |
 | `applies-to` | Specify which type of update the group applies to. When undefined, defaults to version updates. Supported values: `version-updates` or `security-updates`. |
 | `dependency-type` | Limit the group to a type. Supported values: `development` or `production`. |
-| `patterns` | Define one or more patterns to include dependencies with matching names. |
 | `exclude-patterns` | Define one or more patterns to exclude dependencies from the group. |
+| {% ifversion dependabot-updates-group-by %} |
+| `group-by` | Group updates across multiple directories. Supported value: `dependency-name`. |
+| {% endif %} |
+| `patterns` | Define one or more patterns to include dependencies with matching names. |
 | `update-types` | Limit the group to one or more semantic versioning levels. Supported values: `minor`, `patch`, and `major`. |
 
 ### `dependency-type` (`groups`)
@@ -294,6 +297,29 @@ By default, a group will include all types of dependencies.
 * Use `development` to include only dependencies in the "Development dependency group."
 * Use `production` to include only dependencies in the "Production dependency group."
 
+{% ifversion dependabot-updates-group-by %}
+
+### `group-by` (`groups`)
+
+Use `groups.<group-name>.group-by` to specify how {% data variables.product.prodname_dependabot %} should group updates across multiple directories in a monorepo.
+
+* **Type:** String
+* **Accepted values:** `dependency-name`
+* **Applies to:** Configurations with multiple directories specified
+
+When set to `dependency-name`, {% data variables.product.prodname_dependabot %} will create a single pull request for each dependency update across all specified directories, rather than separate pull requests per directory.
+
+**Limitations of cross-directory grouping**
+
+When using `group-by: dependency-name`:
+* All directories must use the same package ecosystem (for example, all `npm` or all `bundler`)
+* Applies to **version updates only**
+* If directories have incompatible version constraints for a dependency, {% data variables.product.prodname_dependabot %} will create separate pull requests
+
+For examples showing the use of `group-by`, see [AUTOTITLE](/code-security/tutorials/secure-your-dependencies/optimizing-pr-creation-version-updates#grouping-updates-across-directories-in-a-monorepo).
+
+{% endif %}
+
 ### `patterns` and `exclude-patterns` (`groups`)
 
 Both options support using `*` as a wild card to define matches with dependency names. If a dependency matches both a pattern and an exclude-pattern, then it is excluded from the group.

content/code-security/tutorials/secure-your-dependencies/optimizing-pr-creation-version-updates.md

@@ -110,6 +110,8 @@ See also [`cooldown`](/code-security/dependabot/working-with-dependabot/dependab
 
 ## Prioritizing meaningful updates
 
+### Grouping related dependencies together
+
 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.
 
 You must configure groups per individual package ecosystem, then you can create multiple groups per package ecosystem using a combination of criteria:
@@ -124,3 +126,36 @@ To see all supported values for each criterion, see [`groups`](/code-security/de
 The below examples present several different methods to create groups of dependencies using the criteria.
 
 {% data reusables.dependabot.dependabot-version-updates-groups-yaml-example %}
+
+{% ifversion dependabot-updates-group-by %}
+
+### Grouping updates across directories in a monorepo
+
+If you manage a monorepo with multiple directories that share common dependencies, you can reduce the number of pull requests for version updates by grouping updates by dependency name across all directories.
+
+When you configure {% data variables.product.prodname_dependabot %} to monitor multiple directories and enable grouping by dependency name, {% data variables.product.prodname_dependabot %} will:
+* Create a single pull request for each dependency update that affects multiple directories
+* Update the same dependency to the same version across all directories in one operation
+* Reduce the number of pull requests you need to review
+* Minimize CI/CD costs by running tests once instead of per directory
+
+For more information, see [`group-by`](/code-security/reference/supply-chain-security/dependabot-options-reference#group-by-groups).
+
+This configuration example groups updates by dependency name across the `/frontend`, `/admin-panel`, and `/mobile-app` directories. If `lodash` needs to be updated in all three directories, {% data variables.product.prodname_dependabot %} will create a single pull request named "Bump lodash in monorepo-dependencies group" that updates `lodash` in all three locations.
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directories:
+      - "/frontend"
+      - "/admin-panel"
+      - "/mobile-app"
+    schedule:
+      interval: "weekly"
+    groups:
+      monorepo-dependencies:
+        group-by: dependency-name
+```
+
+{% endif %}

data/features/dependabot-updates-group-by.yml

@@ -0,0 +1,5 @@
+# Reference: Issue #20890 - Dependabot can group updates by dependency name across multiple directories in a monorepo [GA]
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '>= 3.21'