Merge branch 'main' into handsomely-lighter

Author: reakaleek

config/changelog.example.yml

@@ -212,9 +212,13 @@ bundle:
   output_directory: docs/releases
   # Whether to resolve (copy contents) by default
   resolve: true
-  # When true, PR/issue links to repos marked private in assembler.yml are rewritten in bundle output
-  # (requires resolve: true). Option-based: --sanitize-private-links / --no-sanitize-private-links.
-  sanitize_private_links: false
+  # PR/issue link allowlist: when set (including []), only links to these owner/repo pairs are kept
+  # in bundle output; others are rewritten to '# PRIVATE:' sentinels (requires resolve: true).
+  # When omitted, no link filtering is applied.
+  # Add your repository and any others whose PR/issue links should appear in published docs.
+  # link_allow_repos:
+    # - elastic/elasticsearch
+    # - elastic/kibana
   # Optional: default GitHub repo name applied to all profiles that do not specify their own.
   # Used by the {changelog} directive to generate correct PR/issue links when the product ID
   # differs from the GitHub repository name. Can be overridden per profile.
@@ -238,9 +242,6 @@ bundle:
     #   output: "elasticsearch-{version}.yaml"
     #   # Optional: override the products array written to the bundle output.
     #   # output_products: "elasticsearch {version}"
-    #   # Optional: override bundle.sanitize_private_links for this profile only (requires bundle.resolve: true).
-    #   sanitize_private_links: true
-
     # Example: GitHub release profile (fetches PR list directly from a GitHub release)
     # Use when you want to bundle or remove changelogs based on a published GitHub release.
     # elasticsearch-gh-release:

config/versions.yml

@@ -3,7 +3,7 @@ versioning_systems:
   # Updates for Stack versions are manual
   stack: &stack
     base: 9.0
-    current: 9.3.2
+    current: 9.3.3
 
   # Using an unlikely high version
   # So that our logic that would display "planned" doesn't trigger

docs/changelog/changelog-private-link-sanitization.yaml

@@ -1,5 +1,5 @@
 type: feature
-title: Add bundle-time private link sanitization and changelog directive link visibility
+title: Add bundle-time link allowlist for PR and issue references
 products:
   - product: docs-builder
     target: 0.100.0
@@ -9,7 +9,8 @@ areas:
 prs:
   - https://github.com/elastic/docs-builder/pull/3002
 description: |
-  Adds opt-in `bundle.sanitize_private_links` in changelog configuration (and per-profile override),
-  with `--sanitize-private-links` and `--no-sanitize-private-links` on option-based changelog bundle.
-  Rewrites PR/issue references targeting private `assembler.yml` repos to quoted `# PRIVATE` sentinels
-  when resolve is true. The `{changelog}` directive gains `:link-visibility:` (`auto`, `keep-links`, `hide-links`).
+  Replaces `bundle.sanitize_private_links` with explicit `bundle.link_allow_repos` (`owner/repo` list).
+  When set (including an empty list), PR/issue references not in the allowlist are rewritten to quoted
+  `# PRIVATE:` sentinels when the bundle is resolved. `bundle.repo` must be a single repository (no `+` syntax).
+  Optional assembler.yml warnings when an allowlisted repo is missing or marked private.
+  The `{changelog}` directive retains `:link-visibility:` (`auto`, `keep-links`, `hide-links`).

docs/cli/changelog/add.md

@@ -137,13 +137,20 @@ When running inside GitHub Actions, `changelog add` automatically reads the foll
 | --- | --- | --- |
 | `CHANGELOG_PR_NUMBER` | `--prs` | `github.event.pull_request.number` |
 | `CHANGELOG_TITLE` | `--title` | `steps.evaluate.outputs.title` |
+| `CHANGELOG_DESCRIPTION` | `--description` | `steps.evaluate.outputs.description` |
 | `CHANGELOG_TYPE` | `--type` | `steps.evaluate.outputs.type` |
 | `CHANGELOG_PRODUCTS` | `--products` | `steps.evaluate.outputs.products` |
 | `CHANGELOG_OWNER` | `--owner` | `github.repository_owner` |
 | `CHANGELOG_REPO` | `--repo` | `github.event.repository.name` |
 
 **Precedence**: explicit CLI arguments always take priority over environment variables. Environment variables are only used when the corresponding CLI argument is not provided.
 
