---
title: changelog validate cli command
description: Validate changelog entry files that a PR added or modified. Checks YAML validity, required fields, config-value membership, PR-number existence, and entry...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4044/cli/changelog/validate
products:
  - Elastic Docs Builder
---

# changelog validate cli command
```bash
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.
```sh
# 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.

## Arguments

<definitions>
  <definition term="<pr-number> int required">
    Pull request number to validate.
  </definition>
</definitions>


## Options

<definitions>
  <definition term="--config string">
    Path to the changelog configuration file. Defaults to docs/changelog.yml.
    **Constraints:** symbolic links not allowed, must exist, extensions: yml, yaml
  </definition>
  <definition term="--owner string">
    GitHub repository owner. Defaults to the owner inferred from the git remote origin.
  </definition>
  <definition term="--repo string">
    GitHub repository name. Defaults to the repo inferred from the git remote origin.
  </definition>
  <definition term="--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).
  </definition>
  <definition term="--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
  </definition>
  <definition term="--require">
    Also fail when no changelog entry file references this PR number.
    **Default:** `false`
  </definition>
  <definition term="--head-ref string">
    PR head branch ref — written to decision metadata when on CI.
  </definition>
  <definition term="--head-sha string">
    PR head commit SHA — written to decision metadata when on CI.
  </definition>
  <definition term="--is-fork">
    Whether the PR is from a fork.
    **Default:** `false`
  </definition>
  <definition term="--can-commit">
    Whether the commit strategy allows committing.
    **Default:** `false`
  </definition>
  <definition term="--maintainer-can-modify">
    Whether the fork PR allows maintainer edits.
    **Default:** `false`
  </definition>
  <definition term="--head-repo string">
    Fork repository full name (owner/repo).
  </definition>
  <definition term="-l --log-level enum">
    Minimum log level.
    **Values:** trace, debug, information, warning, error, critical, none
    **Default:** `information`
  </definition>
  <definition term="-c --config-source enum">
    Override the configuration source: local, remote
    **Values:** local, remote, embedded
  </definition>
  <definition term="--skip-private-repositories">
    Skip cloning private repositories
  </definition>
</definitions>


## Global Options

<definitions>
  <definition term="-l --log-level enum">
    Minimum log level.
    **Values:** trace, debug, information, warning, error, critical, none
    **Default:** `information`
  </definition>
  <definition term="-c --config-source enum">
    Override the configuration source: local, remote
    **Values:** local, remote, embedded
  </definition>
  <definition term="--skip-private-repositories">
    Skip cloning private repositories
  </definition>
</definitions>


## Owner, repo, and config resolution


| Value      | Precedence                                      |
|------------|-------------------------------------------------|
| `--owner`  | CLI flag → git remote origin                    |
| `--repo`   | CLI flag → git remote origin                    |
| `--config` | CLI flag → `docs/changelog.yml` in the git root |

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.

## File discovery

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.

## Examples

```sh
# 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"
```