Changelog profile parity for the GitHub release workflow

[lcawl]

Summary

This PR adds source: github_release profile support to changelog bundle and changelog remove so that we continue to have full parity between the command-option-based and profile-based invocations.
It also fixes several bugs discovered along the way, and substantially rewrites the changelog CLI documentation.

Details

New features

source: github_release profile support (changelog bundle and changelog remove)

Profiles can now set source: github_release to fetch the PR list directly from a published GitHub release instead of filtering pre-existing changelog files by product metadata. This is the profile-based equivalent of the existing --release-version option, letting you store your release workflow fully in changelog.yml rather than on the command line. Both changelog bundle and changelog remove support it.

Lifecycle inference from release tags for source: github_release profiles

The {lifecycle} placeholder in output and output_products patterns is now inferred from the raw release tag returned by GitHub, so pre-release suffixes are preserved: v9.2.0-beta.1 → beta, v1.34.1-preview.1 → preview. Previously the tag was stripped to its base version before inference, meaning {lifecycle} was always ga.

Bug fixes

changelog remove silently ignored --repo and --owner in profile mode

These options are not permitted with a profile (all configuration must come from changelog.yml), but no error was emitted. The command now returns an explicit error listing all forbidden options, consistent with changelog bundle's existing validation. The error message also names the specific offending flags rather than issuing a generic rejection.

--release-version inconsistently auto-inferred output_products

When --output-products was omitted, --release-version silently derived a single product entry from the release tag and the internal products.yml registry — behavior that no other filter option (--prs, --issues, --report, --all) shares. This was removed. All option-based filters now consistently derive the products array from the matched changelog files when --output-products is not provided.

Misleading error for source: github_release profiles with a third argument

Passing a third command argument to a github_release profile produced the error "cannot be combined with a promotion report argument," which was confusing since no report is involved. The message now clearly explains the constraint and suggests hardcoding the lifecycle in output_products if tag-suffix inference is not sufficient.

Documentation corrections and improvements

• output profile field was incorrectly marked "Required for bundling." It is optional; the command falls back to changelog-bundle.yaml in the output directory.
• products profile field was incorrectly marked "Required unless source: github_release is set." It is only required when filtering by product metadata. Profiles backed by a promotion report, URL list, or source: github_release do not need it.
• Renamed "products-based profiles" to "standard profiles" throughout, since the old term was misleading for profiles that use a promotion report or URL list and have no products field at all.
• New lifecycle inference tables added to both changelog-bundle.md and changelog.md covering standard profiles (version argument → lifecycle) and GitHub release profiles (release tag → lifecycle), with worked examples for GA, beta, and preview releases.
• Updated changelog.example.yml to include commented-out examples for both standard profiles and source: github_release profiles.
• Expanded and corrected command examples throughout to reflect the correct invocation syntax and expected behavior.

Steps to test

1. Set up a changelog configuration file and create some changelogs that align with PRs in a GitHub release. For example, use the files [DOCS] Changelog test apm-agent-dotnet#2714 (https://github.com/elastic/apm-agent-dotnet/releases)
2. Use the changelogs in that PR or create new changelogs using the --release-version option. For example:

   docs-builder/release/docs-builder changelog add --release-version v1.34.1 

3. Add a profile to the changelog configuration file that uses the source: github_release clause. For example:

   bundle:
     directory: docs/changelog
     output_directory: docs/releases
     resolve: true
     repo: apm-agent-dotnet
     owner: elastic.
     profiles:
       # Fetch the PR list from GitHub release notes
       gh-release:
         source: github_release
         # Output filename ({version} is substituted at runtime)
         output: "apm-agent-dotnet-{version}.yaml"
         # Optional: override the products array written to the bundle output.
         # Useful when the bundle should advertise a different lifecycle than was used for filtering.
         output_products: "apm-agent-dotnet {version} {lifecycle}"

4. Try to create a bundle using the profile that's equivalent to this command:

   docs-builder changelog bundle --release-version v1.34.0

   For example:

   docs-builder changelog bundle gh-release latest

   In my test, this successfully created a bundle named apm-agent-dotnet-1.34.1.yaml in the docs/releases folder and it contained the four relevant changelogs and product metadata like this:

   products:
   - product: apm-agent-dotnet
      target: 1.34.1
      lifecycle: ga
      repo: apm-agent-dotnet
      owner: elastic
   entries:
    - file:
         name: 2662-other-remove-redundant-println-from-profiler.yaml
         checksum: d83a5ab0f429bdf65a86fcbda3c364a1f3e55f70
        type: other
        title: Remove redundant println from profiler
        products:
        - product: apm-agent-dotnet
           target: 1.34.1
           lifecycle: ga
        prs:
        - https://github.com/elastic/apm-agent-dotnet/pull/2662
    ...

5. Try use the same profile to remove changelogs. Confirm that it performs the same as the command-based alternative:

   docs-builder changelog remove --release-version v1.34.0

   For example:

   docs-builder changelog remove gh-release latest

   In my tests, this successfully deleted the four changelogs from the docs/changelog folder.
6. Test when the changelog configuration file fallback behaviour. For example, I commented out the output and output_products fields in the profile and then re-ran the bundle command. It created the bundle successfully in the appropriate directory with the default name changelog-bundle.yaml. The product metadata in the bundle is derived from the GitHub release.
7. Test error handling.
   1. I added extra options to the profile-based commands. For example:

      docs-builder changelog remove gh-release v1.34.1 --repo mine
      docs-builder/release/docs-builder changelog bundle gh-release v1.34.1 preview --repo mine

      These commands both fail with message like this:

      Error: When using a profile, the following options are not allowed: --repo. All paths and filters are derived from the changelog configuration file.

   2. I commented out the bundle.repo and bundle.owner fields in the profile and then re-ran the bundle command. It correctly fails with this error:

      Error: Profile 'gh-release': 'source: github_release' requires a GitHub repository name. Set 'repo' on the profile or on the top-level 'bundle' configuration.

Generative AI disclosure

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

• Yes
• No

3. 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.5, clause-4.6-sonnet-medium

[github-actions]

🔍 Preview links for changed docs

• docs/cli/release/changelog-bundle.md
• docs/cli/release/changelog-remove.md
• docs/contribute/changelog.md