circleci-config-validator#

A pure Python 3 (stdlib + PyYAML) validator for .circleci/config.yml files covering 22 rules across 5 categories.

Commands#

text

python3 scripts/circleci_config_validator.py <command> [options] FILE

CommandDescriptionvalidateFull validation — all 22 rulescheckQuick syntax + structure check onlyjobsList all jobs with executor type and step countgraphShow workflow dependency graph as text

Options#

OptionDescription--format text|json|summaryOutput format (default: text)--strictTreat warnings as errors (exit 1)

Rules#

IDCategorySevDescriptionS001StructureEYAML syntax errorS002StructureEMissing version keyS003StructureEInvalid version (must be 2 or 2.1)S004StructureWMissing jobs or workflows sectionS005StructureWUnknown top-level keysJ001JobsEJob missing execution environmentJ002JobsEJob missing stepsJ003JobsWEmpty steps listJ004JobsWUnknown step nameJ005JobsErun step missing commandW001WorkflowsEWorkflow references undefined jobW002WorkflowsECircular job dependency via requiresW003WorkflowsErequires references undefined jobW004WorkflowsWEmpty workflow (no jobs)SEC1SecurityEHardcoded secret in environment variableSEC2SecurityWsetup_remote_docker without version pinSEC3SecurityWDeprecated deploy step usedSEC4SecurityIcontext used without branch filtersB001Best PracticesIMissing resource_classB002Best PracticesINo working_directory setB003Best PracticesWsave_cache without matching restore_cacheB004Best PracticesWDocker image using latest tag

Examples#

bash

# Full validation
python3 scripts/circleci_config_validator.py validate .circleci/config.yml

# Quick syntax check
python3 scripts/circleci_config_validator.py check .circleci/config.yml

# JSON output for CI
python3 scripts/circleci_config_validator.py --format json validate .circleci/config.yml

# One-line pass/fail
python3 scripts/circleci_config_validator.py --format summary validate .circleci/config.yml

# Strict mode (warnings = errors)
python3 scripts/circleci_config_validator.py --strict validate .circleci/config.yml

# List jobs
python3 scripts/circleci_config_validator.py jobs .circleci/config.yml

# Dependency graph
python3 scripts/circleci_config_validator.py graph .circleci/config.yml

Exit Codes#

• 0 — No errors (warnings may exist)
• 1 — Errors found (or warnings in --strict mode)
• 2 — File not found or YAML parse error

Requirements#

• Python 3.7+
• PyYAML (falls back to graceful error if unavailable)