+`CHANGELOG_DESCRIPTION` has additional precedence rules related to release note extraction:
+
+- If `--description` is provided on the command line, it always wins.
+- If `--no-extract-release-notes` is passed (or `extract.release_notes: false` is set in the changelog configuration), `CHANGELOG_DESCRIPTION` is ignored. This prevents a description that was extracted by `evaluate-pr` from being applied when extraction has been disabled.
+- Otherwise, `CHANGELOG_DESCRIPTION` fills `--description` when it is not set on the command line.
+
 The filename strategy is controlled by the `filename` option in `changelog.yml` (defaulting to `timestamp`). Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) for details.
 
 This allows the CI action to invoke `changelog add` with a minimal command line:

docs/cli/changelog/bundle.md

@@ -97,9 +97,6 @@ The `--input-products` option determines which changelog files are gathered for
 :   Each occurrence can be either comma-separated issues ( `--issues "https://github.com/owner/repo/issues/123,456"`) or a file path (for example `--issues /path/to/file.txt`).
 :   When using a file, every line must be a fully-qualified GitHub issue URL such as `https://github.com/owner/repo/issues/123`. Bare numbers and short forms are not allowed in files.
 
-`--no-sanitize-private-links`
-:   Optional: Explicitly turn off the `sanitize_private_links` option if it's specified in the changelog configuration file.
-
 `--no-resolve`
 :   Optional: Explicitly turn off the `resolve` option if it's specified in the changelog configuration file.
 
@@ -140,13 +137,6 @@ The `--input-products` option determines which changelog files are gathered for
 :   Optional: Copy the contents of each changelog file into the entries array.
 :   By default, the bundle contains only the file names and checksums.
 
