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 optionally a product label. 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, 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.

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