changelog validate-labels cli command

docs-builder changelog validate-labels \
  --config <file> \
  --pr-labels <string> \
  [options]
Note

This command is intended for CI automation. It is used internally by the changelog GitHub Actions and is not typically invoked directly by users.

Validate that a pull request's labels contain a recognised changelog type label, and a product or area label when the configuration requires one (refer to Required pivots). Unlike changelog evaluate-pr, this command performs no GitHub API access, no title resolution, no bot-loop detection, and no manual-edit detection — it only resolves labels against the configured pivot.types, pivot.products, pivot.areas, pivot.required, and rules.create settings. This makes it safe to run on pull_request events from forks without write permissions.

Exits non-zero when status is no-label. All other statuses (ok, skipped) exit zero.

When running under GitHub Actions (the GITHUB_ACTIONS environment variable is set) and --pr-number is provided, 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 --comment-on-success to also record whether the PR will be part of the release notes (type, products and areas, or the reason it is excluded). The comment command then posts that instead of removing the sticky comment. See Comment on success.

--config string required

Path to the changelog.yml configuration file.

Constraints: extensions: yml, yaml

--pr-labels string required
Comma-separated list of PR labels (use ${{ join(github.event.pull_request.labels.*.name, ',') }} in actions).
--pr-number int

PR number — required for decision metadata written when running on CI.

Default: 0

--head-ref string
PR head branch ref — written to decision metadata when on CI.
--head-sha string
PR head commit SHA — written to decision metadata when on CI.
--is-fork

Whether the PR is from a fork.

Default: false

--can-commit

Whether the commit strategy allows committing.

Default: false

--maintainer-can-modify

Whether the fork PR allows maintainer edits.

Default: false

--head-repo string
Fork repository full name (owner/repo).
--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
Output Description
status Validation result: ok, no-label, or skipped
type Resolved changelog type (when ok)
products Comma-separated product specs resolved from PR labels (when resolved)
label-table Markdown table of configured label-to-type mappings (when no-label)
product-label-table Markdown table of configured label-to-product mappings (when no-label due to missing product)
area-label-table Markdown table of configured label-to-area mappings (when no-label because pivot.required lists areas and the PR has no area label)
skip-labels Comma-separated list of configured skip labels (from rules.create exclude rules)

When --pr-number is supplied and the command runs under GitHub Actions, it writes .artifacts/changelog-decision/metadata.json relative to the checkout root. The file contains the PR number, head ref/SHA, validation status, and label tables. A consumer workflow uploads this file as the changelog-decision artifact and a workflow_run job picks it up to call changelog github-comment.

docs-builder changelog validate-labels \
  --config docs/changelog.yml \
  --pr-labels "enhancement,Team:Core" \
  --pr-number 42 \
  --head-ref feature-branch \
  --head-sha abc123