changelog bundle-amend cli command

docs-builder changelog bundle-amend <bundle-path> [options]
		

Amend a bundle with additional or excluded changelog entries without modifying the parent bundle file. Amend bundles follow a specific naming convention: {parent-bundle-name}.amend-{N}.yaml where {N} is a sequence number.

Specify at least one of --add or --remove.

To create a bundle, use changelog bundle cli command. For details and examples, go to Bundle changelogs.

<bundle-path> string required

Required: Path to the original bundle file to amend

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

--add string[]

Optional: Changelog YAML paths to add. Repeat --add or pass a comma-separated list in one value (for example, --add "file1.yaml,file2.yaml"). Supports tilde (~) expansion and relative paths. When entries are sourced from the CDN (the default when bundle.repo or the parent bundle's repo resolves), paths are matched by file name and do not need to exist locally; with local sourcing (--force-local or bundle.use_local_changelogs) the paths must exist on disk.

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

--remove string[]

Optional: Changelog YAML paths to exclude from the effective bundle. Repeat --remove or pass a comma-separated list in one value. Supports tilde (~) expansion and relative paths. When entries are sourced from the CDN, paths are matched by file name and do not need to exist locally; with local sourcing the paths must exist on disk unless --force is used to exclude by file name.

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

--force

Optional: When removing, match by file name even if the bundle checksum differs from the sourced changelog, or when no YAML can be sourced (inferred git-ref entries).

Default: false

--force-local

Optional: Force local entry sourcing for this run (equivalent to bundle.use_local_changelogs: true without editing config).

Default: false

--dry-run

Optional: Preview changes without writing an amend file.

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

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

Amend bundles contain the parent bundle's products plus only the changes for that amend file, not a full repetition of the original bundle's entries.

The parent's complete products (including target, repo, and owner) are copied into every amend file so the amend is self-contained: upload destination discovery, the registry's per-product target, and :version:-filtered CDN consumption all derive from a bundle file's own products.

Like bundles, amend files embed the full changelog content of each entry: entries added with --add carry inline title, type, products, and so on, alongside a file block recording the source file name and checksum for provenance.

Additions:

# 9.3.0.amend-1.yaml
products:
- product: elasticsearch
  target: 9.3.0
  repo: elasticsearch
  owner: elastic
entries:
- file:
    name: late-addition.yaml
    checksum: abc123def456
  type: bug-fix
  title: A late addition
  products:
  - product: elasticsearch
    target: 9.3.0
		

Removals:

# 9.3.0.amend-2.yaml
products:
- product: elasticsearch
  target: 9.3.0
  repo: elasticsearch
  owner: elastic
exclude-entries:
- file:
    name: 138723.yaml
    checksum: def456abc123
		

An amend file can contain both exclude-entries and entries. Within each amend file, exclusions are applied before additions.

When bundles are loaded (either via the changelog render command or the {changelog} directive), amend files are automatically merged with their parent bundles in sequence (amend-1, amend-2, …). The result is rendered as a single release.

The first argument is the local parent bundle. --add can be a CDN path (matched by file name) when entry sourcing uses the CDN:

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --add /changelog/elastic/kibana/main/138723.yaml
		

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --add ./docs/changelog/138723.yaml \
  --force-local
		

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --remove /changelog/elastic/kibana/main/138723.yaml
		

The CLI computes the checksum of the sourced YAML and matches it against the effective bundle (parent plus any existing amend files). If the bundle contains the file with a different checksum, the command fails unless you pass --force to remove by file name only.

Git-ref bundles created with --infer (or infer_missing_changelogs: true) can include entries that were synthesized from GitHub PR metadata. Those entries live only in the bundle. Their file.name is {pull-request-number}.yaml, and there is no changelog YAML on disk or on the CDN whose checksum you can match.

Pass --force so matching is by filename only. The path does not need to exist:

docs-builder changelog bundle-amend ./docs/releases/cloud-hosted-2026-08-13.yaml \
  --remove 300.yaml --force
		

Refer to changelog bundle cli command > Inferred entries and bundle-amend for the full workflow, including how to replace inferred copy with a real changelog.

Comma-separated list:

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --add "./docs/changelog/138723.yaml,./docs/changelog/1770424335.yaml" \
  --force-local
		

Or repeat --add:

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --add ./docs/changelog/138723.yaml \
  --add ./docs/changelog/1770424335.yaml \
  --force-local
		

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --remove "./docs/changelog/old-a.yaml,./docs/changelog/old-b.yaml" \
  --force-local
		

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --remove ./docs/changelog/old-entry.yaml \
  --add ./docs/changelog/new-entry.yaml \
  --force-local
		

docs-builder changelog bundle-amend \
  ./docs/changelog/bundles/9.3.0.yaml \
  --remove /changelog/elastic/kibana/main/138723.yaml \
  --dry-run