changelogs: Add --plan flag to changelog bundle (#3028)

* Add --plan flag to bundle

* Update bundle docs

* use UrlPath

* Fix merge mishap

* Add allowlist and https checks for report URLs

* Use ScopedFileSystem, update xml docs

* Adjust test names

* Fix tests on Windows

* Sanitize paths

* Use OptionalWindowsReplace

Author: cotti

docs/cli/changelog/bundle.md

@@ -54,6 +54,13 @@ The second argument (`[1]`) and optional third argument (`[2]`) accept the follo
 - **Promotion report file** — A path to a downloaded `.html` file containing a promotion report.
 - **URL list file** — A path to a plain-text file containing one fully-qualified GitHub PR or issue URL per line. For example, `https://github.com/elastic/elasticsearch/pull/123`. The file must contain only PR URLs or only issue URLs, not a mix. Bare numbers and short forms such as `owner/repo#123` are not allowed.
 
+## General options
+
+These options work with both profile-based and option-based modes.
+
+`--plan`
+:   Output a structured set of CI step outputs (`needs_network`, `needs_github_token`, `output_path`) describing Docker flags, network requirements, and the resolved output path, then exit without generating the bundle. Intended for CI actions that need to determine container configuration before running the actual bundle step. When running outside GitHub Actions, the output is written to stdout.
+
 ## Options
 
 The following options are only valid in option-based mode (no profile argument).

src/services/Elastic.Changelog/Bundling/ChangelogBundlingService.cs

@@ -90,6 +90,17 @@ public record BundleChangelogsArguments
 	public IReadOnlyList<string>? LinkAllowRepos { get; init; }
 }
 
+/// <summary>
+/// Structured plan output for CI actions. Describes what Docker flags and output path to expect
+/// without actually executing the bundle.
+/// </summary>
+public record BundlePlanResult
+{
+	public bool NeedsNetwork { get; init; }
+	public bool NeedsGithubToken { get; init; }
+	public string? OutputPath { get; init; }
+}
+
 /// <summary>
 /// Service for bundling changelog files
 /// </summary>
@@ -368,7 +379,7 @@ public async Task<bool> BundleChangelogs(IDiagnosticsCollector collector, Bundle
 					?? input.OutputDirectory
 					?? config.Bundle.Directory
 					?? _fileSystem.Directory.GetCurrentDirectory();
-				outputPath = _fileSystem.Path.Join(outputDir, outputPattern);
+				outputPath = _fileSystem.Path.Join(outputDir, outputPattern).OptionalWindowsReplace();
 			}
 
 			// Parse output_products pattern with version/lifecycle substitution
@@ -407,18 +418,18 @@ public async Task<bool> BundleChangelogs(IDiagnosticsCollector collector, Bundle
 		};
 	}
 
-	private static BundleChangelogsArguments ApplyConfigDefaults(BundleChangelogsArguments input, ChangelogConfiguration? config)
+	private BundleChangelogsArguments ApplyConfigDefaults(BundleChangelogsArguments input, ChangelogConfiguration? config)
 	{
 		// Apply directory: CLI takes precedence. Only use config when --directory not specified.
-		var directory = input.Directory ?? config?.Bundle?.Directory ?? Directory.GetCurrentDirectory();
+		var directory = input.Directory ?? config?.Bundle?.Directory ?? _fileSystem.Directory.GetCurrentDirectory();
 
 		if (config?.Bundle == null)
 			return input with { Directory = directory, LinkAllowRepos = null };
 
 		// Apply output default when --output not specified: use bundle.output_directory if set
 		var output = input.Output;
 		if (string.IsNullOrWhiteSpace(output) && !string.IsNullOrWhiteSpace(config.Bundle.OutputDirectory))
-			output = Path.Join(config.Bundle.OutputDirectory, "changelog-bundle.yaml");
+			output = _fileSystem.Path.Join(config.Bundle.OutputDirectory, "changelog-bundle.yaml").OptionalWindowsReplace();
 
 		// Apply resolve: CLI takes precedence over config. Only use config when CLI did not specify.
 		var resolve = input.Resolve ?? config.Bundle.Resolve;
@@ -438,6 +449,73 @@ private static BundleChangelogsArguments ApplyConfigDefaults(BundleChangelogsArg
 		};
 	}
 
