Merge branch 'main' into casey/helm-versioning-strategy

Author: casey-robertson-paypal

.github/workflows/purge-fastly.yml

@@ -1,18 +1,15 @@
 name: Purge Fastly
 
-# **What it does**: Purges Fastly after a deploy and on demand. Soft purge by
-#   default; can hard purge specific languages, or hard purge the ENTIRE cache.
-# **Why we have it**: So that, right after a production deploy, we start afresh,
-#   and so docs engineering can clear a bad cache state without the Fastly UI.
-# **Who does it impact**: Writers and engineers. A full purge impacts all readers,
-#   origin sees a traffic spike while the cache refills, so it's gated below.
+# **What it does**:
+#   On production deploy, hard-purge the changed English content pages by key.
+#   On demand, soft or hard purge language keys, a single key, or entire cache.
+# **Why we have it**: So a just-deployed change is visible right away, and so
+#   docs engineering can clear a bad cache state without the Fastly UI.
+# **Who does it impact**: Writers and engineers. A full purge impacts all readers
+#   and spikes origin traffic while the cache refills, so it's gated below.
 
 on:
   deployment_status:
-  schedule:
-    # Daily soft purge of all languages to catch reusables and AUTOTITLE links.
-    # Intentionally off-peak, around 6-7pm PT.
-    - cron: '20 2 * * *'
   workflow_dispatch:
     inputs:
       languages:
@@ -89,26 +86,22 @@ jobs:
             exit 1
           fi
 
-      - name: Purge Fastly
-        # Auto post-deploy runs wait for the build, purge English only (temporary),
-        # and stay soft. The daily scheduled run waits for nothing, purges all
-        # languages (blank = all), and stays soft. A manual run uses the inputs:
-        # blank languages = all, the `hard` toggle, or a confirmed full-cache purge.
-        #
+      - name: Wait for production to serve this build
+        if: ${{ github.event_name == 'deployment_status' }}
+        run: npm run wait-for-build
+
+      - name: Purge Fastly (manual)
         # Raw inputs are passed through the environment and quoted, never spliced
         # into the command string, so a value like `en' --everything` can't break
         # out of its argument and inject another flag.
+        if: ${{ github.event_name == 'workflow_dispatch' }}
         env:
-          EVENT_NAME: ${{ github.event_name }}
           LANGUAGES_INPUT: ${{ inputs.languages }}
           HARD_INPUT: ${{ inputs.hard }}
           EVERYTHING_INPUT: ${{ inputs.everything }}
         run: |
           args=()
-          if [ "$EVENT_NAME" = "deployment_status" ]; then
-            args+=(--wait-for-build)
-            args+=(--languages en)
-          elif [ -n "$LANGUAGES_INPUT" ]; then
+          if [ -n "$LANGUAGES_INPUT" ]; then
             args+=(--languages "$LANGUAGES_INPUT")
           fi
           if [ "$HARD_INPUT" = "true" ]; then
@@ -119,14 +112,9 @@ jobs:
           fi
           npm run purge-fastly -- "${args[@]}"
 
-      - name: Hard-purge changed English content URLs
-        # Prod deploys only. The soft purge above just marks `language:en` stale,
-        # so stale-while-revalidate can keep serving the pre-deploy copy of a
-        # just-changed page for a while. This evicts the specific English URLs
-        # whose content/ files changed in this deploy, so the next request fetches
-        # fresh. By the time the deploy succeeds the old pods are already gone, so
-        # the refill is deterministically the new content. data/ changes stay
-        # covered by the soft purge above (too many URLs to enumerate cheaply).
+      - name: Hard-purge changed English content pages
+        # On prod deploys, evict the surrogate keys of the English content pages
+        # whose content/ files changed in this deploy.
         if: ${{ github.event_name == 'deployment_status' }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

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