Skip to content
Cigen

validate

The validate command checks your cigen configuration for errors without generating any output files.

Usage

Section titled “Usage”
Terminal window
cigen validate [OPTIONS]

Options

Section titled “Options”

--config <PATH>

Section titled “--config <PATH>”

Path to the cigen configuration directory or file.

  • Default: Current directory (.)
  • Example: --config .cigen/ or --config .cigen/config.yml

--verbose / -v

Section titled “--verbose / -v”

Enable verbose output showing detailed validation steps.

--strict

Section titled “--strict”

Enable strict validation mode with additional checks.

Examples

Section titled “Examples”

Basic Validation

Section titled “Basic Validation”
Terminal window
cigen validate

Validate Specific Configuration

Section titled “Validate Specific Configuration”
Terminal window
cigen validate --config .cigen/

Verbose Output

Section titled “Verbose Output”
Terminal window
cigen validate --config .cigen/ --verbose

What Gets Validated

Section titled “What Gets Validated”

The validate command performs comprehensive checks:

1. Configuration File Syntax

Section titled “1. Configuration File Syntax”
  • YAML syntax validation
  • JSON schema compliance
  • Required field presence

2. Job Definitions

Section titled “2. Job Definitions”
  • Image specifications
  • Step references and syntax
  • Dependency graphs (circular dependency detection)
  • Required vs optional fields

3. Workflow Structure

Section titled “3. Workflow Structure”
  • Job references exist
  • Dependency chains are valid
  • No orphaned jobs

4. Template Variables

Section titled “4. Template Variables”
  • All referenced variables are defined
  • Template syntax is correct
  • No undefined template expressions

5. Provider-Specific Validation

Section titled “5. Provider-Specific Validation”
  • CircleCI: Resource class compatibility, orb usage
  • Platform-specific constraints and limits

6. File References

Section titled “6. File References”
  • Referenced files exist (e.g., Dockerfiles, scripts)
  • Source file groups are valid
  • Cache key dependencies are resolvable

Validation Levels

Section titled “Validation Levels”

Basic Validation (Default)

Section titled “Basic Validation (Default)”
  • Schema compliance
  • Basic syntax checks
  • Job/workflow reference validation

Strict Validation (--strict)

Section titled “Strict Validation (--strict)”
  • All basic validations
  • Warning-level issues become errors
  • Additional best practice checks
  • Performance impact analysis

Error Types and Solutions

Section titled “Error Types and Solutions”

Schema Validation Errors

Section titled “Schema Validation Errors”
Error: Invalid job configuration at 'jobs.test'
  - Missing required property 'image'
  - Property 'invalid_field' is not allowed

Solution: Fix the job definition to match the schema requirements.

Dependency Errors

Section titled “Dependency Errors”
Error: Circular dependency detected
  - job_a -> job_b -> job_c -> job_a

Solution: Remove circular references in job requires fields.

Template Errors

Section titled “Template Errors”
Error: Undefined variable 'app_name' in template
  - File: workflows/main/jobs/deploy.yml
  - Line: 12

Solution: Define the variable in your vars section:

vars:
  app_name: my-application

File Reference Errors

Section titled “File Reference Errors”
Error: Referenced file not found
  - File: Dockerfile.production
  - Referenced in: jobs.build_production.dockerfile

Solution: Create the missing file or correct the reference.

Exit Codes

Section titled “Exit Codes”
  • 0: Validation passed
  • 1: Validation errors found
  • 2: Configuration file not found
  • 3: Internal validation error

Integration

Section titled “Integration”

Pre-commit Hooks

Section titled “Pre-commit Hooks”
repos:
  - repo: local
    hooks:
      - id: cigen-validate
        name: Validate cigen config
        entry: cigen validate
        language: system
        files: '^\.cigen/'
        pass_filenames: false

CI/CD Pipeline

Section titled “CI/CD Pipeline”
# GitHub Actions
- name: Validate CI config
  run: cigen validate --config .cigen/ --strict


# CircleCI
- run:
    name: Validate CI config
    command: cigen validate --config .cigen/ --strict

Editor Integration

Section titled “Editor Integration”

For VS Code, add to .vscode/settings.json:

{
  "yaml.schemas": {
    "https://cigen.dev/schemas/v1/config-schema.json": ".cigen/config.yml"
  }
}

Performance

Section titled “Performance”

Validation is typically fast:

  • Small configs (< 10 jobs): < 100ms
  • Medium configs (10-50 jobs): < 500ms
  • Large configs (50+ jobs): < 2 seconds

Strict mode adds ~50% overhead for additional checks.

Best Practices

Section titled “Best Practices”

Regular Validation

Section titled “Regular Validation”

Run validation frequently during development:

Terminal window
# Watch for changes and validate
watch -n 1 cigen validate

Team Workflows

Section titled “Team Workflows”
  • Add validation to pull request checks
  • Include validation in development workflows
  • Use --strict mode in CI pipelines

Configuration Organization

Section titled “Configuration Organization”

Structure your config for easier validation:

.cigen/
├── config.yml              # Main config
├── jobs/                  # Job definitions
├── workflows/            # Workflow definitions
└── templates/           # Custom templates

Troubleshooting

Section titled “Troubleshooting”

Common Issues

Section titled “Common Issues”
  1. YAML Indentation: Use consistent 2-space indentation
  2. Missing References: Ensure all referenced jobs/commands exist
  3. Schema Mismatches: Check field names against documentation
  4. Template Syntax: Verify Jinja2 template expressions

Debug Mode

Section titled “Debug Mode”

Enable debug output for complex validation issues:

Terminal window
RUST_LOG=debug cigen validate --verbose
Section titled “Related Commands”
Cigen was created by DocSpring
Fill, sign, and generate PDFs at scale