Overview

Usage

1. Install dependencies

• pre-commit
• circleci-cli

2. Create config file .pre-commit-config.yaml with content:

• For CircleCI config validation :

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0 # Ensure this is the latest tag, comparing to the Releases tab
  hooks:
    - id: circleci_validate

• For CircleCI config processing test :

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0 # Ensure this is the latest tag, comparing to the Releases tab
  hooks:
    - id: circleci_process

If you wish to pass additional args to circleci_validate or circleci_process, you can specify them in the config. See circleci config validate --help or circleci config process --help for accepted args. You must use the form --arg=value, not --arg value.

For example, to set an org-slug:

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0 # Ensure this is the latest tag, comparing to the Releases tab
  hooks:
    - id: circleci_validate
      args:
        - --org-slug=my/organization

Or specify a custom config file:

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0
  hooks:
    - id: circleci_validate
      args:
        - .circleci/continue_config.yml

The CircleCI process hook allow passing multiple configuration files.

For example :

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0
  hooks:
    - id: circleci_process
      args:
        - '--pipeline-parameters={"foo": "bar"}'
        - .circleci/config-1.yml
        - .circleci/config-2.yml

Dynamic Configuration (Continuation Orb)

For projects using CircleCI's dynamic configuration with the continuation orb and a modular src/ directory structure, use the circleci_pack_validate hook:

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0
  hooks:
    - id: circleci_pack_validate
      args:
        - --setup-config=.circleci/config.yml
        - --src-dir=.circleci/src

This hook will:

1. Validate the setup config (e.g., .circleci/config.yml)
2. Pack the modular config from src/ directory
3. Validate the packed continuation config

Pack only (without validation)

If you only need to pack the configuration:

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0
  hooks:
    - id: circleci_pack
      args:
        - --src-dir=.circleci/src
        - --output=.circleci/main-config.yml

Skip setup or continuation validation

You can skip either part of the validation:

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0
  hooks:
    - id: circleci_pack_validate
      args:
        - --skip-setup  # Only validate the packed continuation config

$ cat .pre-commit-config.yaml
- repo: https://github.com/zahorniak/pre-commit-circleci.git
  rev: v1.3.0
  hooks:
    - id: circleci_pack_validate
      args:
        - --skip-continuation  # Only validate the setup config

3. Install hook

$ pre-commit install
pre-commit installed at .git/hooks/pre-commit

4. Commit code

$ git commit -m "add circleci hook"
Validate CircleCI config.................................................Passed
Process CircleCI configuration...........................................Passed
[branchname 1111111] add circleci hook
 1 file changed, 5 insertions(+), 1 deletion(-)

How hook works

Hook	Description
circleci_validate	Validates CircleCI configuration using command circleci config validate
circleci_process	Process the CircleCI configuration(s) using command circleci config process
circleci_pack	Packs modular CircleCI config from src/ directory using circleci config pack
circleci_pack_validate	Packs and validates CircleCI dynamic configuration (for continuation orb setups)

Run hook manually

$ pre-commit run -a
Validate CircleCI config.................................................Passed
Process CircleCI configuration...........................................Passed