changelog validate cli command

docs-builder changelog validate <pr-number> [options]
		

Validate changelog entry files that a PR added or modified. Checks YAML validity, required fields, config-value membership, PR-number existence, and entry hygiene. Exits non-zero on any error-level finding; warnings do not block.

# Simplest local usage — owner/repo inferred from git remote, config from docs/changelog.yml
docs-builder changelog validate 4009
		

Pass --require to also fail when no entry file references this PR number, combining file-presence and content validation in a single command.

When running under GitHub Actions and --head-sha is provided, writes decision metadata to .artifacts/changelog-decision/metadata.json for the downstream changelog github-comment step.

<pr-number> int required

Pull request number to validate.

--config string

Path to the changelog configuration file. Defaults to docs/changelog.yml.

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

--owner string

GitHub repository owner. Defaults to the owner inferred from the git remote origin.

--repo string

GitHub repository name. Defaults to the repo inferred from the git remote origin.

--pr-labels string

Comma-separated list of PR labels. When supplied, validates that type: matches the label-derived type (use ${{ join(github.event.pull_request.labels.*.name, ',') }} in Actions).

--files string[]

Explicit file list; bypasses GitHub API discovery. Useful for local runs without a token.

Repeatable: pass --files multiple times to supply more than one value

--require

Also fail when no changelog entry file references this PR number.

Default: false

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

For local use you rarely need to supply any of these. For CI the runner's checkout has no git remote, so pass them explicitly.

Without --files, the command calls the GitHub API (GET /repos/{owner}/{repo}/pulls/{pr}/files) to list changed files and filters to changelog entry files (top-level .yaml/.yml under the changelog directory, not note-*). A GITHUB_TOKEN is needed for this. Supply --files to bypass API discovery entirely.

# Local: everything inferred
docs-builder changelog validate 4009

# Local: also assert an entry file references this PR
docs-builder changelog validate 4009 --require

# Local: validate a specific file without a GitHub token
docs-builder changelog validate 4009 --files docs/changelog/4009.yaml

# CI: explicit owner/repo/labels (git remote not available in the runner)
docs-builder changelog validate "$PR_NUMBER" \
  --config "$CONFIG" \
  --owner "$REPO_OWNER" \
  --repo "$REPO_NAME" \
  --pr-labels "$PR_LABELS"