changelog add cli command

docs-builder changelog add [options]

Create a new changelog entry YAML file.

Options

--products string

Optional: Products affected in format "product target lifecycle, ..." (e.g., "elasticsearch 9.2.0 ga, cloud-serverless 2025-08-05"). If not specified, will be inferred from repository or config defaults.

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

Optional: Turn off extraction of release notes from PR descriptions. By default, release notes are extracted when using --prs. Matched release note text is used as the changelog description (only if --description is not explicitly provided). The changelog title comes from --title or the PR title, not from the release note section.

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

Optional: Use PR numbers for filenames instead of timestamp-slug. With --prs, --report, or --issues (where PRs are resolved), each changelog filename will be derived from its PR numbers. Requires --prs, --report, or --issues. Mutually exclusive with --use-issue-number.

Default: false

--[no-]use-issue-number

Optional: Use issue numbers for filenames instead of timestamp-slug. 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.

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