depmedic / circleci-ci-doctor

circleci-ci-doctor

Audit any .circleci/config.yml for waste, cost leaks, and security gaps. Eight rules. One command. MIT. Fifth in the depmedic CI auditor family alongside ci-doctor (GitHub), gitlab-ci-doctor, bitbucket-ci-doctor, azure-pipelines-ci-doctor.

npm npmjs.com/package/circleci-ci-doctor | source github.com/depmedicdev-byte/circleci-ci-doctor | try it in-browser scanner

Try it in 5 seconds

$ npx circleci-ci-doctor                  # audit current repo
$ npx circleci-ci-doctor --markdown       # PR-comment friendly output
$ npx circleci-ci-doctor --json           # machine-readable
$ npx circleci-ci-doctor --severity=warn  # warn + error only
$ npx circleci-ci-doctor --rules          # list checks
$ npx circleci-ci-doctor --demo           # smoke-test against bundled bad config

The 8 rules

Rule	Severity	What it catches
`expensive-resource-class`	warn / cost	Job uses `resource_class: xlarge`, `2xlarge`, or `3xlarge` without heavy build/test commands. Each tier roughly doubles credits per minute.
`macos-executor`	warn / cost	Job uses a `macos:` executor without xcodebuild / fastlane / swift / pod. macOS minutes cost ~10x Linux Docker.
`docker-no-pin`	warn / security	`docker.image` not pinned to `image@sha256:<digest>`. Floating tags break reproducibility.
`missing-cache`	warn / cost	Job runs `npm` / `pip` / `maven` / `gradle` / `cargo` / `go` / `bundler` install but no `restore_cache` + `save_cache` pair.
`orb-no-pin`	warn / security	Orb ref not `MAJOR.MINOR.PATCH` (e.g. `circleci/node@5` or `@volatile`). Floating refs silently update.
`missing-no-output-timeout`	warn / cost	Hang-prone `run:` step (tests, deploys, migrations, `tail -f`, `docker compose up`) without `no_output_timeout`. Default 10 min — too long.
`secret-echo`	warn / security	`env`, `printenv`, `set -x`, or `echo $TOKEN` in a `run:` block — secrets leak to the build log.
`wide-filters`	warn / cost	Workflow job has no `filters:` — runs on every branch including draft and Renovate branches.

Drop into a workflow

version: 2.1
orbs:
  node: circleci/node@5.1.0
jobs:
  ci-audit:
    docker:
      - image: cimg/node:20.10@sha256:<digest>
    resource_class: small
    steps:
      - checkout
      - run:
          name: ci-doctor
          command: npx --yes circleci-ci-doctor --markdown | tee ci-doctor.md
          no_output_timeout: 2m
      - store_artifacts:
          path: ci-doctor.md
workflows:
  audit:
    jobs:
      - ci-audit:
          filters:
            branches:
              only: [main, /^pr\/.*/]

Why a fifth one?

CircleCI bills in credits per minute with a multiplier by resource_class (small = 5, medium = 10, large = 20, xlarge = 40, 2xlarge = 80, 3xlarge = 120) and macOS at roughly 10x Linux Docker. The default 10-min no_output_timeout means a hung step with no terminal output gets killed mid-run; the same setting often eats the whole job's wall-clock when teams configure it way too high.

And: orbs are remote code that runs in your build. Pinning them to MAJOR.MINOR.PATCH (or better, by certified digest) is the same hygiene as pinning uses: in GitHub Actions.

Audit one repo right now

The in-browser scanner takes a paste, runs all 8 rules, and shows the report inline. Nothing leaves your browser.

Open the scanner View source