changelog evaluate-pr cli command

docs-builder changelog evaluate-pr \
  --config <file> \
  --owner <string> \
  --repo <string> \
  --pr-number <int> \
  --pr-title <string> \
  --pr-labels <string> \
  --head-ref <string> \
  --head-sha <string> \
  [options]
		

Evaluate a pull request for changelog generation eligibility. Performs pre-flight checks (body-only edit, bot loop detection, manual edit detection), loads the changelog configuration, checks label-based creation rules, resolves the PR title and type, and sets GitHub Actions outputs for downstream steps.

When running under GitHub Actions (the GITHUB_ACTIONS environment variable is set), the command writes a decision metadata file to .artifacts/changelog-decision/metadata.json. This file is picked up by the downstream changelog github-comment command to post or update the sticky PR comment. Pass --is-fork, --can-commit, and --maintainer-can-modify so the comment command can select the correct comment body for fork and comment-only PR strategies.

--config string required

Path to the changelog.yml configuration file

Constraints: extensions: yml, yaml

--owner string required

GitHub repository owner

--repo string required

GitHub repository name

--pr-number int required

Pull request number

--pr-title string required

Pull request title

--pr-labels string required

Comma-separated PR labels

--head-ref string required

PR head branch ref

--head-sha string required

PR head commit SHA

--event-action string

Optional: GitHub event action (e.g., opened, synchronize, edited). When omitted, body-only-edit and bot-loop checks are skipped.

--title-changed

Whether the PR title changed (for edited events)

Default: false

--body-changed

Whether the PR body changed (for edited events)

Default: false

--strip-title-prefix

Remove square-bracket prefixes from the PR title

Default: false

--require-changelog-file

Fail when no changelog entry file exists for the PR

Default: false

--require-impact-action

Fail when a breaking-change PR description lacks an Impact and/or Action section

Default: false

--bot-name string

Bot login name for loop detection

Default: github-actions[bot]

--is-fork

Default: false

--can-commit

Default: false

--maintainer-can-modify

Default: false

--head-repo string

-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

docs-builder changelog evaluate-pr \
  --config docs/changelog.yml \
  --owner elastic \
  --repo elasticsearch \
  --pr-number 42 \
  --pr-title "Add new feature" \
  --pr-labels "enhancement,Team:Core" \
  --head-ref feature-branch \
  --head-sha abc123 \
  --event-action opened \
  --strip-title-prefix \
  --require-changelog-file
		

Pass --require-changelog-file to fail the PR (missing-entry) when no changelog entry file exists for the PR number. The entry file is looked up in bundle.directory (default docs/changelog). This flag is designed to be passed as a workflow input rather than hardcoded in changelog.yml.

Impact and Action come from one source, in this order of precedence:

1. The changelog entry file for the PR, when there is one. Its impact: and action: fields win.
2. The PR description, when there is no entry file.

A breaking-change PR that has an entry file and also has ## Impact or ## Action in its description fails with conflicting-impact-action when a section does not match the file's field exactly, whether or not --require-impact-action is set. Leading and trailing whitespace and line-ending style are ignored. The comment asks the author to keep them in one place or make them match.

Pass --require-impact-action to fail the PR (missing-impact-action) when its resolved type is breaking-change and its source lacks an Impact and/or Action. With an entry file that means a missing impact: or action: field. Without one it means a missing Impact or Action section in the PR description. Recognized forms are a markdown heading of any level (## Impact, ### Action) or a label (Impact: ...). Sections that contain only HTML comments, such as an unfilled PR template, count as missing. A section under a heading runs until the next heading of the same or a higher level, so put notes that are not part of Impact or Action under their own heading. A label section ends at the first blank line. Like --require-changelog-file, this flag is designed to be passed as a workflow input.

The sticky PR comment lists the missing sections with a template to paste into the description. Once the sections are present, evaluate-pr sets the impact and action outputs. When Impact or Action is scraped from the PR description, the comment stays on the PR and echoes the scraped text in a collapsible block, so you can check it before bundling. Nothing is echoed when the values come from an entry file, since the file is already part of the PR. evaluate-pr records the captured sections in the decision metadata, so the echo works even when no entry file is generated in the same run.