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

--comment-on-success

Also comment when the check passes, saying whether the PR will be part of the release notes

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

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.

By default the sticky PR comment only appears when a check fails, or to echo a breaking change's Impact and Action. Pass --comment-on-success (the comment-on-success workflow input) to also comment when the check passes. The comment says whether the PR will be part of the release notes:

• Included: the resolved type, products and areas, taken from the PR labels through pivot.types, pivot.products and pivot.areas.
• Not included: the reason, such as the label that matches a rules.create exclusion.

This is the same sticky comment, not a second one. For a breaking change the captured Impact and Action are shown in the same comment. A failing check still shows its failure body instead. Without the flag nothing changes: the comment is removed on success.

--comment-on-success has to be passed to validate-labels, validate and evaluate-pr alike, because each of them rewrites the decision metadata. The first one to know the outcome records it and the later ones keep it.