---
title: changelog validate-labels cli command
description: 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...
url: https://docs-v3-preview.elastic.dev/elastic/docs-builder/pull/4572/cli/changelog/validate-labels
products:
  - Elastic Docs Builder
---

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

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](/elastic/docs-builder/pull/4572/data/release-notes/configure-ref#pivot-required)). 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](/elastic/docs-builder/pull/4572/cli/changelog/evaluate-pr#comment-on-success).

## Options

<definitions>
  <definition term="--config string required">
    Path to the changelog.yml configuration file.
    **Constraints:** extensions: yml, yaml
  </definition>
  <definition term="--pr-labels string required">
    Comma-separated list of PR labels (use ${{ join(github.event.pull_request.labels.*.name, ',') }} in actions).
  </definition>
  <definition term="--pr-number int">
    PR number — required for decision metadata written when running on CI.
    **Default:** `0`
  </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="--comment-on-success">
    Also comment when the check passes, saying whether the PR will be part of the release notes.
    **Default:** `false`
  </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>


## GitHub Actions outputs


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


## Decision metadata

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

## Examples

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