﻿---
title: changelog bundle
description: Bundle changelog files. To create the changelogs, use changelog add. For details and examples, go to Create and bundle changelogs. changelog bundle supports...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2868/cli/release/changelog-bundle
---

# changelog bundle
Bundle changelog files.
To create the changelogs, use [changelog add](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2868/cli/release/changelog-add).
For details and examples, go to [Create and bundle changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2868/contribute/changelog).

## Usage

```sh
docs-builder  changelog bundle [arguments...] [options...] [-h|--help]
```

`changelog bundle` supports two mutually exclusive invocation modes:
- **Profile-based**: All paths and filters come from the changelog configuration file. No other options are allowed. For example, `bundle <profile> <version> <report>`.
- **Option-based**: You supply all filter and output options directly. For example, `bundle --all` (or `--input-products`, `--prs`, `--issues`).

You cannot mix the two modes. Passing any option-based flag together with a profile returns an error.
Profile-based commands discover the changelog configuration automatically (no `--config` flag): they look for `changelog.yml` in the current directory, then `docs/changelog.yml`.
If neither file is found, the command returns an error with instructions to run `docs-builder changelog init` or to re-run from the folder where the file exists.
Option-based commands ignore the `bundle.profiles` section of the changelog configuration file.

## Arguments

These arguments apply to profile-based bundling:
<definitions>
  <definition term="[0] <string?>">
    Profile name from `bundle.profiles` in the changelog configuration file.
  </definition>
  <definition term="For example, "elasticsearch-release".">
  </definition>
  <definition term="When specified, the second argument is the version, promotion report URL, or URL list file.">
  </definition>
  <definition term="[1] <string?>">
    Version number, promotion report URL/path, or URL list file.
  </definition>
  <definition term="For example, 9.2.0, https://buildkite.../promotion-report.html, or /path/to/prs.txt.">
  </definition>
  <definition term="[2] <string?>">
    Optional: Promotion report URL/path or URL list file when the second argument is a version string.
  </definition>
  <definition term="When provided, [1] must be a version string and [2] is the PR/issue filter source.">
  </definition>
  <definition term="For example, docs-builder changelog bundle serverless-release 2026-02 ./promotion-report.html.">
  </definition>
</definitions>

<note>
  The third argument (`[2]`) is required when your profile uses `{version}` placeholders in `output` or `output_products` patterns and you also want to filter by a promotion report or URL list. Without it, the version defaults to `"unknown"`.
</note>


### Profile argument types

The second argument (`[1]`) and optional third argument (`[2]`) accept the following:
- **Version string** — Used for `{version}` substitution in profile patterns. For example, `9.2.0` or `2026-02`.
- **Promotion report URL** — A URL to an HTML promotion report. PR URLs are extracted from it.
- **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.


## Options

The following options are only valid in option-based mode (no profile argument).
Using any of them with a profile returns an error.
You must choose one method for determining what's in the bundle (`--all`, `--input-products`, `--prs`, `--issues`, `--release-version`, or `--report`).
<definitions>
  <definition term="--all">
    Include all changelogs from the directory.
  </definition>
  <definition term="--config <string?>">
    Optional: Path to the changelog.yml configuration file.
  </definition>
  <definition term="Defaults to docs/changelog.yml.">
  </definition>
  <definition term="--directory <string?>">
    Optional: The directory that contains the changelog YAML files.
  </definition>
  <definition term="When not specified, falls back to bundle.directory from the changelog configuration, then the current working directory. See Output files for the full resolution order.">
  </definition>
  <definition term="--hide-features <string[]?>">
    Optional: A list of feature IDs (comma-separated), or a path to a newline-delimited file containing feature IDs.
  </definition>
  <definition term="Can be specified multiple times.">
  </definition>
  <definition term="Adds a hide-features list to the bundle.">
  </definition>
  <definition term="When the bundle is rendered (by the changelog render command or {changelog} directive), changelogs with matching feature-id values will be commented out of the documentation.">
  </definition>
  <definition term="--input-products <List<ProductInfo>?>">
    Filter by products in the format "product target lifecycle, ...".
  </definition>
  <definition term="For more information about the valid product and lifecycle values, go to Product format.">
  </definition>
  <definition term="When specified, all three parts (product, target, lifecycle) are required but can be wildcards (*). Multiple comma-separated values are combined with OR: a changelog is included if it matches any of the specified product/target/lifecycle combinations. For example:">
  </definition>
