changelog bundle cli command

docs-builder changelog bundle \
  [<profile>] \
  [<profile-arg>] \
  [<profile-report>] \
  [options]
		

Aggregates changelog YAML files matching a filter into a single bundle file. The bundle is the artifact used by the {changelog} directive and docs-builder changelog render to produce release notes.

The command has two mutually exclusive modes. You cannot mix them: supplying a profile name on the command line disables all filter and output flags.

<profile> string

Optional: Profile name from bundle.profiles in config (for example, "elasticsearch-release"). When specified, the second argument is the version or promotion report URL.

<profile-arg> string

Optional: Version number or promotion report URL/path when using a profile (for example, "9.2.0" or "https://buildkite.../promotion-report.html")

<profile-report> string

Optional: Promotion report or URL list file when also providing a version. When provided, the second argument must be a version string and this is the PR/issue filter source (for example, "bundle serverless-release 2026-02 ./report.html").

--[no-]all

Include all changelogs in the directory.

Default: false

--config string

Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml'

Constraints: symbolic links not allowed, must exist, extensions: yml, yaml

--directory string

Optional: Directory containing changelog YAML files. Uses config bundle.directory or defaults to current directory

Constraints: symbolic links not allowed

--description string

Optional: Bundle description text with placeholder support. Supports VERSION, LIFECYCLE, OWNER, and REPO placeholders. Overrides bundle.description from config. In option-based mode, placeholders require --output-products to be explicitly specified.

--hide-features string[]

Optional: Filter by feature IDs (comma-separated) or a path to a newline-delimited file containing feature IDs. Can be specified multiple times. Entries with matching feature-id values will be commented out when the bundle is rendered (by CLI render or changelog directive).

Repeatable: pass --hide-features multiple times to supply more than one value

--[no-]no-release-date

Optional: Skip auto-population of release date in the bundle. Mutually exclusive with --release-date. Not available in profile mode.

Default: false

--release-date string

Optional: Explicit release date for the bundle in YYYY-MM-DD format. Overrides auto-population behavior. Mutually exclusive with --no-release-date. Not available in profile mode.

--input-products string

Filter by products in format "product target lifecycle, ..." (for example, "cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"). When specified, all three parts (product, target, lifecycle) are required but can be wildcards (*). Examples: "elasticsearch * " matches all elasticsearch changelogs, "cloud-serverless 2025-12-02 " matches cloud-serverless 2025-12-02 with any lifecycle, " 9.3. " matches any product with target starting with "9.3.", " * *" matches all changelogs (equivalent to --all).

--output string

Optional: Output path for the bundled changelog. Can be either (1) a directory path, in which case 'changelog-bundle.yaml' is created in that directory, or (2) a file path ending in .yml or .yaml. Uses config bundle.output_directory or defaults to 'changelog-bundle.yaml' in the input directory

--output-products string

Optional: Explicitly set the products array in the output file in format "product target lifecycle, ...". Overrides any values from changelogs.

--issues string[]

Filter by issue URLs (comma-separated), or a path to a newline-delimited file containing fully-qualified GitHub issue URLs. Can be specified multiple times.

Repeatable: pass --issues multiple times to supply more than one value

--owner string

GitHub repository owner, which is used when PRs or issues are specified as numbers or when using --release-version. Falls back to bundle.owner in changelog.yml when not specified. If that value is also absent, "elastic" is used.

--[no-]plan

Emit GitHub Actions step outputs (needs_network, needs_github_token, output_path) describing network requirements and the resolved output path, then exit without generating the bundle. Intended for CI actions.

Default: false

--prs string[]

Filter by pull request URLs (comma-separated), or a path to a newline-delimited file containing fully-qualified GitHub PR URLs. Can be specified multiple times.

Repeatable: pass --prs multiple times to supply more than one value

--release-version string

GitHub release tag to use as a filter source (for example, "v9.2.0" or "latest"). When specified, fetches the release, parses PR references from the release notes, and uses those PRs as the filter — equivalent to passing the PR list via --prs. When --output-products is not specified, it is inferred from the release tag and repository name.

