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. The scrubber writes two indexes per note:

  • changelog/{org}/{repo}/notes-{product}-{version}.json — notes for that product and version. changelog bundle reads this key first.
  • changelog/{org}/{repo}/notes-{version}.json — the union of notes for that version across products, kept for older CLI pins.

{changelog} does not read these indexes. It loads published bundle YAML (and amend sidecars listed in bundle/{product}/registry.json).

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.