</definitions>

- `"cloud-serverless 2025-12-02 ga, cloud-serverless 2025-12-06 beta"` — include changelogs for either cloud-serverless 2025-12-02 ga or cloud-serverless 2025-12-06 beta
- `"cloud-serverless 2025-12-02 *"` - match cloud-serverless 2025-12-02 with any lifecycle
- `"elasticsearch * *"` - match all elasticsearch changelogs
- `"* 9.3.* *"` - match any product with target starting with "9.3."
- `"* * *"` - match all changelogs (equivalent to `--all`)

<definitions>
  <definition term="--issues <string[]?>">
    Filter by issue URLs (comma-separated), or a path to a newline-delimited file. Can be specified multiple times.
  </definition>
  <definition term="Each occurrence can be either comma-separated issues ( --issues "https://github.com/owner/repo/issues/123,456") or a file path (for example --issues /path/to/file.txt).">
  </definition>
  <definition term="When using a file, every line must be a fully-qualified GitHub issue URL such as https://github.com/owner/repo/issues/123. Bare numbers and short forms are not allowed in files.">
  </definition>
  <definition term="--no-resolve">
    Optional: Explicitly turn off the `resolve` option if it's specified in the changelog configuration file.
  </definition>
  <definition term="--output <string?>">
    Optional: The output path for the bundle.
  </definition>
  <definition term="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.">
  </definition>
  <definition term="When not specified, falls back to bundle.output_directory from the changelog configuration, then the input directory (which is itself resolved from --directory, bundle.directory, or the current working directory). See Output files for the full resolution order.">
  </definition>
  <definition term="--output-products <List<ProductInfo>?>">
    Optional: Explicitly set the products array in the output file in format "product target lifecycle, ...".
  </definition>
  <definition term="This value replaces information that would otherwise by derived from changelogs.">
  </definition>
  <definition term="--owner <string?>">
    Optional: The GitHub repository owner, required when pull requests or issues are specified as numbers.
  </definition>
  <definition term="Precedence: --owner flag > bundle.owner in changelog.yml > elastic.">
  </definition>
  <definition term="--prs <string[]?>">
    Filter by pull request URLs (comma-separated) or a path to a newline-delimited file. Can be specified multiple times.
  </definition>
  <definition term="Each occurrence can be either comma-separated PRs (for example --prs "https://github.com/owner/repo/pull/123,6789") or a file path (for example --prs /path/to/file.txt).">
  </definition>
  <definition term="When using a file, every line must be a fully-qualified GitHub PR URL such as https://github.com/owner/repo/pull/123. Bare numbers and short forms are not allowed in files.">
  </definition>
  <definition term="--release-version <string?>">
    GitHub release tag to use as a source of pull requests (for example, `"v9.2.0"` or `"latest"`).
  </definition>
  <definition term="When specified, the command fetches the release from GitHub, parses PR references from the release notes, and use it as the bundle filter. Only automated GitHub release notes (the default format or Release Drafter format) are supported at this time.">
  </definition>
  <definition term="Requires repo (--repo or bundle.repo in changelog.yml) and owner (--owner flag > bundle.owner in changelog.yml > elastic) details.">
  </definition>
  <definition term="When --output-products is not specified, the product, target version, and lifecycle are inferred automatically from the release tag and repository name.">
  </definition>
  <definition term="--repo <string?>">
    Optional: The GitHub repository name.
  </definition>
  <definition term="Falls back to bundle.repo in changelog.yml when not specified; if that is also absent, the product ID is used.">
  </definition>
  <definition term="--report <string?>">
    Filter by pull requests extracted from a promotion report. Accepts a URL or a local file path.
  </definition>
  <definition term="The report can be an HTML page from Buildkite or any file containing GitHub PR URLs.">
  </definition>
  <definition term="--resolve">
    Optional: Copy the contents of each changelog file into the entries array.
  </definition>
  <definition term="By default, the bundle contains only the file names and checksums.">
  </definition>
