Atmos Validation

Atmos Validation Framework

Use this skill for every Atmos validation command and validation policy configuration: aggregate project validation, configuration and stack schemas, JSON Schema, OPA/Rego, EditorConfig, GitHub Actions workflows, affected-file selection, and native CI reporting.

For detailed JSON Schema examples, read references/json-schema.md. For OPA/Rego policy patterns, read references/opa-policies.md. For project-wide, affected, and CI validation behavior, read references/project-validation.md.

Start with the Validation Target

Start with the narrowest command that matches the change. Use the aggregate command for a repository gate because it reports every applicable validator instead of stopping at the first one.

Validation Commands

atmos validate component vpc -s plat-ue2-prod
atmos validate stacks
atmos validate schema github-actions
atmos validate --affected --format rich

atmos validate component validates a component in a stack using settings.validation or explicit --schema-path / --schema-type flags.

atmos validate stacks validates stack YAML syntax, imports, duplicate component definitions, and manifest schema compliance.

atmos validate schema <key> validates arbitrary files matched by a schemas.<key>.matches glob against a JSON Schema.

atmos validate aggregates configuration, stack, EditorConfig, and GitHub Actions validation when those project inputs exist. It is the preferred CI entry point for repository-wide validation.

Affected Validation and Exclusions

Use --affected to select repository inputs changed from the merge base. In GitHub pull requests, Atmos reads the PR base; locally, pass --base <ref> when the default base is not appropriate.

atmos validate --affected --base origin/main --format rich
atmos config validate --affected
atmos stack validate --affected
atmos validate ci --affected

Use repeatable repository-relative glob exclusions to keep deliberately-invalid test fixtures out of production validation. --exclude works with the aggregate command and the config, stacks, schema, and GitHub Actions validators whether they run all inputs or only affected inputs.

atmos validate --affected --exclude 'tests/fixtures/**' --format rich
atmos validate schema github-actions --exclude 'tests/fixtures/**'
atmos validate ci --exclude 'tests/fixtures/**'

Use slash-separated repository globs. Do not use an exclusion to hide a deployable project path; run intentional negative fixtures in a dedicated test or annotation E2E check instead.

atmos validate editorconfig --exclude is its established EditorConfig regular-expression flag, not the generic repository-glob exclusion. The aggregate command still applies its repository-glob --exclude before invoking the EditorConfig validator.

Base Paths

Configure validation schema base paths in atmos.yaml:

schemas:
  jsonschema:
    base_path: stacks/schemas/jsonschema
  opa:
    base_path: stacks/schemas/opa
  atmos:
    manifest: stacks/schemas/atmos/atmos-manifest/1.0/atmos-manifest.json

The cue, opa, and jsonschema keys under schemas are reserved for Atmos schema-path configuration. Do not use those names as generic atmos validate schema <key> entries.

Component Validation

Define component validation under settings.validation:

components:
  terraform:
    vpc:
      settings:
        validation:
          validate-vpc-jsonschema:
            schema_type: jsonschema
            schema_path: vpc/validate-vpc-component.json
          check-vpc-opa:
            schema_type: opa
            schema_path: vpc/validate-vpc-component.rego
            module_paths:
              - catalog/constants
            timeout: 10

Each validation step can define:

Generic File Validation

Use atmos validate schema for non-Atmos files, such as GitHub Actions workflows or Kubernetes manifests:

schemas:
  github-actions:
    schema: https://json.schemastore.org/github-workflow.json
    matches:
      - .github/workflows/*.yml
      - .github/workflows/*.yaml

atmos validate schema github-actions

JSON Schema

JSON Schema validates structure, required fields, types, patterns, enums, and ranges. Atmos passes the full resolved component configuration to component schemas, so schemas usually validate under vars, settings, env, backend, or metadata.

Minimal component schema:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "vars": {
      "type": "object",
      "required": ["region"],
      "properties": {
        "region": { "type": "string" }
      }
    }
  }
}

OPA/Rego

Atmos OPA policies use package atmos and collect validation errors in errors.

package atmos

errors[message] {
  input.vars.stage == "prod"
  input.vars.map_public_ip_on_launch == true
  message = "Public IP mapping is not allowed in prod"
}

OPA input is the resolved component configuration. Common fields include input.vars, input.settings, input.env, input.backend, input.metadata, and Terraform CLI context fields available during plan/apply.

CI Guidance

Run validation early in CI with the Atmos container and direct Atmos commands:

jobs:
  validate:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/cloudposse/atmos:${{ vars.ATMOS_VERSION }}
    steps:
      - uses: actions/checkout@v6
      - run: atmos validate --affected --format rich --exclude 'tests/fixtures/**'

Enable native CI output in atmos.yaml when validation runs in CI:

ci:
  enabled: true
  annotations:
    enabled: true

With native CI enabled, aggregate validation writes an Atmos job summary, including passed, skipped, and failed validators. Findings from validators that support source annotations (including GitHub Actions/actionlint) emit GitHub Actions workflow commands; a successful validation stays visible through the green check and job summary rather than creating success annotations. Use --format rich for readable CI diagnostics. The actionlint SARIF format is intentionally side-effect free, so use it when a separate SARIF uploader owns annotations.

Do not reintroduce deprecated setup actions in new examples. Route broader Native CI workflow structure, event triggers, permissions, and actionlint annotation E2E tests to atmos-ci.

Routing

Guardrails

• Prefer stack vars validation over ad hoc shell checks.
• Keep reusable business rules in OPA modules or JSON Schema files, not inline in CI.
• Do not validate against guessed stack names or component names; use atmos list or atmos describe first.
• Keep policy messages actionable and name the field that should change.