Create changelogs

You can use docs-builder changelog commands to create data files ("changelogs") for each notable change in your GitHub repository. These files are ultimately used to generate release documentation.

Every changelog is the same YAML schema. However, some fields are required or optional depending on the context.

This page describes how to create these files both from the command line and from GitHub actions.

Create a changelog configuration file to define all the default behavior and PR label mappings. Refer to Configure changelogs.

These steps describe how to use the changelog add and changelog note commands to create changelog YAML files. If you already have automated release notes for GitHub releases, you can use the changelog gh-release command instead.

1. If you're accessing private repositories or creating a large number of changelogs, log into GitHub or set the GITHUB_TOKEN (or GH_TOKEN ) environment variable with a sufficient personal access token. Refer to Authorization.

2. Run the changelog add or changelog note command in your GitHub repo's root directory.

   • Create a changelog that references a GitHub pull request:

     docs-builder changelog add \
     --prs https://github.com/elastic/elasticsearch/pull/137598
     		

     The --prs value can be a full URL (such as https://github.com/owner/repo/pull/123), a short format (such as owner/repo#123), just a number, or a path to a file containing newline-delimited PR URLs. Multiple PRs can be provided comma-separated. One changelog is created for each PR.

     When you specify --prs or --issues, the command tries to fetch information from GitHub. It derives the title from the pull request or issue title, extracts linked references, and derives the areas, products, and type from labels (if mappings are defined in the configuration file). To control what information is extracted, refer to the extract and pivot sections of the changelog configuration file.

     Note

     This type of changelog does not contain products[].versions. If you specify --products with a version or date, the changelog add command returns an error.

     Release bundles are created from PR lists or GitHub tags thus prs is sufficient to map these changelogs to releases.

   • Create a changelog that does not reference a GitHub pull request:

     docs-builder changelog note \
     --title "Alerts aren't generated for rules with alert flapping off and an alert delay higher than 1" \
     --type known-issue \
     --products "cloud-serverless 2025-10-25" \
     --action 'Set the alert delay value to 1 or turn on "Alert flapping detection".'
     		

     Note

     This type of changelog requires products[].versions. If you specify --products without a version or date, the changelog note command returns an error.

     These files don't have prs and thus don't appear in a release's PR list. The products[].versions are used to add these files to release bundles automatically.

     Title, type, and products (including version or date) are the minimal details required when you are not deriving details from a PR.

   Tip

   Any command strings that contain special characters (such as backquotes) must be preceded with a backslash escape character (\).

   For the most up-to-date command syntax, use the -h option or refer to changelog add cli command and changelog note cli command.

3. Review the output file.

For details about this method, refer to the README.

When automated via the changelog GitHub Actions, changelog creation is a two-step process:

1. changelog evaluate-pr inspects the PR (title, labels, body) and produces outputs such as title, type, description, and products.
2. changelog add reads those outputs from CHANGELOG_* environment variables and generates the changelog YAML file.

The description output from step 1 contains the release note extracted from the PR body (when extract.release_notes is enabled). If extraction is disabled (either by setting extract.release_notes: false in changelog.yml or by passing --no-extract-release-notes to changelog add), the CHANGELOG_DESCRIPTION environment variable is ignored and the extracted description is not written to the changelog.

Refer to CI auto-detection for the full list of environment variables and precedence rules.

1. Find the files that were created by the command or GitHub action.

   You can specify the file location with command options (--output) or configuration options (bundle.directory). Likewise you can control the file names with command options (--use-issue-number or --use-pr-number) or the filename configuration option. Refer to the Filenames.

2. Verify that the files contain content that is accurate and user-friendly. This review is especially important when you're pulling content from GitHub, since there might be some missing or extraneous information.

Changelog files use the following schema:

##### Required fields #####
title:

# A required string that is a short, user-facing headline
# Max 80 characters

type:

# A required string that contains the type of change.
# For the acceptable values, refer to https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntryType.cs
products:

# A required array of objects that denote the affected products.

    - product:

      # A required string with a predefined product ID used for release note routing,
      # filters, and categorization.
      # Refer to https://github.com/elastic/docs-builder/blob/main/config/products.yml for the acceptable values.

      versions:

      # Required when the changelog is not tied to a pull request (known issues, advisories).
      # Omit this field when `prs` attaches the change to a release.
      # Use a YAML list such as [9.3.0, 9.4.0], not "*" and not a pipe-separated string.

      lifecycle:

      # An optional string for new features and enhancements that have a specific availability.
      # For the acceptable values, refer to https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/Lifecycle.cs

##### Optional fields #####
action:

# An optional string that describes what users must do to mitigate the impact
# of a breaking change or known issue.

areas:

# An optional array of strings that denotes the parts/components/services of the
# product that are specifically affected.
# The list of valid values will vary by product.
# The docs for each release typically group the changes by type then by area.

description:

# An optional string that provides additional information about what has changed.
# Max 600 characters

feature-id:

# An optional string to associate a feature or enhancement with a unique feature flag

highlight:

# An optional boolean for items that should be included in release highlights
# or the UI to draw users' attention.

impact:

# An optional string that describes how the user's environment is/will be
# affected by a breaking change.

issues:

# An optional array of strings that contain URLs for issues that are relevant to the PR.
# They are externalized in the release docs so users can follow the links and
# understand the context.

prs:

# An optional array of pull request identifiers (URLs or numbers).
# Each value is externalized in the release docs so users can follow the links and find more details.

subtype:

# An optional string that applies only to breaking changes and further subdivides that type.
# For the acceptable values, refer to https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ChangelogEntrySubtype.cs
		

For content guidelines, go to Changelogs.

If you want to automatically block the creation of changelogs for pull requests or issues based on their labels, you can accomplish this with rules in your changelog configuration file. For example, your changelog.yml file can contain a rules.create section like this:

rules:
  # Create — controls which PRs generate changelogs.
  create:
    # Labels that block changelog creation (comma-separated string)
    exclude: ">non-issue"
    # Product-specific overrides
    products:
      'cloud-serverless':
        exclude: ">non-issue, >test"
		

You can define rules at the global level (applies to all products) or for specific products (cloud-serverless in this example). Product-specific rules override the global rules entirely—they do not merge.

When you run the docs-builder changelog add command with the --prs or --issues options and the pull request or issue has one of the identified labels, the command does not create a changelog. For example:

docs-builder changelog add --prs "1234, 5678" \
  --products "cloud-serverless"
		

If PR 1234 has the >non-issue or >test labels, it will be skipped and no changelog will be created. If PR 5678 does not have any blocking labels, a changelog is created.

Alternatively, you can define rules.create.include to only create changelogs for PRs with specific labels:

rules:
  create:
    include: "@Public, @Notable"
		

For more information about these changelog configuration settings, refer to Changelog configuration reference > rules.create.

You can create multiple changelogs in a single command by providing a newline-delimited file that contains pull requests or issues. For example:

# Create a file with PRs (one per line)
cat > prs.txt << EOF
https://github.com/elastic/elasticsearch/pull/1234
https://github.com/elastic/elasticsearch/pull/5678
EOF

# Use the file with --prs
docs-builder changelog add --prs prs.txt \
  --products "elasticsearch ga"
		

In this example, the command creates one changelog for each pull request in the list.

If you have GitHub releases with automated release notes (the default format or Release Drafter format), the changelog commands can derive the PR list from those release notes with the --release-version option. For example:

docs-builder changelog add --release-version v1.34.0
		

This command creates one changelog file per PR found in the v1.34.0 GitHub release notes. The product ID and lifecycle in each file can be inferred from the repository name and configuration. The files do not include a version field; which product release they belong to is determined by the origin branch.

You can use the docs-builder changelog gh-release command as a one-shot alternative to changelog add and changelog bundle commands. The command parses the release notes, creates one changelog file per pull request found, and creates a changelog-bundle.yaml file — all in a single step. Refer to changelog gh-release cli command.

Some teams have historically had a dedicated page for release highlights. To accommodate this behavior, changelogs have an optional highlight boolean field. Highlights are most commonly used for major or minor version releases to draw attention to the most important changes. Any type of changelog (such as features, enhancements, or bug fixes) can be a highlight, though they're typically associated with type: feature.

Example changelog for a release highlight:

type: feature
products:
- product: elasticsearch
  lifecycle: ga
title: ES|QL Views support
description: 'ES|QL now supports Views: virtual indices whose fields are produced by an ES|QL query. A view is referenced inside a FROM clause exactly like a regular index....'
highlight: true
		

When you set highlight: true in a changelog, it appears in both the highlights page (for example, highlights.md in markdown output) and its normal type section (for example, index.md).

After you've created a changelog files, you can gather them into release bundles. The release bundles are ultimately used to generate release docs.