</definitions>


## Output files

Both modes use the same ordered fallback to determine where to write the bundle. The first value that is set wins:
**Output directory** (where the bundle file is placed):

| Priority | Profile-based                                | Option-based                                 |
|----------|----------------------------------------------|----------------------------------------------|
| 1        | —                                            | `--output` (explicit file or directory path) |
| 2        | `bundle.output_directory` in `changelog.yml` | `bundle.output_directory` in `changelog.yml` |
| 3        | `bundle.directory` in `changelog.yml`        | `--directory` CLI option                     |
| 4        | Current working directory                    | `bundle.directory` in `changelog.yml`        |
| 5        | —                                            | Current working directory                    |

**Input directory** (where changelog YAML files are read from) follows the same fallback for both modes, minus the explicit CLI override that is forbidden in profile mode:

| Priority | Profile-based                         | Option-based                          |
|----------|---------------------------------------|---------------------------------------|
| 1        | `bundle.directory` in `changelog.yml` | `--directory` CLI option              |
| 2        | Current working directory             | `bundle.directory` in `changelog.yml` |
| 3        | —                                     | Current working directory             |

**Bundle filename** is determined by the `bundle.profiles.<name>.output` setting (profile-based) or defaults to `changelog-bundle.yaml` (both modes).
The profile `output` setting can include additional path segments. For example: `"stack/kibana-{version}.yaml"`.
In option-based mode, when you specify `--output`, it supports two formats:
1. **Directory path**: If you specify a directory path (without a filename), the command creates `changelog-bundle.yaml` in that directory:
   ```sh
   docs-builder changelog bundle --all --output /path/to/output/dir
   # Creates /path/to/output/dir/changelog-bundle.yaml
   ```
2. **File path**: If you specify a file path ending in `.yml` or `.yaml`, the command uses that exact path:
   ```sh
   docs-builder changelog bundle --all --output /path/to/custom-bundle.yaml
   # Creates /path/to/custom-bundle.yaml
   ```

If you specify a file path with a different extension (not `.yml` or `.yaml`), the command returns an error.
<note>
  "Current working directory" means the directory you are in when you run the command (`pwd`).
  Setting `bundle.directory` and `bundle.output_directory` in `changelog.yml` is recommended so you don't need to rely on running the command from a specific directory.
</note>


## Repository name in bundles

The repository name is stored in each bundle product entry to ensure that PR and issue links are generated correctly when the bundle is rendered.
It can be set in three ways, in order of precedence:
1. **`--repo` option** (option-based mode only)
2. **`repo` field in the profile** (profile-based mode only; overrides the bundle-level default)
3. **`bundle.repo` in `changelog.yml`** (applies to both modes as a default when neither of the above is set)

Setting `bundle.repo` and `bundle.owner` in your configuration means you rarely need to pass `--repo` and `--owner` on the command line:
```yaml
bundle:
  repo: elasticsearch
  owner: elastic
```

You can still override them per profile if a project has multiple products with different repos.
The bundle output includes a `repo` field in each product:
```yaml
products:
- product: cloud-serverless
  target: 2025-12-02
  repo: elasticsearch
  owner: elastic
entries:
- file:
    name: 1765495972-new-feature.yaml
    checksum: 6c3243f56279b1797b5dfff6c02ebf90b9658464
```

When rendering, pull request and issue links use `https://github.com/elastic/elasticsearch/...` instead of the product ID.
<note>
  If no `repo` is set at any level, the product ID is used as a fallback for link generation.
  This may result in broken links if the product ID doesn't match the GitHub repository name (for example, `cloud-serverless` product ID in the `elasticsearch` repo).
</note>


## Profile configuration fields

