Add documentation for configurable branch name options for pull-request-branch-name (#62394)

Co-authored-by: Laura Coursen <lecoursen@github.com>
Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>

Author: 3 people

content/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/customizing-dependabot-security-prs.md

@@ -76,11 +76,11 @@ To **track progress** towards a project goal or release, use `milestone` to asso
 
 For detailed guidance, see [Associating pull requests with a milestone](/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs#associating-pull-requests-with-a-milestone).
 
-## Changing the separator in the pull request branch name
+## Customizing pull request branch names
 
-To ensure your **branch names align** with your team's existing conventions, use `pull-request-branch-name.separator` to specify the separator you want {% data variables.product.prodname_dependabot %} to use for branch names.
+To ensure your **branch names align** with your team's existing conventions, use `pull-request-branch-name` to customize how {% data variables.product.prodname_dependabot %} generates branch names—including the separator, prefix, length, casing, and format.
 
-For detailed guidance, see [Changing the separator in the pull request branch name](/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs#changing-the-separator-in-the-pull-request-branch-name).
+For detailed guidance, see [Customizing pull request branch names](/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs#customizing-pull-request-branch-names).
 
 ## Example 1: configuration for security updates only
 

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

@@ -621,7 +621,106 @@ Package manager | YAML value      | Supported versions |
 | {% endif %} |
 | yarn         | `npm`            | v1, v2, v3, v4     |
 
-## `pull-request-branch-name.separator` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %}
+## `pull-request-branch-name` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %}
+
+{% ifversion dependabot-branch-name-options %}
+
+Configure how {% data variables.product.prodname_dependabot %} generates branch names for pull requests. You can customize the separator, prefix, length, casing, word separator, and provide a custom template. For examples, see [AUTOTITLE](/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs).
+
+{% data variables.product.prodname_dependabot %} default behavior:
+
+* Generate branch names of the form: `dependabot/PACKAGE-MANAGER/DEPENDENCY`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| [`separator`](#separator) | String | `"/"` | Character used between segments of the branch name. |
+| [`prefix`](#prefix) | String (max 50 characters) | `"dependabot"` | String prepended to the branch name. |
+| [`max-length`](#max-length) | Integer (20–244) | `100` | Maximum character length of the branch name. |
+| [`word-separator`](#word-separator) | String | Not set | Character to replace underscores (`_`) in branch name content after the prefix. |
+| [`branch-name-case`](#branch-name-case) | String | Not set | Apply case transformation to the branch name content after the prefix. |
+| [`template`](#template) | String (max 200 characters) | Not set | Custom format template using placeholders. |
+
+All options are composable. When `template` is set alongside simple options, the processing order is:
+
+1. Template rendering (placeholder substitution)
+1. Separator replacement (`/` replaced with configured separator)
+1. Word-separator replacement (`_` replaced with configured word-separator)
+1. Case transformation applied to content after the prefix
+1. Max-length truncation
+
+### `separator`
+
+Specify a character to use in place of `/` between branch name segments.
+
+Supported values: `"-"`, `_`, `/`
+
+For example, with `separator: "-"`: `dependabot/npm_and_yarn/lodash-4.17.21` becomes `dependabot-npm_and_yarn-lodash-4.17.21`.
+
+> [!TIP]
+> The hyphen symbol must be escaped so it is not interpreted as starting an empty YAML list.
+
+### `prefix`
+
+Specify a custom string to use at the start of the branch name instead of the default `dependabot`.
+
+The value can be up to 50 characters.
+
+For example, with `prefix: "deps"`: `dependabot/npm_and_yarn/lodash-4.17.21` becomes `deps/npm_and_yarn/lodash-4.17.21`.
+
+### `max-length`
+
+Set the maximum allowed length for generated branch names.
+
+* Minimum value: `20`.
+* Maximum value: `244`.
+* Default value: `100`.
+* When a branch name exceeds this limit, it is truncated and a hash suffix is appended to preserve uniqueness.
+
+For example, with `max-length: 40`, a branch name like `dependabot/npm_and_yarn/some-long-dependency-name-1.0.0` is truncated to 40 characters with a hash suffix.
+
+### `word-separator`
+
+Specify a character to replace underscores (`_`) in all branch name content after the prefix—including package manager names, dependency names, group names, and directory paths.
+
+For example, with `word-separator: "-"`:
+
+* `npm_and_yarn` → `npm-and-yarn`
+* `front_end_dir` → `front-end-dir`
+
+### `branch-name-case`
+
+Apply a case transformation to the branch name content after the prefix.
+
+Supported values: `"lowercase"`, `"uppercase"`
+
+For example, with `branch-name-case: "lowercase"`: `dependabot/npm_and_yarn/Lodash-4.17.21` becomes `dependabot/npm_and_yarn/lodash-4.17.21`.
+
+### `template`
+
+Define a custom branch name format using placeholders. The template gives you full control over the structure of generated branch names. For examples, see [AUTOTITLE](/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs).
+
+Available placeholders depend on the update strategy:
+
+| Placeholder | Solo updates | Grouped updates | Multi-ecosystem groups | Description |
+|-------------|:---:|:---:|:---:|-------------|
+| `{prefix}` | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | The configured prefix (default `dependabot`). |
+| `{package_manager}` | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | The package ecosystem identifier (for example, `npm_and_yarn`). |
+| `{directory}` | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | The dependency file directory. |
+| `{target_branch}` | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | The target branch if configured. |
+| `{dependency}` | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "x" aria-label="Not available" %} | The dependency name(s). |
+| `{version}` | {% octicon "check" aria-label="Available" %} | {% octicon "x" aria-label="Not available" %} | {% octicon "x" aria-label="Not available" %} | The new version or ref. |
+| `{group_name}` | {% octicon "x" aria-label="Not available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | The configured group name. |
+| `{name}` | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | {% octicon "check" aria-label="Available" %} | Strategy-appropriate name: dependency and version for solo updates, group name for grouped updates. |
+
+Template validation rules:
+
+* All placeholders must be recognized and allowed for the update strategy in use.
+* Braces must be well-formed (no unclosed `{` or `}`).
+* Using `{package_manager}` in a multi-ecosystem group template raises a validation error because no single package manager applies.
+* The rendered branch name must be a valid Git reference name. Characters such as spaces, `~`, `^`, `:`, `?`, `*`, `[`, and `\` are not allowed, and sequences like `..` or `@{` are rejected.
+* For grouped and multi-ecosystem updates, a 10-character digest is automatically appended to the branch name to guarantee uniqueness. This is not user-controlled.
+
+{% else %}
 
 Specify a separator to use when generating branch names. For examples, see [AUTOTITLE](/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs).
 
@@ -633,11 +732,13 @@ When `pull-request-branch-name.separator` is defined:
 
 * Use the specified character in place of `/`.
 
-Supported values: `"-"`, `_`,  `/`
+Supported values: `"-"`, `_`, `/`
 
 > [!TIP]
 > The hyphen symbol must be escaped so it is not interpreted as starting an empty YAML list.
 
+{% endif %}
+
 ## `rebase-strategy` {% octicon "versions" aria-label="Version updates" height="24" %} {% octicon "shield-check" aria-label="Security updates" height="24" %}
 
 Disable automatic rebasing of pull requests raised by {% data variables.product.prodname_dependabot %}.

content/code-security/tutorials/secure-your-dependencies/customizing-dependabot-prs.md

@@ -212,11 +212,131 @@ updates:
 
 See also [`milestone`](/code-security/reference/supply-chain-security/dependabot-options-reference#milestone--) and [AUTOTITLE](/issues/using-labels-and-milestones-to-track-work/about-milestones).
 
-## Changing the separator in the pull request branch name
+## Customizing pull request branch names
 
 {% data variables.product.prodname_dependabot %} generates a branch for each pull request. Each branch name includes `dependabot`, as well as the name of the package manager and the dependency to be updated. By default, these parts of the branch name are separated by a `/` symbol, for example:
 * `dependabot/npm_and_yarn/next_js/acorn-6.4.1`
 
+{% ifversion dependabot-branch-name-options %}
+
+You can customize branch names using the `pull-request-branch-name` option with the following parameters: `separator`, `prefix`, `max-length`, `word-separator`, `branch-name-case`, and `template`. All options are composable, and you can combine any of them. For the full reference of each parameter, see [`pull-request-branch-name`](/code-security/reference/supply-chain-security/dependabot-options-reference#pull-request-branch-name--).
+
+### Combining formatting options
+
+You can combine `separator`, `word-separator`, `branch-name-case`, `max-length`, and `template` to produce branch names that meet your system's requirements. For example, Docker tag compatibility, Azure Container Registry naming, or Kubernetes branch length limits.
+
+When `template` is set alongside other options, formatting is applied as post-processing after template rendering in this order: separator replacement, word-separator replacement, case transformation, then max-length truncation.
+
+```yaml copy
+# Combine template with formatting options
+
+version: 2
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    pull-request-branch-name:
+      template: "{prefix}/{package_manager}/{dependency}-{version}"
+      separator: "-"
+      word-separator: "-"
+      branch-name-case: "lowercase"
+      max-length: 80
+```
+
+* **Before** (default): `dependabot/npm_and_yarn/Lodash-4.17.21`
+* **After** (with above config): `dependabot-npm-and-yarn-lodash-4.17.21`
+
+When a branch name exceeds `max-length`, it is truncated with a hash suffix to preserve uniqueness.
+
+### Full example with multi-ecosystem groups
+
+The following `dependabot.yml` demonstrates all available options across different ecosystems, including multi-ecosystem group configuration:
+
+```yaml copy
+# Full example demonstrating all branch name options
+
+version: 2
+
+multi-ecosystem-groups:
+  infrastructure:
+    schedule:
+      interval: "weekly"
+    pull-request-branch-name:
+      template: "{prefix}/infra/{name}"
+      word-separator: "-"
+      branch-name-case: "lowercase"
+
+updates:
+  - package-ecosystem: "npm"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    pull-request-branch-name:
+      separator: "-"
+      word-separator: "-"
+      branch-name-case: "lowercase"
+    groups:
+      frontend-deps:
+        patterns: ["react*", "next*"]
+
+  - package-ecosystem: "docker"
+    directory: "/"
+    schedule:
+      interval: "monthly"
+    pull-request-branch-name:
+      template: "{prefix}/{package_manager}/{dependency}-{version}"
+      max-length: 60
+
+  - package-ecosystem: "pip"
+    directory: "/backend"
+    schedule:
+      interval: "weekly"
+    pull-request-branch-name:
+      prefix: "deps"
+      branch-name-case: "lowercase"
+    groups:
+      django-deps:
+        patterns: ["django*"]
+
+  # These entries participate in the "infrastructure" multi-ecosystem group
+  - package-ecosystem: "docker"
+    directory: "/infra"
+    patterns: ["nginx", "redis", "postgres"]
+    multi-ecosystem-group: "infrastructure"
+
+  - package-ecosystem: "terraform"
+    directory: "/infra"
+    patterns: ["hashicorp/*"]
+    multi-ecosystem-group: "infrastructure"
+```
+
+This configuration produces the following branch names:
+
+| Scenario | Strategy | Branch name |
+|----------|----------|-------------|
+| lodash npm update | Solo | `dependabot-npm-and-yarn-lodash-4.17.21` |
+| npm frontend-deps group update | Grouped | `dependabot-npm-and-yarn-frontend-deps-fc93691fd4` |
+| nginx solo Docker update | Solo | `dependabot/docker/nginx-1.25.0` |
+| pip Django update | Solo | `deps/pip/django-4.2.1` |
+| pip django-deps group update | Grouped | `deps/pip/django-deps-a1b2c3d4e5` |
+| Cross-ecosystem infrastructure group (Docker + Terraform) | Multi-ecosystem | `dependabot/infra/infrastructure-fc93691fd4` |
+
+> [!NOTE]
+> For multi-ecosystem groups:
+> * The `pull-request-branch-name` on the `multi-ecosystem-groups` entry controls the grouped cross-ecosystem PR branch name.
+> * Individual `updates` entries that specify `multi-ecosystem-group` **cannot** have their own `pull-request-branch-name`. The group-level configuration takes precedence and is the only one used for those entries.
+> * `{package_manager}` is not available in multi-ecosystem group templates because the group spans multiple ecosystems.
+> * A content digest is always auto-appended to multi-ecosystem group branches to guarantee uniqueness.
+
+### How branch name configuration applies
+
+* **Configuration is per-update entry**: Each standalone `package-ecosystem` entry can have its own branch name configuration. Entries assigned to a multi-ecosystem group use the group-level configuration instead.
+* **Existing PRs are not affected**: Changes only apply to newly created PRs.
+* **Default behavior is unchanged**: If you don't configure any options, branch names remain exactly as they are today.
+
+{% else %}
+
 To maintain supportability or consistency with your existing processes, you may need to ensure your branch names align with your team's existing conventions. In this case, you can use `pull-request-branch-name.separator` to specify a different separator, choosing either `_`, `/`, or `"-"`.
 
 In the below example, the npm configuration changes the default separator from `/` to `"-"`, so that it would appear as such:
@@ -235,13 +355,12 @@ updates:
     schedule:
       interval: "weekly"
     pull-request-branch-name:
-      # Change the default separator (/) to a hyphen (-)
       separator: "-"
 ```
 
-{% data reusables.dependabot.option-affects-security-updates %}
+{% endif %}
 
-See also [`pull-request-branch-name.separator`](/code-security/reference/supply-chain-security/dependabot-options-reference#pull-request-branch-nameseparator--).
+{% data reusables.dependabot.option-affects-security-updates %}
 
 ## Targeting pull requests against a non-default branch
 

data/features/dependabot-branch-name-options.yml

@@ -0,0 +1,6 @@
+# Reference: Configurable branch name format options for Dependabot
+# Options: prefix, max-length, word-separator, branch-name-case, template
+versions:
+  fpt: '*'
+  ghec: '*'
+  ghes: '> 3.22'