+	/// <summary>
+	/// Resolves a bundle plan from config and profile metadata without executing any network calls or
+	/// file-scanning. Used by <c>--plan</c> mode to emit GitHub Actions step outputs
+	/// (<c>needs_network</c>, <c>needs_github_token</c>, <c>output_path</c>) that CI actions consume.
+	/// </summary>
+	public async Task<BundlePlanResult?> PlanBundleAsync(
+		IDiagnosticsCollector collector,
+		BundleChangelogsArguments input,
+		bool hasReleaseVersion,
+		Cancel ctx)
+	{
+		var needsNetwork = hasReleaseVersion;
+		var needsGithubToken = hasReleaseVersion;
+
+		ChangelogConfiguration? config = null;
+		if (!string.IsNullOrWhiteSpace(input.Profile))
+		{
+			if (_configLoader == null)
+			{
+				collector.EmitError(string.Empty, "Changelog configuration loader is required for profile-based bundling.");
+				return null;
+			}
+			config = string.IsNullOrWhiteSpace(input.Config)
+				? await _configLoader.LoadChangelogConfigurationForProfileMode(collector, ctx)
+				: await _configLoader.LoadChangelogConfigurationRequired(collector, input.Config, ctx);
+			if (config == null)
+				return null;
+		}
+		else if (_configLoader != null)
+			config = await _configLoader.LoadChangelogConfiguration(collector, input.Config, ctx);
+
+		BundleProfile? profileDef = null;
+		if (!string.IsNullOrWhiteSpace(input.Profile) &&
+			config?.Bundle?.Profiles?.TryGetValue(input.Profile, out profileDef) == true)
+		{
+			if (string.Equals(profileDef.Source, "github_release", StringComparison.OrdinalIgnoreCase))
+			{
+				needsNetwork = true;
+				needsGithubToken = true;
+			}
+		}
+
+		// Resolve output path — mirrors the logic in ProcessProfile + ApplyConfigDefaults.
+		var outputPath = input.Output;
+		if (string.IsNullOrWhiteSpace(outputPath) && profileDef?.Output != null)
+		{
+			var version = input.ProfileArgument ?? "unknown";
+			var lifecycle = VersionLifecycleInference.InferLifecycle(version);
+			var outputPattern = profileDef.Output
+				.Replace("{version}", version)
+				.Replace("{lifecycle}", lifecycle);
+			var outputDir = config?.Bundle?.OutputDirectory
+				?? config?.Bundle?.Directory
+				?? _fileSystem.Directory.GetCurrentDirectory();
+			outputPath = _fileSystem.Path.Join(outputDir, outputPattern).OptionalWindowsReplace();
+		}
+		else if (string.IsNullOrWhiteSpace(outputPath) && config?.Bundle?.OutputDirectory != null)
+			outputPath = _fileSystem.Path.Join(config.Bundle.OutputDirectory, "changelog-bundle.yaml").OptionalWindowsReplace();
+
+		return new BundlePlanResult
+		{
+			NeedsNetwork = needsNetwork,
+			NeedsGithubToken = needsGithubToken,
+			OutputPath = outputPath
+		};
+	}
+
 	private bool ValidateInput(IDiagnosticsCollector collector, BundleChangelogsArguments input)
 	{
 		if (string.IsNullOrWhiteSpace(input.Directory))

src/services/Elastic.Changelog/Bundling/PromotionReportParser.cs

@@ -19,14 +19,32 @@ public partial class PromotionReportParser(ILoggerFactory logFactory, ScopedFile
 {
 	private readonly ILogger _logger = logFactory.CreateLogger<PromotionReportParser>();
 	private readonly IFileSystem _fileSystem = fileSystem ?? FileSystemFactory.RealRead;
-	private static readonly HttpClient HttpClient = new();
 
-	static PromotionReportParser()
+	private static readonly string[] AllowedHosts = ["github.com", "buildkite.com"];
+
+	private static readonly HttpClient HttpClient = CreateHttpClient();
+
+	private static HttpClient CreateHttpClient()
 	{
-		HttpClient.DefaultRequestHeaders.Add("User-Agent", "docs-builder");
-		HttpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("text/html"));
+		var handler = new SocketsHttpHandler
+		{
+			AllowAutoRedirect = false,
+			ConnectTimeout = TimeSpan.FromSeconds(10),
+			UseProxy = false
+		};
+		var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
+		client.DefaultRequestHeaders.Add("User-Agent", "docs-builder");
+		client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("text/html"));
+		return client;
 	}
 
+	private static bool IsAllowedUrl(string url) =>
+		Uri.TryCreate(url, UriKind.Absolute, out var uri) &&
+		uri.Scheme == Uri.UriSchemeHttps &&
+		AllowedHosts.Any(domain =>
+			uri.Host.Equals(domain, StringComparison.OrdinalIgnoreCase) ||
+			uri.Host.EndsWith($".{domain}", StringComparison.OrdinalIgnoreCase));
+
 	[GeneratedRegex(@"github\.com/([^/]+)/([^/]+)/pull/(\d+)", RegexOptions.IgnoreCase)]
 	private static partial Regex GitHubPrUrlRegex();
 
@@ -74,24 +92,15 @@ private async Task<PromotionReportResult> ParsePromotionReportAsync(string sourc
 			string htmlContent;
 
 			if (source.StartsWith("http://", StringComparison.OrdinalIgnoreCase) ||
-			source.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
+				source.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
 			{
-				// Fetch URL content
-				_logger.LogInformation("Fetching promotion report from URL: {Url}", source);
-				var response = await HttpClient.GetAsync(source, ctx);
-				if (!response.IsSuccessStatusCode)
-				{
-					return new PromotionReportResult
-					{
-						IsValid = false,
-						ErrorMessage = $"Failed to fetch promotion report from URL: {response.StatusCode}"
-					};
-				}
-				htmlContent = await response.Content.ReadAsStringAsync(ctx);
+				var (content, error) = await FetchReportUrlAsync(source, ctx);
+				if (error != null)
+					return new PromotionReportResult { IsValid = false, ErrorMessage = error };
+				htmlContent = content!;
 			}
 			else if (_fileSystem.File.Exists(source))
 			{
-				// Read local file
 				_logger.LogInformation("Reading promotion report from file: {FilePath}", source);
 				htmlContent = await _fileSystem.File.ReadAllTextAsync(source, ctx);
 			}
@@ -104,7 +113,6 @@ private async Task<PromotionReportResult> ParsePromotionReportAsync(string sourc
 				};
 			}
 
-			// Extract PR URLs from HTML content
 			var prUrls = ExtractPrUrlsFromHtml(htmlContent);
 
 			if (prUrls.Count == 0)
@@ -118,11 +126,7 @@ private async Task<PromotionReportResult> ParsePromotionReportAsync(string sourc
 
 			_logger.LogInformation("Extracted {Count} PR URLs from promotion report", prUrls.Count);
 
-			return new PromotionReportResult
-			{
-				IsValid = true,
-				PrUrls = prUrls
-			};
+			return new PromotionReportResult { IsValid = true, PrUrls = prUrls };
 		}
 		catch (HttpRequestException ex)
 		{
@@ -144,6 +148,35 @@ private async Task<PromotionReportResult> ParsePromotionReportAsync(string sourc
 		}
 	}
 
+	/// <summary>Returns (content, null) on success or (null, errorMessage) on failure.</summary>
+	private async Task<(string? Content, string? Error)> FetchReportUrlAsync(string url, Cancel ctx)
+	{
+		if (!IsAllowedUrl(url))
+			return (null, $"Report URL must use HTTPS and target an allowed domain ({string.Join(", ", AllowedHosts)}): {url}");
+
+		_logger.LogInformation("Fetching promotion report from URL: {Url}", url);
+		var response = await HttpClient.GetAsync(url, ctx);
+
+		if ((int)response.StatusCode is >= 300 and < 400 && response.Headers.Location != null)
+		{
+			var redirectTarget = response.Headers.Location.IsAbsoluteUri
+				? response.Headers.Location.ToString()
+				: new Uri(new Uri(url), response.Headers.Location).ToString();
+
+			if (!IsAllowedUrl(redirectTarget))
+				return (null, $"Report URL redirected to a disallowed domain: {redirectTarget}");
+
+			_logger.LogInformation("Following redirect to: {Url}", redirectTarget);
+			response = await HttpClient.GetAsync(redirectTarget, ctx);
+		}
+
+		if (!response.IsSuccessStatusCode)
+			return (null, $"Failed to fetch promotion report from URL: {response.StatusCode}");
+
+		var content = await response.Content.ReadAsStringAsync(ctx);
+		return (content, null);
+	}
+
 	private List<string> ExtractPrUrlsFromHtml(string html)
 	{
 		var prUrls = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

src/services/Elastic.Changelog/Uploading/ChangelogUploadService.cs

@@ -99,6 +99,8 @@ public async Task<bool> Upload(IDiagnosticsCollector collector, ChangelogUploadA
 
 	internal IReadOnlyList<UploadTarget> DiscoverUploadTargets(IDiagnosticsCollector collector, string changelogDir)
 	{
+		var rootDir = _fileSystem.DirectoryInfo.New(changelogDir);
+
 		var yamlFiles = _fileSystem.Directory.GetFiles(changelogDir, "*.yaml", SearchOption.TopDirectoryOnly)
 			.Concat(_fileSystem.Directory.GetFiles(changelogDir, "*.yml", SearchOption.TopDirectoryOnly))
 			.ToList();
@@ -107,6 +109,13 @@ internal IReadOnlyList<UploadTarget> DiscoverUploadTargets(IDiagnosticsCollector
 
 		foreach (var filePath in yamlFiles)
 		{
+			var fileInfo = _fileSystem.FileInfo.New(filePath);
+			if (SymlinkValidator.ValidateFileAccess(fileInfo, rootDir) is { } accessError)
+			{
+				collector.EmitWarning(filePath, $"Skipping: {accessError}");
+				continue;
+			}
+
 			var products = ReadProductsFromFragment(filePath);
 			if (products.Count == 0)
 			{