Changelog configuration reference

The changelog configuration file contains settings to make the creation of changelog files and bundles more consistent and repeatable.
By default, it's named docs/changelog.yml.

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

These are the main configuration sections:

Configures directory paths, GitHub repository defaults, and named profiles for bundle operations. These settings are separate from rules.bundle filtering.

Refer to:

• Basic bundle settings
• Bundle descriptions
• Bundle profiles

Controls bundle-level behavior. These settings are relevant to one or all of the changelog bundle, changelog gh-release, and changelog remove commands.

You can add introductory text to bundles using the description field. This text appears at the top of rendered changelogs, after the release heading but before the entry sections.

When using profiles, you can provide this information in:

• bundle.description: Default description for all profiles
• bundle.profiles.<name>.description: Profile-specific description (overrides the default)

Bundle descriptions support these {version}, {lifecycle}, {owner}, and {repo} substitution variables. When using {version} or {lifecycle}, you must provide the necessary version argument in the command (for example, bundle profile 9.2.0) or define output_products in your configuration file.

For complex descriptions with multiple paragraphs, lists, and links, use YAML literal block scalars with the | (pipe) syntax:

bundle:
  description: |
    This release includes significant improvements:

    - Enhanced performance
    - Bug fixes and stability improvements
    - New features for better user experience

    For security updates, go to [security announcements](https://example.com/docs).

    Download the release binaries: https://github.com/{owner}/{repo}/releases/tag/v{version}
		

The | (pipe) preserves line breaks and is ideal for Markdown-formatted text. Avoid using > (greater than) for descriptions as it folds line breaks into spaces, making lists and paragraphs difficult to format correctly.

Named profiles enable you to run commands repeatedly with consistent options. They work with both changelog bundle and changelog remove commands.

These settings are located in the bundle.profiles.<name> section of the configuration file:

description

Overrides the global bundle.description.

hide_features

Feature IDs to mark as hidden in the bundle.

When the bundle is rendered, entries with matching feature-id values are commented out.

output

The output filename pattern for the bundle file.

Supports {version} and {lifecycle} placeholders.

When not set, the output path falls back in order to: bundle.output_directory/changelog-bundle.yaml (if bundle.output_directory is configured), then changelog-bundle.yaml in the input directory.

Setting this is recommended so each profile produces a distinctly named file rather than overwriting the default.

Example: "elasticsearch/{version}.yaml"

output_products

The bundle's products metadata, which affects the bundle rules that are applied and the product and version titles that ultimately appear in documentation.

Supports {version} and {lifecycle} placeholders.

When not set, the products array is derived from the individual changelog files matched by the filter. This often produces multiple product entries (one per unique product/target/lifecycle combination across all matched files), which may not reflect a single clean release identity.

When set, the products array in the bundle is exactly the value you specify, replacing anything that would be derived from the matched changelogs. Use this to publish a single, authoritative product entry with a specific version and lifecycle.

The {lifecycle} placeholder is substituted at runtime with the inferred lifecycle. For source: github_release profiles this comes from the release tag suffix. For standard profiles it comes from the version argument. Refer to changelog bundle cli command > Lifecycle inference.

If you omit lifecycle from the pattern (for example, "elasticsearch {version}"), the lifecycle field is omitted from the products array entirely.

Example: "elasticsearch {version} {lifecycle}" or "elasticsearch {version} ga" to hardcode GA regardless of tag.

Refer to changelog bundle cli command > Product format.

owner

Overrides bundle.owner.

products

Derive the list of changelogs by matching their products values (equivalent to the --input-products command option).

Not used when the source of truth for the release is a promotion report, URL list file, or source: github_release; in those cases this setting is ignored.

Supports {version} and {lifecycle} placeholders that are substituted at runtime.

The value "* * *" is equivalent to the --all command option.

Example: "elasticsearch {version} {lifecycle}"

Refer to changelog bundle cli command > Product format.

release_dates

Overrides bundle.release_dates.

repo

Overrides bundle.repo.

Required when source: github_release is used and bundle.repo is not set.

source

Derive the list of changelogs from the specified source.

Only github_release is currently supported (equivalent to the --release-version command option), which means a PR list is fetched from the GitHub release identified by the version argument.

Requires repo to be set at the profile or bundle level.

Mutually exclusive with products.

Example: source: github_release

Example profile usage:

docs-builder changelog bundle elasticsearch-release 9.2.0
docs-builder changelog remove elasticsearch-release 9.2.0
		

Controls how the changelog add command extracts information from PR descriptions and titles.

When extract.issues is true, the system looks for patterns like "Fixes #123" in PR bodies (when you're creating changelogs from PRs) or "Fixed by #123" in issue bodies (when you're creating changelogs from issues).

When extract.release_notes is true, the system looks for content like this in the PR or issue description:

• Release Notes: ...
• Release-Notes: ...
• release notes: ...
• Release Note: ...
• Release Notes - ...
• ## Release Note (as a markdown header)

The extracted release note text is used in the changelog description.

When extract.strip_title_prefix is true:

• The separator hyphen is removed only when at least one bracket prefix was stripped; PR titles that intentionally start with - followed by whitespace and have no bracket prefix are left unchanged.
• Titles that still begin with -, *, +, an en dash (U+2013), or an em dash (U+2014) are surrounded in quotes so they're not parsed as list markers.
• The title cleanup only occurs when the title is derived from GitHub. If you specify --title explicitly, that title is used as-is without any prefix stripping.

Controls how the changelog add command generates changelog file names.

Specifies the allowed lifecycle values for your changelogs.

You can specify lifecycles as a comma-separated string ("preview, beta, ga") or as a YAML list.

Specifies the allowed area, type, and subtype values for your changelogs. Also controls how the changelog add command maps GitHub labels to various changelog fields.

The following example demonstrates some GitHub label mappings in the pivot section of the changelog configuration file:

pivot:
  types:
    # Example mappings - customize based on your label naming conventions
    breaking-change:
      labels: ">breaking, >bc"
    bug-fix: ">bug"
    enhancement: ">enhancement"
  areas:
    # Example mappings - customize based on your label naming conventions
    Autoscaling: ":Distributed Coordination/Autoscaling"
    "ES|QL": ":Search Relevance/ES|QL"
  products:
    'elasticsearch':
      - ":product/elasticsearch"
    'cloud-serverless':
      - ":product/serverless"
		

Specifies the allowed product values and the default values used by the changelog add command.

Example:

products:
  available: ["elasticsearch", "cloud-serverless"]
  default:
    - product: elasticsearch
      lifecycle: ga
		

Provides two key ways to customize the changelog workflow:

• rules.create defines GitHub labels that turn changelog creation on or off
• rules.bundle defines changelog types, areas, or product combinations that are included or excluded from release bundles

Understanding these rules is essential for managing large-scale changelog workflows with multiple products and release patterns.

Defines global default match behavior for all rules.

If a lower-level match or match_areas is specified (for example, rules.create.match or rules.bundle.match_areas), it overrides the inherited value.

Defines the PR or issue labels that affect the creation of changelogs. These rules affect the docs-builder changelog add command when it's pulling information from GitHub (for example using --prs or --issues command options).

These settings are located in the rules.create section of the configuration file:

Product keys in rules.create.products can be a single product ID or a comma-separated list of product IDs (for example, 'elasticsearch, kibana'). Product-specific rules override the global create rules entirely.

rules:
  create:
    exclude: ">non-issue"
    products:
      'elasticsearch, kibana':
        exclude: ">test"
      cloud-serverless:
        exclude: ">non-issue, ILM"
		

For more context, go to Create changelogs > Control changelog creation.

Controls which changelogs are included in bundles. These rules are applied by the docs-builder changelog bundle and docs-builder changelog gh-release commands after the primary filter (--prs, --issues, --all, or --input-products) has identified the relevant changelogs and before the bundle is written.

These settings are located in the rules.bundle section of the configuration file:

For examples, go to Changelog configuration reference > Product matching behavior.

The way bundle rules are applied can be broken down into three "modes":

1 — No filtering

This mode applies when there is no effective bundle rule.

No changelogs are filtered out of the bundle based on their product, type, or area.

2 — Global rules

This mode applies when there's at least one global bundle rule set and the rules.bundle.products section is absent or empty (products: {}).

Global rules are evaluated against each changelog's own products, type, and areas.

There is no single product used for the rule context and no disjoint exclusion.

Changelogs with missing or empty products are included with a warning; global product "include" or "exclude" lists are skipped for those entries, global type and area rules still apply.

3 — Product-specific rules

This mode applies when the rules.bundle.products section is not absent or empty.

The bundle uses a single product for its rule context.

Disjoint changelogs are excluded and changelogs with missing or empty products are excluded with a warning.

Global rules.bundle are not used for filtering.

Refer to Changelog configuration reference > Product-specific bundle rules.

Changelog commands emit a hint when both global bundle fields and a non-empty products map are present because global keys are ignored in Mode 3. The changelog bundle and changelog gh-release commands also emit informational messages when rules cause changelogs to be omitted from the bundle.

The following sections provide details and examples for some of the more complicated bundle rule scenarios.

The following table demonstates the impact of area-related bundle rules:

As described in match settings, the conjunction value means every area in the config list must appear in the changelog.

The following table demonstates the impact of global ("Mode 2") bundle rule match settings:

The impact of the match_products setting differs depending on the mode. For product-specific ("Mode 3") details, refer to Changelog configuration reference > Product-specific bundle rules.

In practice, most changelogs have a single product, so any (the default) and all behave identically for them. The difference only matters for changelogs with multiple products.

This section provides more detailed information about "mode 3" product-specific bundle rules.

Product keys in rules.bundle.products can be a single product ID or a comma-separated list of product IDs (for example, 'elasticsearch, kibana') if you want an identical set of rules for multiple products.

When you create a bundle, only a single product-specific bundle rule can apply (we cannot combine multiple products' rules). A single rule-context product must therefore be determined for each bundle. In cases where a bundle is associated with multiple products, a single rule-context product is automatically determined as follows:

• If the --output-products (CLI) or output_products (profile) option is specified, it's the first product alphabetically from that list
• Otherwise, it's the first product alphabetically from all products aggregated from changelogs that passed the primary filter (--all, --prs, --issues, or --input-products) to be candidates for inclusion in the bundle.

The bundle's rule-context product affects how rules are applied to each changelog, as follows:

• If a changelog contains the rule-context product in its products list and product-specific rules exist for that product, the rules are applied and the changelog is included or excluded accordingly.
• If a changelog does not contain the rule-context product in its products list it is disjoint from the rule context and excluded from the bundle.
• If there are no products in the changelog or it's empty, a warning occurs and it's excluded the changelog.

For example, if you create a bundle with --output-products "kibana 9.3.0, security 9.3.0" the derived rule-context product is kibana and it affects the changelogs as follows:

For release notes that need different rule behavior per product, run separate changelog bundle invocations with a single product in --output-products (or a profile whose output_products resolves to one product). Alternatively, use Mode 2 (global-only rules.bundle) when you need OR-style product inclusion without disjoint exclusion.

You can define all the same area, product, and type rules (such as include_products, exclude_types, include_areas, and match_areas) as described in Changelog configuration reference > rules.bundle. However, in this context, include_products can only affect changelogs that already contain the rule context product. It cannot pull in changelogs that are disjoint from that context.

The following example demonstrates how per-product rules replace global rules:

rules:
  bundle:
    exclude_types: [docs]
    exclude_areas: [Internal]
    products:
      kibana:
        include_areas: [UI]
		

The result when the rule context product is kibana is as follows:

• Changelogs that have only elasticsearch product IDs are excluded as disjoint.
• Changelogs that have kibana product IDs have the appropriate product-specific rules applied. Global exclude_types and exclude_areas rules are not applied. Add exclude_types under kibana if you still need to exclude docs types.