changelog add cli command

docs-builder changelog add [options]
		

Create a changelog file that describes a single item in the release documentation. For details and examples, go to Create changelogs.

--products string

Products affected in format "product target lifecycle, ..." (for example, "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"). The valid product identifiers are listed in products.yml. For more information about valid product and lifecycle values, go to Product format.

--action string

Optional: What users must do to mitigate

--areas string[]

Optional: Area(s) affected (comma-separated or specify multiple times)

Repeatable: pass --areas multiple times to supply more than one value

--[no-]concise

Optional: Omit schema reference comments from generated YAML files. Useful in CI to produce compact output.

Default: false

--config string

Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml'

Constraints: symbolic links not allowed, must exist, extensions: yml, yaml, supports ~ home expansion

--description string

Optional: Additional information about the change (max 600 characters)

--[no-]no-extract-release-notes

Turn off extraction of release notes from PR or issue descriptions. By default, the behavior is determined by the extract.release_notes changelog configuration setting. Release notes are extracted when using --prs or --report (and from issues when using --issues).

Default: false

--[no-]no-extract-issues

Optional: Turn off extraction of linked references. When using --prs: turns off extraction of linked issues from the PR body (e.g., "Fixes #123"). When using --issues: turns off extraction of linked PRs from the issue body (e.g., "Fixed by #123"). By default, linked references are extracted in both cases.

Default: false

--feature-id string

Optional: Feature flag ID

--[no-]highlight

Optional: Include in release highlights

--impact string

Optional: How the user's environment is affected

--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. Each occurrence can be either comma-separated issues (e.g., --issues "https://github.com/owner/repo/issues/123,456") or a file path (e.g., --issues /path/to/file.txt). If --owner and --repo are provided, issue numbers can be used instead of URLs. If specified, --title can be derived from the issue. Creates one changelog file per issue. Mutually exclusive with --release-version and --report.

Repeatable: pass --issues multiple times to supply more than one value

--owner string

Optional: GitHub repository owner (used when --prs or --issues contains just numbers, or when using --release-version). Falls back to bundle.owner in changelog.yml when not specified. If that value is also absent, "elastic" is used.

--output string

Optional: Output directory for the changelog. Falls back to bundle.directory in changelog.yml when not specified. Defaults to current directory.

--prs string[]

Optional: Pull request URL(s) or PR number(s) (comma-separated), or a path to a newline-delimited file containing PR URLs or numbers. Can be specified multiple times. Each occurrence can be either comma-separated PRs (e.g., --prs "https://github.com/owner/repo/pull/123,6789") or a file path (e.g., --prs /path/to/file.txt). When specifying PRs directly, provide comma-separated values. When specifying a file path, provide a single value that points to a newline-delimited file. If --owner and --repo are provided, PR numbers can be used instead of URLs. If specified, --title can be derived from the PR. If mappings are configured, --areas and --type can also be derived from the PR. Creates one changelog file per PR. Mutually exclusive with --release-version and --report.

Repeatable: pass --prs multiple times to supply more than one value

--report string

Optional: URL or file path to a promotion report HTML document. Extracts GitHub pull request URLs and creates one changelog per PR (same parsing as changelog bundle --report). Mutually exclusive with --prs, --issues, and --release-version.

--release-version string

Optional: GitHub release tag to fetch PRs from (e.g., "v9.2.0" or "latest"). When specified, creates one changelog per PR in the release notes. Requires --repo (or bundle.repo in changelog.yml). Mutually exclusive with --prs, --issues, and --report. Does not create a bundle; use 'changelog gh-release' for that.

--repo string

Optional: GitHub repository name (used when --prs or --issues contains just numbers, or when using --release-version). Falls back to bundle.repo in changelog.yml when not specified.

--[no-]strip-title-prefix

Optional: When used with --prs or --report, remove square brackets and text within them from the beginning of PR titles, and also remove a colon if it follows the closing bracket (e.g., "[Inference API] Title" becomes "Title", "[ES|QL]: Title" becomes "Title", "[Discover][ESQL] Title" becomes "Title")

