Bundle changelogs

You can use docs-builder changelog commands to created consolidated data files ("release bundles") that list all the notable changes associated with a particular release. These files are ultimately used to generate release documentation.

This page describes how to create these files from the command line. For details about the equivalent GitHub action, refer to the docs-actions README.

1. Create a changelog configuration file to define all the default behavior and optional profiles and rules. Refer to Configure changelogs.
2. Create changelogs that describe all the notable changes. Refer to Create changelogs.

To have accurate release notes, there must be a definitive source of truth for what was shipped in each release. This is a superset of what will appear in the documentation.

The source of truth can be:

• a list of GitHub pull requests
• a list of GitHub issues
• a buildkite promotion report (which contains a list of PRs)
• automated release notes for GitHub releases
• all changelog files that exist in a specific folder
• all changelog files that match specific products, versions, and lifecycles

Deriving the source of truth from the contents of a folder or from the metadata in changelogs are the least accurate options (unless you have additional processes to confirm the validity of that information). It is recommended to use lists that are generated as part of your release coordination activities. Consider your options carefully and discuss with your docs team if necessary.

The changelog bundle command has two modes of operation. You can:

• specify all the command options every time you run the command, or
• define "profiles" in the changelog configuration file

The latter method is more convenient and consistent for repetitive workflows, therefore it's the recommended method described here.

You must create profiles that match your chosen source of truth.

For the most up-to-date changelog configuration options, refer to changelog.example.yml and Changelog configuration reference.

If the source of truth for what was shipped in each release is:

• a list of GitHub pull requests
• a list of GitHub issues
• a buildkite promotion report (which contains a list of PRs)

... your profile does not have any mandatory settings. However it's a good idea to define the basic bundle settings and the profile settings for the output filename and output products. For example:

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

1. The directory that contains changelog files.
2. The directory that contains changelog bundles.
3. Resolve the changelog files in the bundle rather than just referencing them. Otherwise, when you move or remove changelog files the bundle cannot be rendered.
4. If output is omitted, the default path and file names are used. This example shows how you can use a {version} variable to customize the bundle's filename.
5. The bundle's product metadata, which affects the rules that are applied and the product and version titles that ultimately appear in the documentation. If omitted, it's derived from all the changelogs in the bundle.

If you have automated GitHub release notes, the changelog bundle command can fetch the release from GitHub, parse PR references from the release notes, and uses them as the bundle filter. Only automated GitHub release notes (the default format or Release Drafter format) are supported at this time.

Your profile must contain source: github_release. It's also a good idea to include the basic bundle settings and the profile settings for the output filename and output products. For example:

bundle:
  resolve: true
  profiles:
    agent-gh-release:
      source: github_release
      repo: apm-agent-dotnet
      owner: elastic
      output: "agent-{version}.yaml"
      output_products: "apm-agent-dotnet {version} {lifecycle}"
		

1. This profile fetches the PR list from the GitHub release notes for the version tag specified in the command.
2. For source: github_release profiles, the {lifecycle} placeholder in output and output_products is inferred from full release tag name. For example, if the release tag is v1.34.1-preview.1 the lifecycle is preview. Refer to changelog bundle cli command > Lifecycle inference for more details.

If the source of truth for what was shipped in each release is:

• the products information that exists in each changelog
• all changelog files that exist in a specific folder

... you must include products in your profile. For example:

bundle:
  directory: docs/changelog
  output_directory: docs/releases
  resolve: true
  repo: elasticsearch
  owner: elastic
  profiles:
    # Collect all changelogs
    release-all:
      products: "* * *"
      output: "all.yaml"
    # 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 with a specific lifecycle
    elasticsearch-ga-only:
      products: "elasticsearch {version} ga"
      output: "elasticsearch-{version}.yaml"
    # Infer the lifecycle from the version
    elasticsearch-with-lifecycle:
      products: "elasticsearch {version} {lifecycle}"
      output: "elasticsearch-{version}.yaml"
      output_products: "elasticsearch {version}"
		