--repo string

GitHub repository name, which is used when PRs or issues are specified as numbers or when using --release-version. Falls back to bundle.repo in changelog.yml when not specified. If that value is also absent, the product ID is used.

--report string

A URL or file path to a promotion report. Extracts PR URLs and uses them as the filter.

--[no-]resolve

Optional: Copy the contents of each changelog file into the entries array. Uses config bundle.resolve or defaults to false.

-l --log-level enum

Minimum log level.

Values: trace, debug, information, warning, error, critical, none

Default: information

-c --config-source enum

Override the configuration source: local, remote

Values: local, remote, embedded

--[no-]skip-private-repositories

Skip cloning private repositories

-l --log-level enum

Minimum log level.

Values: trace, debug, information, warning, error, critical, none

Default: information

-c --config-source enum

Override the configuration source: local, remote

Values: local, remote, embedded

--[no-]skip-private-repositories

Skip cloning private repositories

Define reusable profiles in changelog.yml and invoke by name. This is the recommended approach for release workflows because the filter, output path, and product metadata are all captured in configuration and don't need to be specified on the command line.

# Bundle using a named profile (version inferred for {lifecycle} placeholder)
docs-builder changelog bundle elasticsearch-release 9.2.0

# Bundle using a profile with a promotion report as the filter source
docs-builder changelog bundle elasticsearch-release 9.2.0 ./promotion-report.html
		

The second positional argument accepts:

• A version string (e.g. 9.2.0, 9.2.0-beta.1) — lifecycle is inferred automatically (ga, beta, rc)
• A promotion report URL or file path
• A plain-text URL list file (one fully-qualified GitHub URL per line)

When your profile uses {version} in its output pattern and you also want to filter by a report, pass both arguments.

Example profile in changelog.yml:

bundle:
  repo: elasticsearch
  owner: elastic
  directory: docs/changelog
  output_directory: docs/releases
  profiles:
    elasticsearch-release:
      products: "elasticsearch {version} {lifecycle}"
      output: "elasticsearch/{version}.yaml"
      output_products: "elasticsearch {version}"
		

Supply filter flags directly when you don't have a profile configured or need a one-off bundle.

Exactly one of the following filter flags is required:

• --all — include every changelog in the directory
• --input-products — match by product, target date, and lifecycle (e.g. "elasticsearch * *")
• --prs — filter by PR URLs or a newline-delimited file of PR URLs
• --issues — filter by issue URLs or a newline-delimited file of issue URLs
• --release-version — fetch PR references from a GitHub release tag (e.g. v9.2.0 or latest)
• --report — filter by PRs referenced in a promotion report (URL or local file)

# Bundle all changelogs in docs/changelog/
docs-builder changelog bundle --all --directory docs/changelog

# Bundle changelogs for a specific product release
docs-builder changelog bundle \
  --input-products "elasticsearch 9.2.0 ga" \
  --output docs/releases/9.2.0.yaml

# Bundle from a GitHub release
docs-builder changelog bundle \
  --release-version v9.2.0 \
  --repo elasticsearch \
  --owner elastic
		

By default the bundle contains only file names and checksums — the original changelog files must remain on disk for rendering. Add --resolve (or set bundle.resolve: true in changelog.yml) to embed the full entry content inside the bundle. A resolved bundle is:

• Required when using the {changelog} directive after deleting the source changelog files
• Required when link_allow_repos is configured (private-link scrubbing only runs during resolve)
• Necessary to regenerate rendered Markdown or AsciiDoc after the source files are removed

Pass --plan to emit GitHub Actions step outputs (needs_network, needs_github_token, output_path) without generating the bundle. Use this in a planning step to decide whether subsequent steps require a GitHub token or network access.

For full configuration reference, see Bundle changelogs.

The changelog bundle command has --input-products and --output-products options that accept values with the format "product target lifecycle, ..." where:

