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.

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 command. 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 command in your GitHub repo's root directory. For example:

   docs-builder changelog add \
   --title "Improve SAML error handling by adding metadata"
   --type enhancement
   --products "elasticsearch 9.2.8, cloud-serverless 2026-02-02"
   		

   Title, type, and products are the minimal details required for each changelog file.

   Tip

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

   Alternatively, pull the information from GitHub:

   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.

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

3. Review the output file.

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 and their target release.

    - 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.

      target:

      # An optional string that facilitates pre-release doc previews.
      # For products with version releases, it contains the target version number (V.R.M).
      # For products with date releases, it contains the target release date
      # or the date the PR was merged.

      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.

You can prevent changelog creation for PRs based on their labels. For example, your configuration 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"
		

Those settings affect commands with the --prs or --issues options, 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 labels. For example, 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 9.2.0 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, target version, and lifecycle in each changelog are inferred automatically from the release tag and the repository name. For example, a tag of v1.34.0 in the apm-agent-dotnet repo creates changelogs with product: apm-agent-dotnet, target: 1.34.0, and lifecycle: ga.

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