changelog gh-release cli command

docs-builder changelog gh-release <repo> [<version>] [options]
		

Create changelog files and a bundle from a GitHub release by parsing pull request references from the release notes.

For general information about changelogs, go to Create release notes from changelogs.

<repo> string required

Required: GitHub repository in owner/repo format (e.g., "elastic/elasticsearch" or just "elasticsearch" which defaults to elastic/elasticsearch)

<version> string

Optional: Version tag to fetch (e.g., "v9.0.0", "9.0.0"). Defaults to "latest"

Default: latest

--config string

Optional: Path to the changelog.yml configuration file. Defaults to 'docs/changelog.yml'

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

--description string

Optional: Bundle description text with placeholder support. Supports VERSION, LIFECYCLE, OWNER, and REPO placeholders. Overrides bundle.description from config.

--output string

Optional: Output directory for changelog files. Falls back to bundle.directory in changelog.yml when not specified. Defaults to './changelogs'

--release-date string

Optional: Explicit release date for the bundle in YYYY-MM-DD format. Overrides GitHub release published date.

--strip-title-prefix

Optional: Remove square brackets and text within them from the beginning of PR titles (e.g., "[Inference API] Title" becomes "Title")

Default: false

--warn-on-type-mismatch

Optional: Warn when the type inferred from release notes section headers doesn't match the type derived from PR labels. Defaults to true

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

The command creates two types of output in the directory specified by --output:

• One YAML changelog file per pull request found in the release notes.
• A bundle file at {output}/bundles/{version}-{product}-bundle.yml that references all created changelog files.

The product, target version, and lifecycle are inferred automatically from the release tag and the repository name (via products.yml). For example, a tag of v9.2.0 on elastic/elasticsearch creates changelogs with product: elasticsearch, target: 9.2.0, and lifecycle: ga.

For each pull request found in the release notes, the command follows the same fidelity ladder as commit-range bundling:

1. A checked-in changelog entry wins. If an entry for the PR already exists in the repository's entry pool (uploaded via changelog-upload), it is used verbatim — matched by file-name-derived PR numbers (file names survive scrubbing) or by its prs references.
2. Otherwise an entry is synthesized from PR metadata: release-note text from the PR body becomes the description (the same extraction path changelog add uses, controlled by extract.release_notes), and linked issues are carried over (extract.issues).
3. Title/link-only is the last resort when the PR body carries no release-note text.

When the entry pool cannot be reached, the command warns and falls back to synthesis, so repositories that never upload individual entries keep working.

The rules.bundle section of your changelog.yml applies to bundles created by this command. For details, refer to Changelog configuration reference > rules.bundle.

# Latest release
docs-builder changelog gh-release elastic/elasticsearch

# Specific version tag
docs-builder changelog gh-release elastic/elasticsearch v9.2.0

# Short repository name (defaults to elastic/ owner)
docs-builder changelog gh-release elasticsearch v9.2.0

# Custom output directory
docs-builder changelog gh-release elasticsearch v9.2.0 \
  --output ./docs/changelog \
  --config ./docs/changelog.yml

# Description with placeholders
docs-builder changelog gh-release elasticsearch v9.2.0 \
  --description "Elasticsearch {version} release. Download: https://github.com/{owner}/{repo}/releases/tag/v{version}"