1. This profile collects all changelogs from the directory.
2. This profile collects any changelogs that have product: cloud-serverless, any lifecycle, and the date partially specified in the command.
3. This profile collects any changelogs that have product: elasticsearch, lifecycle: ga, and the version specified in the command.
4. In this case, the lifecycle is inferred from the version specified in the command. For example, if the version is 9.2.0-beta.1 the lifecycle is beta. Refer to changelog bundle cli command > Lifecycle inference.

If you created profiles, you can use them with the changelog bundle command like this:

docs-builder changelog bundle <profile> <version|report|url-list>
		

The second argument accepts a version string, a promotion report URL or path, or a URL list file (a plain-text file with one fully-qualified GitHub URL per line). If you are using a {version} placeholder in the output_products or output fields, you must provide that value as well as your report or URL argument.

For example, if the source of truth for what was shipped in each release is:

• a list of GitHub pull requests or issues:

  # Bundle changelogs from a PR list ({lifecycle} → "ga" inferred from "9.2.0")
  docs-builder changelog bundle elasticsearch-release 9.2.0 ./prs.txt
  		

  ... where prs.txt is a newline delimited file with PR or issue URLs like this this:

  https://github.com/elastic/kibana/pull/123
  https://github.com/elastic/kibana/pull/456
  		

• a buildkite promotion report:

  # Bundle changelogs from a buildkite report ({version} → "2026-02-13")
  docs-builder changelog bundle serverless-report 2026-02-13 ./promotion-report.html
  		

• automated release notes for GitHub releases:

  # Bundle changelogs from the release notes of a specific GitHub tag
  docs-builder changelog bundle agent-gh-release v1.34.1
  
  # Use "latest" to fetch the most recent release
  docs-builder changelog bundle agent-gh-release latest
  		

  Alternatively, use the changelog gh-release command, which creates the changelogs and bundles at the same time.

  Note

  This method requires a GITHUB_TOKEN or GH_TOKEN environment variable (or an active gh login) to fetch release details from the GitHub API.

• all changelog files that exist in a specific folder:

  docs-builder changelog bundle release-all '*'
  		

• all changelog files that match specific products, versions, and lifecycles:

  # Bundle changelogs with partial dates
  docs-builder changelog bundle serverless-monthly 2026-02
  
  # Bundle changelogs for a GA release ({lifecycle} → "ga" inferred from "9.2.0")
  docs-builder changelog bundle elasticsearch-with-lifecycle 9.2.0
  
  # Bundle changelogs for a beta release ({lifecycle} → "beta" inferred from "9.2.0-beta.1")
  docs-builder changelog bundle elasticsearch-with-lifecycle 9.2.0-beta.1
  		

By default all changelogs that match the chosen source of truth are included in the bundle.

To apply additional filtering by the changelog type, areas, or products, add bundle rules.

When you need to add changelogs to an existing bundle, you can use the docs-builder changelog bundle-amend command, which creates amend bundles. For example:

docs-builder changelog bundle-amend \
  ./docs/releases/9.3.0.yaml \
  --add "./docs/changelog/138723.yaml,./docs/changelog/1770424335.yaml"
		

Amend bundles follow a specific naming convention: {parent-bundle-name}.amend-{N}.yaml where {N} is a sequence number.

When bundles are turned into docs (either via the changelog render command or the {changelog} directive), amend files are automatically merged with their parent bundles. The changelogs from all matching amend files are combined with the parent bundle's changelogs and the result is rendered as a single release.

For more details and examples, go to changelog bundle-amend cli command.

A single changelog file might be applicable to multiple releases (for example, it might be delivered in both Stack and Serverless releases or Elastic Cloud Hosted and Enterprise releases on different timelines). After it has been included in all of the relevant bundles, it is reasonable to delete the changelog to keep your repository clean.