-`--sanitize-private-links`
-:   Optional: Turn on [private link sanitization](#private-link-sanitization).
-:   Pull requests and issues that target repositories marked `private: true` in the `references` section of `assembler.yml` are rewritten as quoted `# PRIVATE:` sentinel strings in the bundle file.
-:   This option requires a resolved bundle: use `--resolve` or set `bundle.resolve: true` in the `changelog.yml`.
-:   If sanitization is enabled and the bundle is not resolved, the command fails.
-:   When you omit this option, it defaults to `bundle.sanitize_private_links` in your changelog configuration file, which defaults to `false`.
-
 ## Output files
 
 Both modes use the same ordered fallback to determine where to write the bundle. The first value that is set wins:
@@ -284,27 +274,26 @@ rules:
           - "Monitoring"
 ```
 
-## Private link sanitization [private-link-sanitization]
+## PR and issue link allowlist [link-allowlist]
 
-A changelog in a public repository might contain links to pull requests or issues in private repositories.
-To prevent that information from appearing in the documentation, use `bundle.sanitize_private_links` in the changelog configuration file (or a product-specific profile override) or the `--sanitize-private-links` command option.
+A changelog in a public repository might contain links to pull requests or issues in repositories that should not appear in published documentation.
 
-This feature relies on the [`assembler.yml`](/configure/site/content.md) file and the existence of `private: true` to determine which repo links should be sanitized.
-Every repository that appears in a PR or issue link must be listed under `assembler.yml` `references`. References to unknown repositories fail the command so you can fix the registry.
-Repos are assumed to be `private: false` unless you specify otherwise.
+Set `bundle.link_allow_repos` in `changelog.yml` to an explicit list of `owner/repo` strings (for example, `elastic/elasticsearch`). When this key is present (including as an empty list), PR and issue references are filtered at bundle time: only links whose resolved repository is in the list are kept; others are rewritten to quoted `# PRIVATE:` sentinel strings in the bundle YAML.
 
 :::{important}
-When you use these options, you must also set `bundle.resolve: true` or specify `--resolve`.
-Unresolved bundles that only store `file:` pointers do not get this rewrite; if you need private link sanitization, you must use a resolved bundle.
+`bundle.link_allow_repos` requires a **resolved** bundle. Set `bundle.resolve: true` or pass `--resolve`. Unresolved bundles that only store `file:` pointers are not rewritten.
 :::
 
-The `changelog bundle`, `changelog gh-release`, and `changelog bundle-amend` commands rewrite PR and issue references that **target** private repositories into quoted sentinel strings such as `"# PRIVATE: …"` in the bundle file.
-The changelog directive and `changelog render` command then omit these sentinels from the documentation.
+When [`assembler.yml`](/configure/site/content.md) is available, docs-builder emits **warnings** (non-fatal) if an allowlisted repo is missing from `references` or is marked `private: true`, so you can verify the registry before publishing.
+
+The `changelog bundle`, `changelog gh-release`, and `changelog bundle-amend` commands apply the same rules. The changelog directive and `changelog render` command omit `# PRIVATE:` sentinels from rendered documentation.
 
 :::{warning}
 Sentinel values are omitted from rendered documentation but remain in bundle files; they are not cryptographic redaction.
 :::
 
+`bundle.repo` must name a **single** GitHub repository (do not use `repo1+repo2` merged-repo syntax).
+
 ## Option-based examples
 
 ### Bundle by report or URL list

docs/cli/changelog/evaluate-pr.md

@@ -66,6 +66,7 @@ docs-builder changelog evaluate-pr [options...] [-h|--help]
 | `should-generate` | `true` if `changelog add` should run |
 | `should-upload` | `true` if the artifact should be uploaded |
 | `title` | Resolved PR title |
+| `description` | Release note extracted from the PR body (when `extract.release_notes` is enabled and a release note is found). Long or multi-line release notes (>120 characters) are placed here. Passed downstream as `CHANGELOG_DESCRIPTION` for `changelog add`. |
 | `type` | Resolved changelog type |
 | `products` | Comma-separated product specs resolved from PR labels via `pivot.products` mappings (e.g., `cloud-hosted, cloud-serverless`) |
 | `label-table` | Markdown table of configured label-to-type mappings |

docs/contribute/changelog.md

@@ -363,6 +363,17 @@ Ideally this task will be automated such that it's performed by a bot or GitHub
 If you run it from the command line, you must precede any special characters (such as backquotes) with a backslash escape character (`\`).
 :::
 
+### CI two-step flow
+
+When automated via the [changelog GitHub Actions](https://github.com/elastic/docs-actions/tree/main/changelog), changelog creation is a two-step process:
+
+1. **`changelog evaluate-pr`** inspects the PR (title, labels, body) and produces outputs such as `title`, `type`, `description`, and `products`.
+2. **`changelog add`** reads those outputs from `CHANGELOG_*` environment variables and generates the changelog YAML file.
+
+The `description` output from step 1 contains the release note extracted from the PR body (when `extract.release_notes` is enabled). If extraction is disabled — either by setting `extract.release_notes: false` in `changelog.yml` or by passing `--no-extract-release-notes` to `changelog add` — the `CHANGELOG_DESCRIPTION` environment variable is ignored and the extracted description is not written to the changelog.
+
+Refer to [CI auto-detection](/cli/changelog/add.md#ci-auto-detection) for the full list of environment variables and precedence rules.
+
 For up-to-date command usage information, use the `-h` option or refer to [](/cli/changelog/add.md).
 
 ### Authorization
@@ -713,8 +724,8 @@ Top-level `bundle` fields:
 |---|---|
 | `repo` | Default GitHub repository name applied to all profiles. Falls back to product ID if not set at any level. |
 | `owner` | Default GitHub repository owner applied to all profiles. |
-| `resolve` | When `true`, embeds full changelog entry content in the bundle (same as `--resolve`). Required when `sanitize_private_links` is enabled. |
-| `sanitize_private_links` | When `true`, rewrites PR/issue references that target private repositories (per `assembler.yml` `references`) to quoted `# PRIVATE:` sentinel strings in bundle YAML. Requires `resolve: true` and a non-empty `references` section in `assembler.yml`. Default `false`. Refer to  [Private link sanitization at bundle time](/cli/changelog/bundle.md#private-link-sanitization). |
+| `resolve` | When `true`, embeds full changelog entry content in the bundle (same as `--resolve`). Required when `link_allow_repos` is set. |
+| `link_allow_repos` | When set (including an empty list), only PR/issue links whose resolved repository is in this `owner/repo` list are kept; others are rewritten to `# PRIVATE:` sentinels in bundle YAML. When absent, no link filtering is applied. Requires `resolve: true`. Refer to [PR and issue link allowlist](/cli/changelog/bundle.md#link-allowlist). |
 
 Profile configuration fields in `bundle.profiles`:
 
@@ -727,7 +738,6 @@ Profile configuration fields in `bundle.profiles`:
 | `repo` | Optional. Overrides `bundle.repo` for this profile only. Required when `source: github_release` is used and no `bundle.repo` is set. |
 | `owner` | Optional. Overrides `bundle.owner` for this profile only. |
 | `hide_features` | List of feature IDs to embed in the bundle as hidden. |
-| `sanitize_private_links` | Optional. Overrides `bundle.sanitize_private_links` for this profile. |
 
 Example profile configuration:
 
@@ -1048,7 +1058,7 @@ The `--hide-features` option on the `render` command and the `hide-features` fie
 
 A changelog can reference multiple pull requests and issues in the `prs` and `issues` array fields.
 
-To comment out the private links in all changelogs in your bundles, refer to [changelog bundle](/cli/changelog/bundle.md#private-link-sanitization).
+To comment out links that are not in your allowlist in all changelogs in your bundles, refer to [changelog bundle](/cli/changelog/bundle.md#link-allowlist).
 
 If you are working in a private repo and do not want any pull request or issue links to appear (even if they target a public repo), you also have the option to configure link visibiblity in the [changelog directive](/syntax/changelog.md) and [changelog render](/cli/changelog/render.md) command.
 
@@ -1296,7 +1306,7 @@ docs-builder changelog remove elasticsearch-release 9.2.0 --dry-run
 The command automatically discovers `changelog.yml` by checking `./changelog.yml` then `./docs/changelog.yml` relative to your current directory.
 If no configuration file is found, the command returns an error with advice to create one or to run from the directory where the file exists.
 
-The `output`, `output_products`, `hide_features`, `sanitize_private_links`, and `resolve` fields are bundle-specific and are always ignored for removal (along with other bundle-only settings that do not affect which changelog files match the filter).
+The `output`, `output_products`, `hide_features`, `link_allow_repos`, and `resolve` fields are bundle-specific and are always ignored for removal (along with other bundle-only settings that do not affect which changelog files match the filter).
 Which other fields are used depends on the profile type:
 
 - Standard profiles: only the `products` field is used. The `repo` and `owner` fields are ignored (they only affect bundle output metadata).

src/Elastic.Documentation.Configuration/Changelog/BundleConfiguration.cs

@@ -39,10 +39,11 @@ public record BundleConfiguration
 	public string? Owner { get; init; }
 
 	/// <summary>
-	/// When true, PR/issue references targeting repositories marked <c>private: true</c> in
-	/// <c>assembler.yml</c> are rewritten to sentinel values at bundle time (requires <see cref="Resolve"/>).
+	/// When set (including an empty list), PR/issue references whose resolved <c>owner/repo</c> is not listed
+	/// are rewritten to <c># PRIVATE:</c> sentinels at bundle time. When absent, no link filtering is applied.
+	/// Requires <see cref="Resolve"/>.
 	/// </summary>
-	public bool SanitizePrivateLinks { get; init; }
+	public IReadOnlyList<string>? LinkAllowRepos { get; init; }
 
 	/// <summary>
 	/// Named bundle profiles for different release scenarios.
@@ -104,9 +105,4 @@ public record BundleProfile
 	/// Mutually exclusive with <see cref="Products"/>.
 	/// </summary>
 	public string? Source { get; init; }
-
-	/// <summary>
-	/// When set, overrides <see cref="BundleConfiguration.SanitizePrivateLinks"/> for this profile.
-	/// </summary>
-	public bool? SanitizePrivateLinks { get; init; }
 }