> For the complete documentation index, see [llms.txt](https://docs-lunar.earthly.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-lunar.earthly.dev/configuration/lunar-config/validation.md).

# Validating your config

Validate lunar-config.yml at commit/PR time — before merge — with a Hub-less dry run that runs the same checks the Hub does, plus a generated JSON Schema.

`lunar hub pull` validates configuration on the Hub, but by then the change has already merged. To catch mistakes **before** they merge, validate the config in CI on the pull request.

There are two complementary tools:

1. **`lunar hub pull --dry-run`** — the authoritative check, meant to run in CI on your pull requests. It runs the Hub's own load-and-validate steps against the same code (load the config, resolve every `uses:` plugin, validate the whole manifest, check that the image every collector, policy, and cataloger runs in exists, and resolve each component's default branch) and stops before applying anything — so it catches the mistakes a real `hub pull` would reject after merge, without a separate re-implementation that could drift.
2. **A JSON Schema** — generated from the manifest definition, for editor autocomplete and inline structural feedback while you type.

{% hint style="info" %}
**The dry run can run without a Hub.** It resolves public repositories anonymously, but private repositories and wildcard components need Git platform access. The CLI first tries an environment token, then `lunar login`. After that, a service-token caller uses a Hub-vended credential; other callers try `gh` or `glab`. See [Git platform tokens](https://docs-lunar.earthly.dev/docs/lunar-cli.md#lunar_github_token-lunar_gitlab_token).
{% endhint %}

## `lunar hub pull --dry-run`

```bash
lunar hub pull --dry-run <repo>
```

`<repo>` is the config repository ref, such as `github://acme-corp/lunar@my-branch` or `gitlab://gitlab.com/acme-corp/lunar@my-branch`.

The dry run clones the repository, loads `lunar-config.yml` and any [`lunar-config.d/`](https://docs-lunar.earthly.dev/configuration/lunar-config.md) fragments, and resolves every `uses:` plugin. It validates required fields, enum values, hook and cron shapes, [`on:`](https://docs-lunar.earthly.dev/configuration/lunar-config/on.md) expressions, [domain](https://docs-lunar.earthly.dev/configuration/lunar-config/domains.md) references, and [`uiPanels`](https://docs-lunar.earthly.dev/configuration/lunar-config/uipanels.md) definition files. It also verifies that each referenced plugin exists and resolves.

If validation fails, the command prints the error and exits non-zero. It never applies the manifest. With a Hub configured, it contacts the Hub only to check the configuration's images and, with the service token, to obtain a Git platform credential.

It runs the Hub's own `PullManifest` load-and-validate code — the `Fetch` pipeline plus the same component default-branch resolution the Hub performs before persisting — so a component pointing at a typo'd or inaccessible repo fails the dry run too, not just a real pull.

{% hint style="warning" %}
**One known gap:** the dry run does not install a script's dependencies (the `pip`/`npm` install the Hub runs for inline scripts that name no image), because that needs the runtime images and is too heavy for a CI gate. A dependency-install failure can therefore still surface only on a real `hub pull`. Everything else — structure, plugin resolution, script images, and component branch resolution — is validated.
{% endhint %}

### Script images

The dry run asks your Lunar Hub (`LUNAR_HUB_HOST` and `LUNAR_HUB_TOKEN`) to check that the image every collector, policy, and cataloger runs in exists, after [`image_replace`](https://docs-lunar.earthly.dev/configuration/lunar-config/images.md#rewriting-image-references) rewrites. The Hub looks each image up with the registry credentials it uses on a real pull. An image that is missing, has an invalid reference, or that the Hub can't verify fails the dry run, as does a token the Hub rejects.

With no Hub configured, the dry run fails and says to set the Hub or pass [`--no-hub`](https://docs-lunar.earthly.dev/docs/lunar-cli.md#--no-hub-lunar_no_hubtrue). Under `--no-hub`, or with the Hub's image check off (`HUB_IMAGE_CHECK=off`), it skips this check with a note, and the Hub still checks the images when it pulls the configuration.

## Pre-merge validation in CI

Run the dry run on every pull request against your config repo. The example below is for **GitHub Actions** — it's provided as a starting point; adapt the CLI install and the invocation to whatever CI system you use ([Sync Config](https://docs-lunar.earthly.dev/install/lunar-hub/self-hosted/sync-config.md#gitlab-ci) has the GitLab equivalent). It needs a token that can read the config repo and the plugin repos it references.

It intentionally runs on **all** pull requests rather than only when `lunar-config.yml` changes: the dry run resolves and validates every referenced plugin, including local `./`-path plugins in `collectors/`, `policies/`, or `catalogers/`, so a PR that edits one of those without touching `lunar-config.yml` is still checked. (A `paths:` filter would skip those.)

```yaml
name: Validate Lunar config

on:
  pull_request:

jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      id-token: write      # the job's OIDC token authenticates to the Hub
      contents: read
    steps:
      - name: Install Lunar CLI
        run: |
          curl -fsSL -o lunar "https://github.com/earthly/lunar-dist/releases/latest/download/lunar-linux-amd64"
          chmod +x lunar
          sudo mv lunar /usr/local/bin/lunar
      - name: Dry-run the config
        env:
          LUNAR_GITHUB_TOKEN: ${{ secrets.LUNAR_GITHUB_TOKEN }}
          LUNAR_HUB_HOST: hub.example.com
        run: |
          export LUNAR_HUB_TOKEN="$(curl -fsS \
            -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=hub.example.com" | jq -r .value)"
          lunar hub pull --dry-run "github://${{ github.repository }}@${{ github.event.pull_request.head.sha }}"
```

The job authenticates to the Hub with its [CI job identity](https://docs-lunar.earthly.dev/docs/authorization/ci-identity.md), which can check images but can't apply a configuration. Don't give a pull request job the Hub service token: a pull request can edit the workflow and read it.

{% hint style="info" %}
Pin the CLI to a specific release (e.g. `.../releases/download/v1.2.3/lunar-linux-amd64`) instead of `latest` for reproducible CI. The token needs read access to the config repo and any private plugin repos it `uses:`.
{% endhint %}

## JSON Schema (editor autocomplete)

For editor autocomplete and inline structural validation as you edit, the CLI emits a [JSON Schema](https://json-schema.org/) (draft-07 format) for `lunar-config.yml`, generated from the same manifest definition the Hub uses:

```bash
lunar config schema > lunar-config.schema.json
```

Commit that file and point your editor at it. In VS Code, for example:

```jsonc
// .vscode/settings.json
{
  "yaml.schemas": {
    "./lunar-config.schema.json": ["lunar-config.yml", "lunar-config.d/*.yml"]
  }
}
```

{% hint style="warning" %}
The JSON Schema is a **structural aid only** — it checks unknown/misspelled keys, types, and enum values. It does **not** resolve `uses:` plugins or component branches (the dry run does that), so it can't tell you a plugin or repo doesn't exist. (Neither the schema nor the dry run installs per-snippet dependencies — see the dry-run note above.) Use `lunar hub pull --dry-run` as the authoritative check; treat the schema as editor feedback.

If you also validate against the schema in CI, use a **YAML 1.2** validator such as [`check-jsonschema`](https://check-jsonschema.readthedocs.io/). YAML 1.1 parsers (e.g. Python's `yaml.safe_load`) coerce bare `on:`, `yes:`, `no:`, and `off:` mapping keys into booleans, which spuriously fails schema validation on the `on:` field.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs-lunar.earthly.dev/configuration/lunar-config/validation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