• product is the product ID from products.yml (required)
• target is the target version or date (optional)
• lifecycle exists in Lifecycle.cs (optional)

You can further limit the possible values with the products and lifecycles options in the changelog configuration file.

For example:

• "kibana 9.2.0 ga"
• "cloud-serverless 2025-08-05"
• "cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"

If you use "* * *" in the --input-products command option or bundle.profiles.<name>.products configuration setting, it's equivalent to the --all command option.

The way that lifecycle values are inferred varies between GitHub release profiles and standard profiles.

For source: github_release profiles, the {lifecycle} placeholder in output and output_products is derived from the full release tag name. For example:

For standard profiles, {version} is copied verbatim from your command argument and {lifecycle} is derived from that value. For example:

For more information about acceptable product and lifecycle values, go to Product format.

A changelog in a public repository might contain links to pull requests or issues in repositories that should not appear in published documentation.

Set bundle.link_allow_repos in changelog.yml to an explicit list of owner/repo strings. When this key is present (including as an empty list), PR and issue references are filtered at bundle time: only links whose resolved repository is in the list are kept; others are rewritten to # PRIVATE: sentinel strings in the bundle YAML.

You can use --release-version to fetch pull request references directly from GitHub release notes and use them as the bundle filter. This is equivalent to building a PR list file manually and passing it with --prs, but without any file management.

docs-builder changelog bundle \
  --release-version v1.34.0 \
  --repo apm-agent-dotnet \
  --owner elastic
  --output-products "apm-agent-dotnet 1.34.0 ga"
		

1. The tag value that is used in the GET /repos/{owner}/{repo}/releases/tags/{tag} releases API.
2. You must specify --repo or set bundle.repo in the changelog configuration file.
3. If you don't specify --owner, it uses bundle.owner in the changelog configuration or else defaults to elastic.
4. The bundle's product metadata is inferred automatically from the release tag and repository name; you can override that behavior with the --output-products option.

By default all changelogs that match PRs in the GitHub release notes are included in the bundle. To apply additional filtering by the changelog type, areas, or products, add rules.bundle configuration settings.

