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.

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

Named profiles simplify bundle creation for different release scenarios. Profiles work with both changelog bundle and changelog remove commands.

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

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.

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.

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"
		

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.

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.