Bundle profiles in `changelog.yml` support the following fields:
<definitions>
  <definition term="products">
    Required. The product filter pattern for input changelogs. Supports `{version}` and `{lifecycle}` placeholders that are substituted at runtime.
  </definition>
  <definition term="Example: "elasticsearch {version} {lifecycle}"">
  </definition>
  <definition term="output">
    Required for bundling. The output filename pattern. `{version}` is substituted at runtime.
  </definition>
  <definition term="Example: "elasticsearch-{version}.yaml"">
  </definition>
  <definition term="output_products">
    Optional. Overrides the products array written to the bundle output. Supports `{version}` and `{lifecycle}` placeholders. Useful when you want the bundle to have a single clear `product` object (instead of inheriting all of product data from the changelogs) and complete control over the product, version, and lifecycle details that are shown in the documentation.
  </definition>
  <definition term="Example: "elasticsearch {version} ga"">
  </definition>
  <definition term="repo">
    Optional. The GitHub repository name written to each product entry in the bundle. Used by the `{changelog}` directive to generate correct PR/issue links. Only needed when the product ID doesn't match the GitHub repository name. Overrides `bundle.repo` when set.
  </definition>
  <definition term="Example: repo: elasticsearch.">
  </definition>
  <definition term="owner">
    Optional. The GitHub owner written to each product entry in the bundle. Overrides `bundle.owner` when set.
  </definition>
  <definition term="Example: owner: elastic">
  </definition>
  <definition term="hide_features">
    Optional. Feature IDs to mark as hidden in the bundle output (string or list). When the bundle is rendered, entries with matching `feature-id` values are commented out.
  </definition>
</definitions>


## Examples

The following changelog configuration example contains multiple profiles for filtering the bundles:
```yaml
bundle:
  repo: elasticsearch 
  owner: elastic
  profiles:
    # Find changelogs with any lifecycle and a partial date
    serverless-monthly:
      products: "cloud-serverless {version}-* *" 
      output: "serverless-{version}.yaml"
      output_products: "cloud-serverless {version}"

    # Find changelogs that match a list of PRs
    serverless-report: 
      output: "serverless-{version}.yaml"
      output_products: "cloud-serverless {version}"

    # Find changelogs with a specific lifecycle
    elasticsearch-ga-only:
      products: "elasticsearch {version} ga" 
      output: "elasticsearch-{version}.yaml"

    # Infer the lifecycle from the version
    elasticsearch-release:
      hide_features: 
        - feature-flag-1
        - feature-flag-2
      products: "elasticsearch {version} {lifecycle}" 
      output: "elasticsearch-{version}.yaml"
      output_products: "elasticsearch {version}"
```

For example, when the version is:
- `9.2.0` or `9.2.0-rc.1` the inferred lifecycle that is used in the filter is `ga`.
- `9.2.0-beta.1` the inferred lifecycle is `beta`.
- `9.2.0-alpha.1` or `9.2.0-preview.1` the inferred lifecycle is `preview`.

For more information about acceptable product and lifecycle values, go to [Product format](/elastic/docs-builder/pull/2868/contribute/changelog#product-format).
You can invoke those profiles with commands like this:
```sh
# Bundle changelogs that match specific product metadata
docs-builder changelog bundle elasticsearch-release 9.2.0 beta

# Bundle changelogs with partial dates
docs-builder changelog bundle serverless-monthly 2026-02

# Bundle changelogs that match a list of PRs in a downloaded promotion report
# (version used for {version} substitution; report used as PR filter)
docs-builder changelog bundle serverless-report 2026-02-13 ./promotion-report.html

# Same using a URL list file instead of an HTML promotion report
docs-builder changelog bundle serverless-report 2026-02-13 ./prs.txt
```

For option-based mode, use `--report` to filter by a promotion report:
```sh
# 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
```


### Bundle by GitHub release

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.
```sh
docs-builder changelog bundle \
  --release-version v1.34.0 \
  --repo apm-agent-dotnet \ 
  --owner elastic 
```

The product metadata is inferred automatically from the release tag.
You can override the inferred product metadata by providing the `--output-products` option.
For example:
```sh
docs-builder changelog bundle \
  --release-version v1.34.0 \
  --output-products "apm-agent-dotnet 1.34.0 ga"
```

<note>
  `--release-version` requires a `GITHUB_TOKEN` or `GH_TOKEN` environment variable (or an active `gh` login) to fetch release details from the GitHub API.
</note>