You can use the --issues option to create a bundle of changelogs that relate to those GitHub issues. Issues can be identified by a full URL (such as https://github.com/owner/repo/issues/123), a short format (such as owner/repo#123), or just a number (in which case --owner and --repo are required — or set via bundle.owner and bundle.repo in the configuration).

docs-builder changelog bundle --issues "12345,12346" \
  --repo elasticsearch \
  --owner elastic \
  --output-products "elasticsearch 9.2.2 ga"
		

Alternatively, you can specify a path to a newline-delimited file that contains the issue URLS (for example, --issues /path/to/file.txt). In this case, you cannot use short URLs or numbers, each line must have a full URL.

By default all changelogs that match issues in the list are included in the bundle. To apply additional filtering by the changelog type, areas, or products, add rules.bundle configuration settings.

You can use the --prs option to create a bundle of the changelogs that relate to those pull requests.

Pull requests can be identified by a full URL (such as https://github.com/owner/repo/pull/123), a short format (such as owner/repo#123), or just a number.

docs-builder changelog bundle --prs "108875,135873,136886" \
  --repo elasticsearch \
  --owner elastic \
  --output-products "elasticsearch 9.2.2 ga"
		

1. The comma-separated list of pull request numbers to seek.
2. The repository in the pull request URLs. Not required when using full PR URLs, or when bundle.repo is set in the changelog configuration.
3. The owner in the pull request URLs. Not required when using full PR URLs, or when bundle.owner is set in the changelog configuration.
4. The product metadata for the bundle. If it is not provided, it will be derived from all the changelog product values.

Alternatively, you can specify a path to a newline-delimited file that contains the PR URLS (for example, --prs /path/to/file.txt). In this case, you cannot use short URLs or numbers, each line must have a full URL. For example:

https://github.com/elastic/elasticsearch/pull/108875
https://github.com/elastic/elasticsearch/pull/135873
https://github.com/elastic/elasticsearch/pull/136886
https://github.com/elastic/elasticsearch/pull/137126
		

By default all changelogs that match PRs in the list are included in the bundle. To apply additional filtering by the changelog type, areas, or products, add rules.bundle configuration settings.

If you have changelog files that reference those pull requests, the command creates a file like this:

products:
- product: elasticsearch
  target: 9.2.2
  lifecycle: ga
entries:
- file:
    name: 1765507819-fix-ml-calendar-event-update-scalability-issues.yaml
    checksum: 069b59edb14594e0bc3b70365e81626bde730ab7
- file:
    name: 1765507798-convert-bytestransportresponse-when-proxying-respo.yaml
    checksum: c6dbd4730bf34dbbc877c16c042e6578dd108b62
- file:
    name: 1765507839-use-ivf_pq-for-gpu-index-build-for-large-datasets.yaml
    checksum: 451d60283fe5df426f023e824339f82c2900311e
		

You can use the --input-products option to create a bundle of changelogs that match the product details. When using --input-products, you must provide all three parts: product, target, and lifecycle. Each part can be a wildcard (*) to match any value.

docs-builder changelog bundle \
  --input-products "cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"
		

1. Include all changelogs that have the cloud-serverless product identifier with target dates of either December 2 2025 (lifecycle ga) or December 6 2025 (lifecycle beta). For more information about product values, refer to Product format.

You can use wildcards in any of the three parts:

# Bundle any changelogs that have exact matches for either of these clauses
docs-builder changelog bundle --input-products "cloud-serverless 2025-12-02 ga, elasticsearch 9.3.0 beta"

# Bundle all elasticsearch changelogs regardless of target or lifecycle
docs-builder changelog bundle --input-products "elasticsearch * *"

# Bundle all cloud-serverless 2025-12-02 changelogs with any lifecycle
docs-builder changelog bundle --input-products "cloud-serverless 2025-12-02 *"

# Bundle any cloud-serverless changelogs with target starting with "2025-11-" and "ga" lifecycle
docs-builder changelog bundle --input-products "cloud-serverless 2025-11-* ga"

# Bundle all changelogs (equivalent to --all)
docs-builder changelog bundle --input-products "* * *"
		

If you have changelog files that reference those product details, the command creates a file like this:

products:
- product: cloud-serverless
  target: 2025-12-02
- product: cloud-serverless
  target: 2025-12-06
entries:
- file:
    name: 1765495972-fixes-enrich-and-lookup-join-resolution-based-on-m.yaml
    checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464
- file:
    name: 1765507778-break-on-fielddata-when-building-global-ordinals.yaml
    checksum: 70d197d96752c05b6595edffe6fe3ba3d055c845
		

1. By default these values match your --input-products (even if the changelogs have more products). To specify different product metadata, use the --output-products option.

You can use --report to filter by a promotion report:

# Extract PRs from a downloaded report and use them as the filter
docs-builder changelog bundle \
  --report ./promotion-report.html \
  --directory ./docs/changelog \
  --output ./docs/releases/bundle.yaml
		

By default all changelogs that match PRs in the promotion report are included in the bundle. To apply additional filtering by the changelog type, areas, or products, add rules.bundle configuration settings.

You can use the --hide-features option to embed feature IDs that should be hidden when the bundle is rendered. This is useful for features that are not yet ready for public documentation.

docs-builder changelog bundle \
  --input-products "elasticsearch 9.3.0 *" \
  --hide-features "feature:hidden-api,feature:experimental" \
  --output /path/to/bundles/9.3.0.yaml
		

1. Feature IDs to hide. Changelogs with matching feature-id values will be commented out when rendered.

The bundle output will include a hide-features field:

products:
- product: elasticsearch
  target: 9.3.0
hide-features:
  - feature:hidden-api
  - feature:experimental
entries:
- file:
    name: 1765495972-new-feature.yaml
    checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464
		

When this bundle is rendered (either via the changelog render command or the {changelog} directive), changelogs with feature-id values matching any of the listed features will be commented out in the output.