﻿---
title: changelog add
description: Create a changelog file that describes a single item in the release documentation. For details and examples, go to Create and bundle changelogs. When...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/cli/release/changelog-add
---

# changelog add
Create a changelog file that describes a single item in the release documentation.
For details and examples, go to [Create and bundle changelogs](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/2927/contribute/changelog).

## Usage

```sh
docs-builder changelog add [options...] [-h|--help]
```


## Options

<definitions>
  <definition term="--action <string?>">
    Optional: What users must do to mitigate.
  </definition>
  <definition term="If the content contains any special characters such as backquotes(`), you must precede it with a backslash escape character (``).">
  </definition>
  <definition term="--areas <string[]?>">
    Optional: Areas affected (comma-separated or specify multiple times).
  </definition>
  <definition term="--concise">
    Optional: Omit schema reference comments from the generated YAML files. Useful in CI workflows to produce compact output.
  </definition>
  <definition term="--config <string?>">
    Optional: Path to the changelog.yml configuration file. Defaults to `docs/changelog.yml`.
  </definition>
  <definition term="--description <string?>">
    Optional: Additional information about the change (max 600 characters).
  </definition>
  <definition term="If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (\).">
  </definition>
  <definition term="--no-extract-release-notes">
    Optional: Turn off extraction of release notes from PR descriptions.
  </definition>
  <definition term="The extractor looks for content in various formats in the PR description:">
  </definition>
  <definition>
    - `Release Notes: ...`
  </definition>
  <definition>
    - `Release-Notes: ...`
  </definition>
  <definition>
    - `release notes: ...`
  </definition>
  <definition>
    - `Release Note: ...`
  </definition>
  <definition>
    - `Release Notes - ...`
  </definition>
  <definition>
    - `## Release Note` (as a markdown header)
  </definition>
  <definition term="Short release notes (≤120 characters, single line) are used as the changelog title (only if --title is not explicitly provided).">
  </definition>
  <definition term="Long release notes (>120 characters or multi-line) are used as the changelog description (only if --description is not explicitly provided).">
  </definition>
  <definition term="By default, the behavior is determined by the extract.release_notes changelog configuration setting.">
  </definition>
  <definition term="--feature-id <string?>">
    Optional: Feature flag ID
  </definition>
  <definition term="--highlight <bool?>">
    Optional: Include in release highlights.
  </definition>
  <definition term="--impact <string?>">
    Optional: How the user's environment is affected.
  </definition>
  <definition term="If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (\).">
  </definition>
  <definition term="--issues <string[]?>">
    Optional: Issue URL(s) or number(s) (comma-separated), or a path to a newline-delimited file containing issue URLs or numbers. Can be specified multiple times.
  </definition>
  <definition term="Each occurrence can be either comma-separated issues (for example --issues "https://github.com/owner/repo/issues/123,456") or a file path (for example --issues /path/to/file.txt).">
  </definition>
  <definition term="When specifying issues directly, provide comma-separated values.">
  </definition>
  <definition term="When specifying a file path, provide a single value that points to a newline-delimited file.">
  </definition>
  <definition term="If --owner and --repo are provided, issue numbers can be used instead of URLs.">
  </definition>
  <definition term="If specified, --title can be derived from the issue.">
  </definition>
  <definition term="Creates one changelog file per issue.">
  </definition>
  <definition term="--no-extract-issues">
    Optional: Turn off extraction of linked references.
  </definition>
  <definition term="When using --prs: turns off extraction of linked issues from the PR body (for example, "Fixes #123").">
  </definition>
  <definition term="When using --issues: turns off extraction of linked PRs from the issue body (for example, "Fixed by #123").">
  </definition>
  <definition term="By default, the behavior is determined by the extract.issues changelog configuration setting.">
  </definition>
  <definition term="--output <string?>">
    Optional: Output directory for the changelog fragment. Falls back to `bundle.directory` in `changelog.yml` when not specified. If that value is also absent, defaults to current directory.
  </definition>
  <definition term="--owner <string?>">
    Optional: GitHub repository owner (used when `--prs` or `--issues` contains just numbers, or when using `--release-version`).
  </definition>
  <definition term="Falls back to bundle.owner in changelog.yml when not specified. If that value is also absent, defaults to elastic.">
  </definition>
  <definition term="--products <List<ProductInfo>>">
    Products affected in format "product target lifecycle, ..." (for example, `"elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"`).
  </definition>
  <definition term="The valid product identifiers are listed in products.yml.">
  </definition>
  <definition term="The valid lifecycles are listed in ChangelogConfiguration.cs.">
  </definition>
  <definition term="Precedence when --products is not specified: products are derived from PR/issue labels via pivot.products label mappings (if configured), then from products.default in changelog.yml, and finally inferred from the current git repository name. An error is raised if no products can be determined by any of these means.">
  </definition>
  <definition term="Refer to Products resolution in the how-to guide for full details.">
  </definition>
  <definition term="--prs <string[]?>">
    Optional: Pull request URLs or numbers (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers. Can be specified multiple times.
  </definition>
  <definition term="Each occurrence can be either comma-separated PRs (for example --prs "https://github.com/owner/repo/pull/123,6789") or a file path (for example --prs /path/to/file.txt).">
  </definition>
  <definition term="When specifying PRs directly, provide comma-separated values.">
  </definition>
  <definition term="When specifying a file path, provide a single value that points to a newline-delimited file.">
  </definition>
  <definition term="If --owner and --repo are provided, PR numbers can be used instead of URLs.">
  </definition>
  <definition term="If specified, --title can be derived from the PR.">
  </definition>
  <definition term="If mappings are configured, --areas, --type, and --products can also be derived from the PR labels.">
  </definition>
  <definition term="Creates one changelog file per PR.">
  </definition>
  <definition term="If there are rules.create definitions in the changelog configuration file and a PR has a blocking label for the resolved products, that PR is skipped and no changelog file is created for it.">
  </definition>
  <definition term="--release-version <string?>">
    Optional: GitHub release tag to use as a source of pull requests (for example, `"v9.2.0"` or `"latest"`).
  </definition>
  <definition term="When specified, the command fetches the release from GitHub, parses PR references from the release notes, and creates one changelog file per PR — without creating a bundle. Only automated GitHub release notes (the default format or Release Drafter format) are supported at this time.">
  </definition>
  <definition term="Use docs-builder changelog gh-release instead if you also want a bundle.">
  </definition>
  <definition term="Requires --repo (or bundle.repo in changelog.yml).">
  </definition>
  <definition term="Set to latest to use the most recent release.">
  </definition>
  <definition term="--repo <string?>">
    Optional: GitHub repository name (used when `--prs`, `--issues`, or `--release-version` is specified). Falls back to `bundle.repo` in `changelog.yml` when not specified.
  </definition>
  <definition term="--strip-title-prefix">
    Optional: When used with `--prs`, remove square brackets and text within them from the beginning of PR titles, and also remove a colon if it follows the closing bracket.
  </definition>
  <definition term="For example, if a PR title is "[Attack discovery]: Improves Attack discovery hallucination detection", the changelog title will be "Improves Attack discovery hallucination detection".">
  </definition>
  <definition term="Multiple square bracket prefixes are also supported (for example "[Discover][ESQL] Fix filtering by multiline string fields" becomes "Fix filtering by multiline string fields").">
  </definition>
  <definition term="This option applies only when the title is derived from the PR (when --title is not explicitly provided).">
  </definition>
  <definition term="By default, the behavior is determined by the extract.strip_title_prefix changelog configuration setting (which defaults to false).">
  </definition>
  <definition term="--subtype <string?>">
    Optional: Subtype for breaking changes (for example, `api`, `behavioral`, or `configuration`).
  </definition>
  <definition term="The valid subtypes are listed in ChangelogConfiguration.cs.">
  </definition>
  <definition term="--title <string>">
    A short, user-facing title (max 80 characters)
  </definition>
  <definition term="Required if neither --prs nor --issues is specified.">
  </definition>
  <definition term="If both --prs and --title are specified, the latter value is used instead of what exists in the PR.">
  </definition>
  <definition term="If the content contains any special characters such as backquotes, you must precede it with a backslash escape character (\).">
  </definition>
  <definition term="--type <string>">
    Required if neither `--prs` nor `--issues` is specified. Type of change (for example, `feature`, `enhancement`, `bug-fix`, or `breaking-change`).
  </definition>
  <definition term="If mappings are configured, type can be derived from the PR or issue.">
  </definition>
  <definition term="The valid types are listed in ChangelogConfiguration.cs.">
  </definition>
  <definition term="--use-pr-number">
    Optional: Use PR numbers for filenames instead of the configured `filename` strategy. With both `--prs` (which creates one changelog per specified PR) and `--issues` (which creates one changelog per specified issue), each changelog filename will be derived from its PR numbers. Requires `--prs` or `--issues`. Mutually exclusive with `--use-issue-number`.
  </definition>
  <definition term="--use-issue-number">
    Optional: Use issue numbers for filenames instead of the configured `filename` strategy. With both `--prs` (which creates one changelog per specified PR) and `--issues` (which creates one changelog per specified issue), each changelog filename will be derived from its issues. Requires `--prs` or `--issues`. Mutually exclusive with `--use-pr-number`.
  </definition>
</definitions>


## CI auto-detection

When running inside GitHub Actions, `changelog add` automatically reads the following environment variables to fill in arguments that were not provided on the command line:

| Environment variable  | Fills     | Set from                           |
|-----------------------|-----------|------------------------------------|
| `CHANGELOG_PR_NUMBER` | `--prs`   | `github.event.pull_request.number` |
| `CHANGELOG_TITLE`     | `--title` | `steps.evaluate.outputs.title`     |
| `CHANGELOG_TYPE`      | `--type`  | `steps.evaluate.outputs.type`      |
| `CHANGELOG_OWNER`     | `--owner` | `github.repository_owner`          |
| `CHANGELOG_REPO`      | `--repo`  | `github.event.repository.name`     |

**Precedence**: explicit CLI arguments always take priority over environment variables. Environment variables are only used when the corresponding CLI argument is not provided.
The filename strategy is controlled by the `filename` option in `changelog.yml` (defaulting to `timestamp`). Refer to [changelog.example.yml](https://github.com/elastic/docs-builder/blob/main/config/changelog.example.yml) for details.
This allows the CI action to invoke `changelog add` with a minimal command line:
```sh
docs-builder changelog add --config docs/changelog.yml --output /tmp/staging --concise --strip-title-prefix
```


## Products resolution

When you run the `changelog add` command without the `--products` option, it resolves products in the following order:
1. **`--products` CLI option** — always takes priority.
2. **`pivot.products` label mapping** — if `pivot.products` is configured and the PR or issue has labels that match, those products are used. Multiple matching entries are all applied.
3. **`products.default` in `changelog.yml`** — the configured default products are used.
4. **Repository name inference** — if `--repo` is specified (or `bundle.repo` is set in `changelog.yml`), the repository name is matched against known product IDs in `products.yml`.
5. **Error** — if none of the above resolves to at least one product, an error is raised.

Product-specific `rules.create` rules are evaluated *after* products are resolved from labels, so label-derived products correctly participate in per-product create rule checks.