Default: false

--subtype string

Optional: Subtype for breaking changes (api, behavioral, configuration, etc.)

--title string

Optional: A short, user-facing title (max 80 characters). Required if neither --prs, --issues, nor --report is specified. If --prs and --title are specified, the latter value is used instead of what exists in the PR.

--type string

Optional: Type of change (feature, enhancement, bug-fix, breaking-change, etc.). Required if neither --prs, --issues, nor --report is specified. If mappings are configured, type can be derived from the PR or issue.

--[no-]use-pr-number

Use PR numbers for filenames instead of the configured filename strategy. Requires --prs, --issues, or --report. Mutually exclusive with --use-issue-number. Refer to Filenames.

Default: false

--[no-]use-issue-number

Use issue numbers for filenames instead of the configured filename strategy. Requires --prs or --issues. Mutually exclusive with --use-pr-number. Refer to Filenames.

Default: false

-l --log-level enum

Minimum log level.

Values: trace, debug, information, warning, error, critical, none

Default: information

-c --config-source enum

Override the configuration source: local, remote

Values: local, remote, embedded

--[no-]skip-private-repositories

Skip cloning private repositories

By default, output files are named according to the filename strategy in changelog.yml:

Refer to changelog.example.yml or Changelog configuration reference.

You can override those settings with the --use-pr-number or --use-issue-number flags:

docs-builder changelog add \
  --prs 1234 \
  --products "elasticsearch 9.2.3" \
  --use-pr-number

docs-builder changelog add \
  --issues 4567 \
  --products "elasticsearch 9.3.0" \
  --use-issue-number
		

The --products option accepts values with the format "product target lifecycle, ..." where:

• product is a product ID that exists in products.yml (required)
• target is the target version or date (optional)
• lifecycle exists in Lifecycle.cs (optional)

You can further limit the possible values with the products and lifecycles options in the changelog configuration file.

For example:

• "kibana 9.2.0 ga"
• "cloud-serverless 2025-08-05"
• "cloud-enterprise 4.0.3, cloud-hosted 2025-10-31"

The changelog add command resolves product values in the following order:

1. The --products CLI option always takes priority.
2. If pivot.products is defined in the changelog configuration file and the PR or issue has labels that match, those products are used. Multiple matching entries are all applied.
3. If products.default is defined in the changelog configuration file, those default products are used.
4. If --repo is specified (or bundle.repo is set in the changelog configuration file), the repository name is matched against known product IDs in products.yml and the derived value is used.

The same order applies when using --report (after PR URLs are resolved from the promotion report), and when using batch --prs with multiple pull requests.

If none of these steps yield at least one product, the command returns an error.

By default, the command checks docs/changelog.yml for a configuration file. You can specify a different path with --config.

If a configuration file exists, the command validates its values before generating changelog files:

• If the configuration file contains lifecycles, products, subtype, or type values that don't match the known valid values, validation fails.
• If the configuration file contains areas values and they don't match what you specify in --areas, validation fails.
• If the configuration file contains lifecycles or products values that are a subset of the available values and you try to create a changelog with values outside that subset, validation fails.

In each of these cases where validation fails, a changelog file is not created.

If the configuration file contains rules.create definitions and a PR or issue has a blocking label, that PR is skipped and no changelog file is created for it. For more information, refer to Create changelogs > Control changelog creation.

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

Explicit CLI arguments always take priority over environment variables.

CHANGELOG_DESCRIPTION has additional precedence rules related to release note extraction:

• If --description is provided on the command line, it always wins.
• If --no-extract-release-notes is passed (or extract.release_notes: false is set in the changelog configuration), CHANGELOG_DESCRIPTION is ignored.
• Otherwise, CHANGELOG_DESCRIPTION fills --description when it is not set on the command line.

This allows the CI action to invoke changelog add with a minimal command line:

docs-builder changelog add --config docs/changelog.yml --output /tmp/staging --concise --strip-title-prefix