changelog note cli command

docs-builder changelog note [options]

Create a changelog YAML for content that is not tied to a pull request. Typical uses are known issues and security advisories. For details and examples, go to Create changelogs.

Files are named note-{slug}.yml. Each product lists products[].versions — the release versions the change applies to.

--name string
Explicit slug for the note filename. Defaults to a slug derived from the title.
--products string
Products and versions in the format "product versions [lifecycle], ..." where versions is a |-separated list of release versions (for example, "elasticsearch 9.3.0|9.4.0 ga"). Unlike changelog add, the middle slot is required and is a version list, not omitted. The valid product identifiers are listed in products.yml.
--action string
Optional action text.
--areas string[]

Optional area tags.

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

--concise

Omit schema reference comments from the generated YAML.

Default: false

--config string

Path to the changelog.yml configuration file.

Constraints: symbolic links not allowed, must exist, extensions: yml, yaml

--description string
Additional information (max 600 characters). Optional.
--no-extract-release-notes

Skip extracting release note text from PR/issue descriptions.

Default: false

--no-extract-issues

Skip extracting linked issues/PRs from PR/issue body.

Default: false

--feature-id string
Optional feature ID.
--highlight
Mark the entry as a highlight.
--impact string
Optional impact text.
--issues string[]

URLs of related issues. Optional citation field; listing issues does not attach the file to a release.

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

--owner string
GitHub owner. Falls back to bundle.owner or "elastic".
--output string
Output directory.
--prs string[]

Optional PR URLs (cited but not used as anchor).

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

--repo string
GitHub repository name.
--strip-title-prefix

Strip a repo-name prefix from the title.

Default: false

--strict-fetch

Treat GitHub fetch failures as errors.

Default: false

--subtype string
Entry subtype.
--title string
A short, user-facing headline (max 80 characters). Required.
--type string
The type of change. For valid values, see ChangelogEntryType.cs. Required.
-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

--skip-private-repositories
Skip cloning private repositories
-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

--skip-private-repositories
Skip cloning private repositories

The --products option uses the same positional slots as changelog add, but the middle slot is a |-separated version list and is required:

  • "elasticsearch 9.3.0 ga" — one version
  • "elasticsearch 9.3.0|9.4.0|9.5.0 ga" — multiple versions
  • "cloud-serverless 2025-08-05" — date-based release, one version

A changelog that spans products can declare each product separately:

docs-builder changelog note \
  --title "Known issue with aggregations" \
  --type known-issue \
  --products "elasticsearch 9.3.0|9.4.0 ga" \
  --products "kibana 9.3.0|9.4.0 ga"

The command writes a note-{slug}.yml file to the configured output directory:

title: Known issue with aggregations
type: known-issue
products:
  - product: elasticsearch
    versions: [9.3.0, 9.4.0]
    lifecycle: ga

Upload is the same as for other changelog YAML files. An index at changelog/{org}/{repo}/notes-{version}.json lists every changelog "note" file that applies to each version.

If the release bundle for that product and version or date has already shipped when you upload, the scrubber generates an amend file so the changelog reaches published docs without a manual rerun.

If there is no existing or planned bundle for that product and version or date, you can create a bundle from a path list that contains all the relevant changelogs. Refer to Bundle by file paths.

The same configuration-file checks that apply to changelog add apply here: valid products, lifecycles, and type values are validated against docs/changelog.yml when it exists.

A version in --products for changelog add is an error; use changelog note instead.