You can use the docs-builder changelog remove command to remove changelogs. If you created profiles, you can use them like this:

docs-builder changelog remove <profile> <version|report|url-list>
		

For example, if the source of truth for what was shipped in each release is:

• a list of GitHub pull requests or issues:

  docs-builder changelog remove elasticsearch-release ./prs.txt
  		

• a buildkite promotion report:

  docs-builder changelog remove serverless-report ./promotion-report.html
  		

• automated release notes for GitHub releases:

  docs-builder changelog remove agent-gh-release 1.34.1
  		

  Note

  This method requires a GITHUB_TOKEN or GH_TOKEN environment variable (or an active gh login) to fetch release details from the GitHub API.

• all changelog files that exist in a specific folder:

  docs-builder changelog remove release-all '*'
  		

• all changelog files that match specific products, versions, and lifecycles:

  docs-builder changelog remove serverless-monthly 2026-02
  		

Before deleting, the command automatically scans for bundles that still hold unresolved (file:) references to the matching changelog files. If any are found, the command reports an error for each dependency. This check prevents the {changelog} directive from failing at build time with missing file errors. To proceed with removal even when unresolved bundle dependencies exist, use --force.

To preview what would be removed without deleting anything, use --dry-run.

For full option details, go to changelog remove cli command.

The following sections provide more details about optional and advanced steps.

If you want to automatically include or exclude changelogs from bundles based on their areas, types, or products, you can accomplish this with rules in your changelog configuration file. Bundle rules run as a secondary stage after the candidate changelogs are collected (for example, based on a PR list, promotion report, or other valid source of truth).

For example, you might choose to omit other or docs types of changelogs. Or you might choose to omit all changelogs related to specific features (areas) from a product's release bundles.

You can define rules at the global level (applies to all products) like this:

rules:
  bundle:
    exclude_products: elasticsearch
    exclude_types: deprecation
    exclude_areas:
      - Internal
		

Alternatively, you can define product-specific rules:

rules:
  bundle:
    products:
      cloud-serverless:
        include_areas:
          - "Search"
          - "Monitoring"
      elasticsearch:
        exclude_areas:
          - Autoscaling
		

Product-specific rules override the global rules entirely—they do not merge. For details, refer to Changelog configuration reference > rules.bundle and Changelog configuration reference > Advanced rule examples.

Changelogs have an optional feature-id field that you can use to associate the change with a specific feature or project. If there are features or projects that are not yet ready for public documentation, you can list those IDs in the hide_features setting:

bundle:
  directory: docs/changelog
  output_directory: docs/releases
  repo: elasticsearch
  owner: elastic
  resolve: true
  profiles:
    serverless-report:
      output: "serverless/{version}.yaml"
      output_products: "cloud-serverless {version}"
      hide_features:
        - feature-flag-1
        - feature-flag-2
		

1. The feature identifiers to hide.

When you use this profile to create a bundle, the list is carried forward into its metadata. Any changelogs with matching feature-id values are commented out when you publish the bundle.

A changelog can reference multiple pull requests and issues in its prs and issues fields. You can allowlist links to certain repos with the link_allow_repos setting. For example:

bundle:
  directory: docs/changelog
  output_directory: docs/releases
  repo: elasticsearch
  owner: elastic
  resolve: true
  link_allow_repos:
    - elastic/elasticsearch
    - elastic/kibana
    - elastic/roadmap
		

1. Only links to these owner/repo pairs are shown in the release docs. Others are rewritten to # PRIVATE: sentinels.

There are no implicit values for this setting. You must list every repo whose links should appear, including the current repo. When this setting is omitted entirely, no link filtering is applied.

If you are working in a private repo and do not want any pull request or issue links to appear (even if they target a public repo), you can also configure link visibility in the changelog directive and changelog render command.

After you've created release bundles, you can use them to generate release docs.