Update changelog to pull from PR (#2338)

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>

Author: lcawl

config/changelog.yml.example

@@ -54,3 +54,25 @@ available_products:
   - cloud-enterprise
   # Add more products as needed
 
+# GitHub label mappings (optional - used when --pr option is specified)
+# Maps GitHub PR labels to changelog type values
+# When a PR has a label that matches a key, the corresponding type value is used
+label_to_type:
+  # Example mappings - customize based on your label naming conventions
+  # "type:feature": feature
+  # "type:bug": bug-fix
+  # "type:enhancement": enhancement
+  # "type:breaking": breaking-change
+  # "type:security": security
+
+# Maps GitHub PR labels to changelog area values
+# Multiple labels can map to the same area, and a single label can map to multiple areas (comma-separated)
+label_to_areas:
+  # Example mappings - customize based on your label naming conventions
+  # "area:search": search
+  # "area:security": security
+  # "area:ml": machine-learning
+  # "area:observability": observability
+  # "area:index": index-management
+  # "area:multiple": "search, security"  # Multiple areas comma-separated
+

docs/cli/release/changelog-add.md

@@ -38,20 +38,30 @@ docs-builder changelog add [options...] [-h|--help]
 `--output <string?>`
 :   Optional: Output directory for the changelog fragment. Defaults to current directory.
 
+`--owner <string?>`
+:   Optional: GitHub repository owner (used when `--pr` is just a number).
+
 `--products <List<ProductInfo>>`
 :   Required: Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`).
 :   The valid product identifiers are listed in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
 :   The valid lifecycles are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
 
 `--pr <string?>`
-:   Optional: Pull request number.
+:   Optional: Pull request URL or number (if `--owner` and `--repo` are provided).
+:   If specified, `--title` can be derived from the PR.
+:   If mappings are configured, `--areas` and `--type` can also be derived from the PR.
+
+`--repo <string?>`
+:   Optional: GitHub repository name (used when `--pr` is just a number).
 
 `--subtype <string?>`
 :   Optional: Subtype for breaking changes (for example, `api`, `behavioral`, or `configuration`).
 :   The valid subtypes are listed in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
 
 `--title <string>`
-:    Required: A short, user-facing title (max 80 characters)
+:    A short, user-facing title (max 80 characters)
+:    Required if `--pr` is not specified.
+:    If both `--pr` and `--title` are specified, the latter value is used instead of what exists in the PR.
 
 `--type <string>`
 :   Required: Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).

docs/contribute/changelog.md

@@ -25,20 +25,22 @@ Usage: changelog add [options...] [-h|--help] [--version]
 Add a new changelog fragment from command-line input
 
 Options:
-  --title <string>                  Required: A short, user-facing title (max 80 characters) (Required)
-  --type <string>                   Required: Type of change (feature, enhancement, bug-fix, breaking-change, etc.) (Required)
-  --products <List<ProductInfo>>    Required: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05") (Required)
-  --subtype <string?>               Optional: Subtype for breaking changes (api, behavioral, configuration, etc.) (Default: null)
-  --areas <string[]?>               Optional: Area(s) affected (comma-separated or specify multiple times) (Default: null)
-  --pr <string?>                    Optional: Pull request URL (Default: null)
-  --issues <string[]?>              Optional: Issue URL(s) (comma-separated or specify multiple times) (Default: null)
-  --description <string?>           Optional: Additional information about the change (max 600 characters) (Default: null)
-  --impact <string?>                Optional: How the user's environment is affected (Default: null)
-  --action <string?>                Optional: What users must do to mitigate (Default: null)
-  --feature-id <string?>            Optional: Feature flag ID (Default: null)
-  --highlight <bool?>               Optional: Include in release highlights (Default: null)
-  --output <string?>                Optional: Output directory for the changelog fragment. Defaults to current directory (Default: null)
-  --config <string?>                Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' (Default: null)
+  --products <List<ProductInfo>>    Required: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05") [Required]
+  --title <string?>                 Optional: A short, user-facing title (max 80 characters). Required if --pr is not specified. If --pr and --title are specified, the latter value is used instead of what exists in the PR. [Default: null]
+  --type <string?>                  Optional: Type of change (feature, enhancement, bug-fix, breaking-change, etc.). Required if --pr is not specified. If mappings are configured, type can be derived from the PR. [Default: null]
+  --subtype <string?>               Optional: Subtype for breaking changes (api, behavioral, configuration, etc.) [Default: null]
+  --areas <string[]?>               Optional: Area(s) affected (comma-separated or specify multiple times) [Default: null]
+  --pr <string?>                    Optional: Pull request URL or PR number (if --owner and --repo are provided). If specified, --title can be derived from the PR. If mappings are configured, --areas and --type can also be derived from the PR. [Default: null]
+  --owner <string?>                 Optional: GitHub repository owner (used when --pr is just a number) [Default: null]
+  --repo <string?>                  Optional: GitHub repository name (used when --pr is just a number) [Default: null]
+  --issues <string[]?>              Optional: Issue URL(s) (comma-separated or specify multiple times) [Default: null]
+  --description <string?>           Optional: Additional information about the change (max 600 characters) [Default: null]
+  --impact <string?>                Optional: How the user's environment is affected [Default: null]
+  --action <string?>                Optional: What users must do to mitigate [Default: null]
+  --feature-id <string?>            Optional: Feature flag ID [Default: null]
+  --highlight <bool?>               Optional: Include in release highlights [Default: null]
+  --output <string?>                Optional: Output directory for the changelog fragment. Defaults to current directory [Default: null]
+  --config <string?>                Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml' [Default: null]
 ```
 
 ### Product format
@@ -76,22 +78,32 @@ If a configuration file exists, the command validates all its values before gene
 - If the configuration file contains `lifecycle`, `product`, `subtype`, or `type` values that don't match the values in `products.yml` and `ChangelogConfiguration.cs`, validation fails. The changelog file is not created.
 - If the configuration file contains `areas` values and they don't match what you specify in the `--areas` command option, validation fails. The changelog file is not created.
 
+### GitHub label mappings
+
+You can optionally add `label_to_type` and `label_to_areas` mappings in your changelog configuration.
+When you run the command with the `--pr` option, it can use these mappings to fill in the `type` and `areas` in your changelog based on your pull request labels.
+
+Refer to [changelog.yml.example](https://github.com/elastic/docs-builder/blob/main/config/changelog.yml.example).
+
 ## Examples
 
+### Multiple products
+
 The following command creates a changelog for a bug fix that applies to two products:
 
 ```sh
 docs-builder changelog add \
-  --title "Fixes enrich and lookup join resolution based on minimum transport version" \
-  --type bug-fix \ <1>
-  --products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ <2>
+  --title "Fixes enrich and lookup join resolution based on minimum transport version" \ <1>
+  --type bug-fix \ <2>
+  --products "elasticsearch 9.2.3, cloud-serverless 2025-12-02" \ <3>
   --areas "ES|QL"
-  --pr "https://github.com/elastic/elasticsearch/pull/137431" <3>
+  --pr "https://github.com/elastic/elasticsearch/pull/137431" <4>
 ```
 
-1. The type values are defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
-2. The product values are defined in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
-3. At this time, the PR value can be a number or a URL; it is not validated.
+1. This option is required only if you want to override what's derived from the PR title.
+2. The type values are defined in [ChangelogConfiguration.cs](https://github.com/elastic/docs-builder/blob/main/src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs).
+3. The product values are defined in [products.yml](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
+4. The `--pr` value can be a full URL (such as `https://github.com/owner/repo/pull/123`, a short format (such as `owner/repo#123`) or just a number (in which case you must also provide `--owner` and `--repo` options).
 
 The output file has the following format:
 
@@ -107,3 +119,52 @@ title: Fixes enrich and lookup join resolution based on minimum transport versio
 areas:
 - ES|QL
 ```
+
+### PR label mappings
+
+You can update your changelog configuration file to contain GitHub label mappings, for example:
+
+```yaml
+# Available areas (optional - if not specified, all areas are allowed)
+available_areas:
+  - search
+  - security
+  - machine-learning
+  - observability
+  - index-management
+  - ES|QL
+  # Add more areas as needed
+
+# GitHub label mappings (optional - used when --pr option is specified)
+# Maps GitHub PR labels to changelog type values
+# When a PR has a label that matches a key, the corresponding type value is used
+label_to_type:
+  # Example mappings - customize based on your label naming conventions
+  ">enhancement": enhancement
+  ">breaking": breaking-change
+
+# Maps GitHub PR labels to changelog area values
+# Multiple labels can map to the same area, and a single label can map to multiple areas (comma-separated)
+label_to_areas:
+  # Example mappings - customize based on your label naming conventions
+  ":Search Relevance/ES|QL": "ES|QL"
+```
+
+When you use the `--pr` option to derive information from a pull request, it can make use of those mappings:
+
+```sh
+docs-builder changelog add --pr https://github.com/elastic/elasticsearch/pull/139272 --products "elasticsearch 9.3.0" --config test/changelog.yml
+```
+
+In this case, the changelog file derives the title, type, and areas:
+
+```yaml
+pr: https://github.com/elastic/elasticsearch/pull/139272
+type: enhancement
+products:
+- product: elasticsearch
+  target: 9.3.0
+areas:
+- ES|QL
+title: '[ES|QL] Take TOP_SNIPPETS out of snapshot'
+```

src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs

@@ -46,6 +46,17 @@ public class ChangelogConfiguration
 
 	public List<string>? AvailableProducts { get; set; }
 
+	/// <summary>
+	/// Mapping from GitHub label names to changelog type values
+	/// </summary>
+	public Dictionary<string, string>? LabelToType { get; set; }
+
+	/// <summary>
+	/// Mapping from GitHub label names to changelog area values
+	/// Multiple labels can map to the same area, and a single label can map to multiple areas (comma-separated)
+	/// </summary>
+	public Dictionary<string, string>? LabelToAreas { get; set; }
+
 	public static ChangelogConfiguration Default => new();
 }
 

src/services/Elastic.Documentation.Services/Changelog/ChangelogInput.cs

@@ -9,12 +9,14 @@ namespace Elastic.Documentation.Services.Changelog;
 /// </summary>
 public class ChangelogInput
 {
-	public required string Title { get; set; }
-	public required string Type { get; set; }
+	public string? Title { get; set; }
+	public string? Type { get; set; }
 	public required List<ProductInfo> Products { get; set; }
 	public string? Subtype { get; set; }
 	public string[] Areas { get; set; } = [];
 	public string? Pr { get; set; }
+	public string? Owner { get; set; }
+	public string? Repo { get; set; }
 	public string[] Issues { get; set; } = [];
 	public string? Description { get; set; }
 	public string? Impact { get; set; }

src/services/Elastic.Documentation.Services/Changelog/GitHubPrService.cs

@@ -0,0 +1,166 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using System.Net.Http.Headers;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.Logging;
+
+namespace Elastic.Documentation.Services.Changelog;
+
+/// <summary>
+/// Service for fetching pull request information from GitHub
+/// </summary>
+public partial class GitHubPrService(ILoggerFactory loggerFactory) : IGitHubPrService
+{
+	private readonly ILogger<GitHubPrService> _logger = loggerFactory.CreateLogger<GitHubPrService>();
+	private static readonly HttpClient HttpClient = new();
+
+	static GitHubPrService()
+	{
+		HttpClient.DefaultRequestHeaders.Add("User-Agent", "docs-builder");
+		HttpClient.DefaultRequestHeaders.Add("Accept", "application/vnd.github.v3+json");
+	}
+
+	/// <summary>
+	/// Fetches pull request information from GitHub
+	/// </summary>
+	/// <param name="prUrl">The PR URL (e.g., https://github.com/owner/repo/pull/123, owner/repo#123, or just a number if owner/repo are provided)</param>
+	/// <param name="owner">Optional: GitHub repository owner (used when prUrl is just a number)</param>
+	/// <param name="repo">Optional: GitHub repository name (used when prUrl is just a number)</param>
+	/// <param name="ctx">Cancellation token</param>
+	/// <returns>PR information or null if fetch fails</returns>
+	public async Task<GitHubPrInfo?> FetchPrInfoAsync(string prUrl, string? owner = null, string? repo = null, CancellationToken ctx = default)
+	{
+		try
+		{
+			var (parsedOwner, parsedRepo, prNumber) = ParsePrUrl(prUrl, owner, repo);
+			if (parsedOwner == null || parsedRepo == null || prNumber == null)
+			{
+				_logger.LogWarning("Unable to parse PR URL: {PrUrl}. Owner: {Owner}, Repo: {Repo}", prUrl, owner, repo);
+				return null;
+			}
+
+			// Add GitHub token if available (for rate limiting and private repos)
+			var githubToken = Environment.GetEnvironmentVariable("GITHUB_TOKEN");
+			using var request = new HttpRequestMessage(HttpMethod.Get, $"https://api.github.com/repos/{parsedOwner}/{parsedRepo}/pulls/{prNumber}");
+			if (!string.IsNullOrEmpty(githubToken))
+			{
+				request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", githubToken);
+			}
+
+			_logger.LogDebug("Fetching PR info from: {ApiUrl}", request.RequestUri);
+
+			var response = await HttpClient.SendAsync(request, ctx);
+			if (!response.IsSuccessStatusCode)
+			{
+				_logger.LogWarning("Failed to fetch PR info. Status: {StatusCode}, Reason: {ReasonPhrase}", response.StatusCode, response.ReasonPhrase);
+				return null;
+			}
+
+			var jsonContent = await response.Content.ReadAsStringAsync(ctx);
+			var prData = JsonSerializer.Deserialize(jsonContent, GitHubPrJsonContext.Default.GitHubPrResponse);
+
+			if (prData == null)
+			{
+				_logger.LogWarning("Failed to deserialize PR response");
+				return null;
+			}
+
+			return new GitHubPrInfo
+			{
+				Title = prData.Title,
+				Labels = prData.Labels?.Select(l => l.Name).ToArray() ?? []
+			};
+		}
+		catch (HttpRequestException ex)
+		{
+			_logger.LogWarning(ex, "HTTP error fetching PR info from GitHub");
+			return null;
+		}
+		catch (TaskCanceledException)
+		{
+			_logger.LogWarning("Request timeout fetching PR info from GitHub");
+			return null;
+		}
+		catch (Exception ex) when (ex is not (OutOfMemoryException or StackOverflowException or ThreadAbortException))
+		{
+			_logger.LogWarning(ex, "Unexpected error fetching PR info from GitHub");
+			return null;
+		}
+	}
+
+	private static (string? owner, string? repo, int? prNumber) ParsePrUrl(string prUrl, string? defaultOwner = null, string? defaultRepo = null)
+	{
+		// Handle full URL: https://github.com/owner/repo/pull/123
+		if (prUrl.StartsWith("https://github.com/", StringComparison.OrdinalIgnoreCase) ||
+			prUrl.StartsWith("http://github.com/", StringComparison.OrdinalIgnoreCase))
+		{
+			var uri = new Uri(prUrl);
+			var segments = uri.Segments;
+			// segments[0] is "/", segments[1] is "owner/", segments[2] is "repo/", segments[3] is "pull/", segments[4] is "123"
+			if (segments.Length >= 5 && segments[3].Equals("pull/", StringComparison.OrdinalIgnoreCase))
+			{
+				var owner = segments[1].TrimEnd('/');
+				var repo = segments[2].TrimEnd('/');
+				if (int.TryParse(segments[4], out var prNum))
+				{
+					return (owner, repo, prNum);
+				}
+			}
+		}
+
+		// Handle short format: owner/repo#123
+		var hashIndex = prUrl.LastIndexOf('#');
+		if (hashIndex > 0 && hashIndex < prUrl.Length - 1)
+		{
+			var repoPart = prUrl[..hashIndex];
+			var prPart = prUrl[(hashIndex + 1)..];
+			if (int.TryParse(prPart, out var prNum))
+			{
+				var repoParts = repoPart.Split('/');
+				if (repoParts.Length == 2)
+				{
+					return (repoParts[0], repoParts[1], prNum);
+				}
+			}
+		}
+
+		// Handle just a PR number when owner/repo are provided
+		if (int.TryParse(prUrl, out var prNumber) &&
+			!string.IsNullOrWhiteSpace(defaultOwner) && !string.IsNullOrWhiteSpace(defaultRepo))
+		{
+			return (defaultOwner, defaultRepo, prNumber);
+		}
+
+		return (null, null, null);
+	}
+
+	private sealed class GitHubPrResponse
+	{
+		public string Title { get; set; } = string.Empty;
+		public List<GitHubLabel>? Labels { get; set; }
+	}
+
+	private sealed class GitHubLabel
+	{
+		public string Name { get; set; } = string.Empty;
+	}
+
+	[JsonSourceGenerationOptions(PropertyNameCaseInsensitive = true)]
+	[JsonSerializable(typeof(GitHubPrResponse))]
+	[JsonSerializable(typeof(GitHubLabel))]
+	[JsonSerializable(typeof(List<GitHubLabel>))]
+	private sealed partial class GitHubPrJsonContext : JsonSerializerContext;
+}
+
+/// <summary>
+/// Information about a GitHub pull request
+/// </summary>
+public class GitHubPrInfo
+{
+	public string Title { get; set; } = string.Empty;
+	public string[] Labels { get; set; } = [];
+}
+