---
title: changelog note cli command
description: 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,...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4120/cli/changelog/note
products:
  - Elastic Docs Builder
---

# changelog note cli command
```bash
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](https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4120/data/release-notes/create).
Files are named `note-{slug}.yml`. Each product lists `products[].versions` — the release versions the change applies to.

## Options

<definitions>
  <definition term="--name string">
    Explicit slug for the note filename. Defaults to a slug derived from the title.
  </definition>
  <definition term="--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](https://github.com/elastic/docs-builder/blob/main/config/products.yml).
  </definition>
  <definition term="--action string">
    Optional action text.
  </definition>
  <definition term="--areas string[]">
    Optional area tags.
    **Repeatable:** pass `--areas` multiple times to supply more than one value
  </definition>
  <definition term="--concise">
    Omit schema reference comments from the generated YAML.
    **Default:** `false`
  </definition>
  <definition term="--config string">
    Path to the changelog.yml configuration file.
    **Constraints:** symbolic links not allowed, must exist, extensions: yml, yaml
  </definition>
  <definition term="--description string">
    Additional information (max 600 characters). Optional.
  </definition>
  <definition term="--no-extract-release-notes">
    Skip extracting release note text from PR/issue descriptions.
    **Default:** `false`
  </definition>
  <definition term="--no-extract-issues">
    Skip extracting linked issues/PRs from PR/issue body.
    **Default:** `false`
  </definition>
  <definition term="--feature-id string">
    Optional feature ID.
  </definition>
  <definition term="--highlight">
    Mark the entry as a highlight.
  </definition>
  <definition term="--impact string">
    Optional impact text.
  </definition>
  <definition term="--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
  </definition>
  <definition term="--owner string">
    GitHub owner. Falls back to bundle.owner or "elastic".
  </definition>
  <definition term="--output string">
    Output directory.
  </definition>
  <definition term="--prs string[]">
    Optional PR URLs (cited but not used as anchor).
    **Repeatable:** pass `--prs` multiple times to supply more than one value
  </definition>
  <definition term="--repo string">
    GitHub repository name.
  </definition>
  <definition term="--strip-title-prefix">
    Strip a repo-name prefix from the title.
    **Default:** `false`
  </definition>
  <definition term="--strict-fetch">
    Treat GitHub fetch failures as errors.
    **Default:** `false`
  </definition>
  <definition term="--subtype string">
    Entry subtype.
  </definition>
  <definition term="--title string">
    A short, user-facing headline (max 80 characters). Required.
  </definition>
  <definition term="--type string">
    The type of change. For valid values, see [ChangelogEntryType.cs](https://github.com/elastic/docs-builder/blob/main/src/Elastic.Documentation/ReleaseNotes/ChangelogEntryType.cs). Required.
  </definition>
  <definition term="-l --log-level enum">
    Minimum log level.
    **Values:** trace, debug, information, warning, error, critical, none
    **Default:** `information`
  </definition>
  <definition term="-c --config-source enum">
    Override the configuration source: local, remote
    **Values:** local, remote, embedded
  </definition>
  <definition term="--skip-private-repositories">
    Skip cloning private repositories
  </definition>
</definitions>


## Global Options

<definitions>
  <definition term="-l --log-level enum">
    Minimum log level.
    **Values:** trace, debug, information, warning, error, critical, none
    **Default:** `information`
  </definition>
  <definition term="-c --config-source enum">
    Override the configuration source: local, remote
    **Values:** local, remote, embedded
  </definition>
  <definition term="--skip-private-repositories">
    Skip cloning private repositories
  </definition>
</definitions>


## Product and version format

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:
```sh
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"
```


## Output

The command writes a `note-{slug}.yml` file to the configured output directory:
```yaml
title: Known issue with aggregations
type: known-issue
products:
  - product: elasticsearch
    versions: [9.3.0, 9.4.0]
    lifecycle: ga
```


## After creation

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](/elastic/docs-builder/pull/4120/cli/changelog/bundle#changelog-bundle-files).

## Configuration checks

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.