Handle extract.release_notes properly on CI (#3047)

* Handle extract.release_notes

* Update docs/contribute/changelog.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Add explicit extraction state property

* Add further testing for extraction behavior gaps

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: cotti

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/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

src/services/Elastic.Changelog/Creation/ChangelogCreationService.cs

@@ -44,6 +44,9 @@ public record CreateChangelogArguments
 	/// </summary>
 	public bool? ExtractReleaseNotes { get; init; }
 
+	/// <summary>null and true both mean enabled; only explicit false disables extraction.</summary>
+	public bool ExtractionDisabled => ExtractReleaseNotes == false;
+
 	/// <summary>
 	/// Whether to extract linked issues/PRs from PR/issue body. null = use config default.
 	/// </summary>
@@ -79,6 +82,7 @@ public async Task<bool> CreateChangelog(IDiagnosticsCollector collector, CreateC
 	{
 		try
 		{
+			var cliDescription = input.Description;
 			input = EnrichFromCI(input);
 
 			// Load changelog configuration
@@ -92,6 +96,16 @@ public async Task<bool> CreateChangelog(IDiagnosticsCollector collector, CreateC
 			// Apply config defaults to input (for extract_release_notes, extract_issues)
 			input = ApplyConfigDefaults(input, config);
 
+			// When extraction is disabled (by CLI or config), discard any CI-injected description
+			// that originated from evaluate-pr's release-note extraction.
+			if (input.ExtractionDisabled
+				&& string.IsNullOrWhiteSpace(cliDescription)
+				&& !string.IsNullOrWhiteSpace(input.Description))
+			{
+				_logger.LogInformation("Clearing CI-provided description because release note extraction is disabled");
+				input = input with { Description = null };
+			}
+
 			// Multiple PRs: one changelog per PR (--use-pr-number uses PR number as each filename)
 			if (input.Prs != null && input.Prs.Length > 1)
 				return await CreateChangelogsForMultiplePrsAsync(collector, input, config, ctx);
@@ -412,11 +426,15 @@ internal CreateChangelogArguments EnrichFromCI(CreateChangelogArguments input)
 			? input.Products
 			: ProductArgument.ParseProductSpecs(ciProducts);
 
+		var enrichedDescription = !string.IsNullOrWhiteSpace(input.Description)
+			? input.Description
+			: input.ExtractionDisabled ? null : ciDescription;
+
 		return input with
 		{
 			Prs = enrichedPrs,
 			Title = !string.IsNullOrWhiteSpace(input.Title) ? input.Title : ciTitle,
-			Description = !string.IsNullOrWhiteSpace(input.Description) ? input.Description : ciDescription,
+			Description = enrichedDescription,
 			Type = !string.IsNullOrWhiteSpace(input.Type) ? input.Type : ciType,
 			Owner = input.Owner ?? ciOwner,
 			Repo = !string.IsNullOrWhiteSpace(input.Repo) ? input.Repo : ciRepo,

tests/Elastic.Changelog.Tests/Changelogs/Create/CreateChangelogTestBase.cs

@@ -13,8 +13,8 @@ public abstract class CreateChangelogTestBase(ITestOutputHelper output) : Change
 {
 	protected IGitHubPrService MockGitHubService { get; } = A.Fake<IGitHubPrService>();
 
-	protected ChangelogCreationService CreateService() =>
-		new(LoggerFactory, ConfigurationContext, MockGitHubService, FileSystem);
+	protected ChangelogCreationService CreateService(IEnvironmentVariables? env = null) =>
+		new(LoggerFactory, ConfigurationContext, MockGitHubService, FileSystem, env);
 
 	protected async Task<string> CreateConfigDirectory(string configContent)
 	{