You can test your CircleCI configuration files right on your machine before you even commit them, saving you from those embarrassing "oops, my config broke the build" pushes.
Let’s see this in action. Imagine you’ve got a simple .circleci/config.yml file:
version: 2.1
jobs:
build:
docker:
- image: cimg/base:2023.04
steps:
- checkout
- run: echo "Building project..."
- run: echo "Tests passing!"
workflows:
version: 2
build-and-test:
jobs:
- build
You want to ensure this is syntactically correct and that the commands within it will run as expected.
The core problem CircleCI config validation solves is preventing malformed or logically flawed configurations from being deployed to your CI/CD pipeline. This traditionally meant pushing code, waiting for a build, and then debugging a failed build due to a config error. By validating locally, you catch these issues before they impact your team or your pipeline’s history.
Here’s how it works internally: CircleCI’s local validation tool, circleci diagnostics, mimics the parsing and validation steps that the CircleCI server performs. It checks for:
- YAML Syntax: Is the file valid YAML?
- Schema Compliance: Does the structure adhere to the CircleCI configuration schema (e.g., correct keys, expected data types)?
- Job and Workflow Logic: Are jobs referenced correctly in workflows? Are required keys present for executors, steps, etc.?
The primary lever you control is the configuration file itself, .circleci/config.yml. You edit this file to define your build steps, environments, and workflow logic. The circleci diagnostics command then acts as your local linter and validator for this file.
To run the validation, you first need the CircleCI CLI installed. If you don’t have it, you can typically install it via Homebrew on macOS:
brew install circleci
Once installed, navigate to the root of your project in your terminal (the directory containing the .circleci folder) and run:
circleci diagnostics validate
This command will read your .circleci/config.yml file and report any syntax errors or schema violations.
For example, if you accidentally introduced a typo, like jobss instead of jobs:
version: 2.1
jobss: # Typo here
build:
docker:
- image: cimg/base:2023.04
steps:
- checkout
- run: echo "Building project..."
workflows:
version: 2
build-and-test:
jobs:
- build
Running circleci diagnostics validate would produce an error like this:
Error: Unknown key `jobss` at line 4, column 1.
Did you mean `jobs`?
This immediately tells you what’s wrong and even suggests the fix.
Beyond basic syntax, diagnostics also checks for logical inconsistencies. For instance, if you define a job but don’t include it in any workflow, or if a workflow references a job that doesn’t exist:
version: 2.1
jobs:
build:
docker:
- image: cimg/base:2023.04
steps:
- checkout
- run: echo "Building project..."
workflows:
version: 2
build-and-test:
jobs:
- deploy # This job doesn't exist
The validation command would catch this:
Error: Workflow 'build-and-test' references job 'deploy' which is not defined.
The circleci diagnostics command isn’t just about syntax; it helps enforce best practices and catch common mistakes by understanding the structure of a valid CircleCI configuration. It’s like having a spell-checker and a grammar checker specifically for your CI/CD pipeline definition.
A common pitfall is forgetting to include the version: 2.1 at the top of your config.yml. While circleci diagnostics validate might not always flag this as a hard error if the rest of the syntax is sound, it’s crucial for enabling newer features and ensuring compatibility. The CLI is quite good at inferring intent, but explicit declarations are always best.
The ultimate goal is to have circleci diagnostics validate return with no output, indicating a clean bill of health for your configuration.
Once your config is validated locally, the next step is often to test the actual execution of your steps using circleci diagnostics build.