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} plus the same .yaml or .yml extension as the parent, 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: Local path to the parent bundle, or a CDN locator /bundle/{product}/{file}.yaml (leading slash optional; an absolute http(s) URL with that path is also accepted). Locator syntax takes precedence: prefix with ./ to force local resolution of a relative path that would otherwise match the locator shape. Local paths support tilde (~) expansion and must be a .yml/.yaml file that exists on disk.

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

--output string

Optional: Where to write the new sidecar when the parent is a CDN locator. A directory, or a .yaml/.yml path whose file name must be {parent}.amend-N plus the same extension as the parent for the next unused N. Falls back to bundle.output_directory in changelog.yml, then the current directory. Ignored for a local parent.

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

Pass a CDN locator as the parent. --add can be a CDN entry path (matched by file name) when entry sourcing uses the CDN:

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

This writes 9.3.0.amend-1.yaml (or the next unused N) under ./docs/releases. Upload is a separate step; the sidecar is uploaded like any other bundle YAML:

docs-builder changelog upload \
  --artifact-type bundle \
  --directory ./docs/releases \
  --target s3 \
  --s3-bucket-name my-changelog-bundles
		

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, or no YAML can be sourced (for example a git-ref entry that exists only in the bundle), the command fails unless you pass --force to remove by file name only.

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