Update changelog to pull from PR

[lcawl]

Summary

1. Updated the docs-builder changelog add command to support the --pr option with GitHub integration.
2. Added --repo and --owner options to resolve GitHub URLs when only a PR number is provided (based on the use of those options in the elastic-agent-changelog-tool build command per https://github.com/elastic/elastic-agent-changelog-tool/blob/main/docs/usage.md)
3. Updated the docs-builder changelog add command to make --title and --type optional when --pr is specified.
4. Created tests for the command with mocked GitHub PR responses using FakeItEasy.

Features:

• Automatic PR title extraction when --pr is specified
• Label-based type and area mapping via configuration
• Graceful fallback if GitHub is inaccessible
• Respects explicit command-line overrides (--title, --type, --areas)
• Supports GitHub token authentication via GITHUB_TOKEN environment variable
• When --pr is specified:
  • --title and --type are optional
    • Title is derived from PR title if not provided
    • Type is derived from PR labels (via label_to_type mapping) if not provided
    • Areas are derived from PR labels (via label_to_areas mapping) if not provided
    • Fails if PR info cannot be fetched or title/type cannot be derived
  • --owner and --repo are required if only a PR number is provided
• When --pr is not specified:
  • --title and --type are required (validation error if missing)
• Tests are run via dotnet test tests/Elastic.Documentation.Services.Tests command

Usage examples

If I provide a changelog.yml that contains type and area mappings, for example:

# 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"

I can then use these mappings to grab details from the pull request:

./docs-builder changelog add --pr https://github.com/elastic/elasticsearch/pull/139272 --products "elasticsearch 9.3.0" --config blah/changelog.yml

The generated 1765415340-[es|ql]-take-top_snippets-out-of-snapshot.yaml file has successfully derived the title, type, and area:

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'

You can also provide just a PR number with owner and repo (with and without overriding title and type):

docs-builder changelog add  --pr 123 --owner elastic --repo elasticsearch --products "elasticsearch 9.2.0 ga"

docs-builder changelog add --title "Fix bug" --type bug-fix --products "elasticsearch 9.2.0 ga" --pr 123 --owner elastic --repo docs-builder

Here's an example of an error message for the new behaviour in a situation where I haven't created type mappings:

 ./docs-builder changelog add --pr https://github.com/elastic/elasticsearch/pull/139272 --products "elasticsearch 9.3.0"

...

Error: Cannot derive type from PR https://github.com/elastic/elasticsearch/pull/139272 labels: no label-to-type mapping configured in changelog.yml. Please provide --type or configure label_to_type in changelog.yml.

AI summaries of changes made

Since I made these updates in four iterations, here are the individual summaries...

Related to --pr github integration changes

• ChangelogConfiguration (src/services/Elastic.Documentation.Services/Changelog/ChangelogConfiguration.cs):
  • Added LabelToType dictionary for mapping GitHub labels to changelog types
  • Added LabelToAreas dictionary for mapping GitHub labels to changelog areas
• GitHubPrService (src/services/Elastic.Documentation.Services/Changelog/GitHubPrService.cs):
  • New service to fetch PR information from GitHub API
  • Parses PR URLs (full URLs and short format like owner/repo#123)
  • Handles authentication via GITHUB_TOKEN environment variable
  • Returns PR title and labels
• ChangelogService (src/services/Elastic.Documentation.Services/ChangelogService.cs):
  • Integrated GitHub PR fetching when --pr is provided
  • Uses PR title for changelog title (unless --title is explicitly provided)
  • Maps PR labels to type and areas based on configuration
  • Falls back gracefully if GitHub access fails with informational messages
• ChangelogCommand (src/tooling/docs-builder/Commands/ChangelogCommand.cs):
  • Updated to create and pass GitHubPrService to ChangelogService
• changelog.yml.example (config/changelog.yml.example):
  • Added example configuration for label_to_type and label_to_areas mappings

The implementation is complete and builds successfully. The command will now automatically populate changelog fields from GitHub PRs when the --pr option is used, while still allowing manual overrides.

Related to addition of --owner and --repo

• ChangelogCommand (src/tooling/docs-builder/Commands/ChangelogCommand.cs):
  • Added --owner and --repo optional parameters
  • Updated documentation to indicate they're used when --pr is just a number
  • Passed these values to ChangelogInput
• ChangelogInput (src/services/Elastic.Documentation.Services/Changelog/ChangelogInput.cs):
  • Added Owner and Repo properties
• GitHubPrService (src/services/Elastic.Documentation.Services/Changelog/GitHubPrService.cs):
  • Updated FetchPrInfoAsync to accept optional owner and repo parameters
  • Updated ParsePrUrl to use provided owner/repo when prUrl is just a number
  • Supports:
    • Full URLs: https://github.com/owner/repo/pull/123
    • Short format: owner/repo#123
      -Just a number: 123 (requires --owner and --repo)
• ChangelogService (src/services/Elastic.Documentation.Services/ChangelogService.cs):
  • Updated to pass owner and repo to the GitHub service
  • Added validation: if --pr is just a number, both --owner and --repo must be provided

The implementation is complete and builds successfully. The command now supports resolving GitHub PRs using just a number when --owner and --repo are provided.

Related to required command options

• ChangelogCommand (src/tooling/docs-builder/Commands/ChangelogCommand.cs):
  • Made title and type optional parameters (nullable)
  • Reordered parameters so required products comes first
  • Updated documentation to indicate they're optional when --pr is specified
• ChangelogInput (src/services/Elastic.Documentation.Services/Changelog/ChangelogInput.cs):
  • Changed Title and Type from required to nullable properties
• ChangelogService (src/services/Elastic.Documentation.Services/ChangelogService.cs):
  • Updated validation logic:
    • If --pr is specified, fetch PR info first
    • If PR fetch fails, fail with an error
    • If PR fetch succeeds but title/type can't be derived, fail with specific error messages:
      • Title: fails if PR has no title
      • Type: fails if no label-to-type mapping is configured or no matching label is found
    • Final validation ensures title/type are present (either from PR or explicitly provided)
    • Added null-forgiving operators in BuildChangelogData since values are validated before use

The implementation is complete and builds successfully. The command now supports deriving title and type from PRs when --pr is specified, and fails with clear error messages if they cannot be derived.

Related to added tests

• Created IGitHubPrService interface (src/services/Elastic.Documentation.Services/Changelog/IGitHubPrService.cs)
  • Enables mocking GitHub API calls
• Updated GitHubPrService to implement IGitHubPrService
  • Maintains backward compatibility
• Updated ChangelogService to use IGitHubPrService instead of the concrete class
  • Enables dependency injection and mocking
• Updated ChangelogCommand to use the interface
• Created test project (tests/Elastic.Documentation.Services.Tests/)
  • Includes test helpers (TestHelpers.cs) with TestDiagnosticsCollector and TestLoggerFactory
• Created tests (ChangelogServiceTests.cs) covering:
  • Basic changelog creation with YAML validation
  • PR option with title derivation from GitHub
  • Label-to-type mapping from PR labels
  • Label-to-areas mapping from PR labels
  • PR number with owner/repo parameters
  • Explicit title override of PR title
  • Multiple products
  • Breaking changes with subtypes
  • Issues array
  • Feature ID and highlight flags
  • Error cases (invalid product, invalid type, PR fetch failures, missing label mappings)

All 15 tests pass, validating the changelog add command's input handling and YAML output generation with mocked GitHub PR responses.

Outstanding questions

• Do we need a way to configure default owner and repo values?

Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this contribution?

• Yes
• No

2. If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: composer-1 agent

[github-actions]

🔍 Preview links for changed docs

• docs/cli/release/changelog-add.md
• docs/contribute/changelog.md

[reakaleek]

Wondering if we should use https://github.com/octokit/dotnet-sdk

Nevertheless, LGTM.

[reakaleek]

Can we also add tests for this?

[lcawl]

Can we also add tests for this?

I've added this via 2aadd2b (and added summary to the PR description). If that's not sufficient, lmk!