gitlab-ci-doctor

Audit .gitlab-ci.yml for waste, cost leaks, and security gaps. Sister project to ci-doctor (GitHub Actions). Same engine, same opinions, GitLab-native rules.

npx gitlab-ci-doctor                  # audit current repo
npx gitlab-ci-doctor --markdown       # MR-comment friendly
npx gitlab-ci-doctor --json           # machine-readable
npx gitlab-ci-doctor --severity=warn  # warn + error only
npx gitlab-ci-doctor --rules          # list checks
npx gitlab-ci-doctor --demo           # smoke-test against bundled bad pipeline

Exit code is 1 when there are error-level findings, so it drops into a GitLab CI job (or a pre-commit hook) without ceremony.

What it catches

| Rule | Severity | Why it matters | | --- | --- | --- | | image-no-pin | warn | :latest and bare image names are mutable; pin a digest. | | missing-cache | warn | npm/pip/gradle/cargo etc. without cache: re-download every run. | | missing-interruptible | warn | Stale pipelines on superseded MR commits keep burning minutes. | | missing-timeout | warn | A hung job runs to the project default (often 1h, max 24h). | | expensive-runner | warn | saas-linux-large/2xlarge, saas-windows, saas-macos cost 2x to 10x. | | artifact-no-expiration | warn | artifacts: without expire_in: accumulate storage cost. | | deprecated-only-except | info | Migrate to rules: (composes with workflow:rules). | | git-strategy-clone | warn | clone re-fetches full history every job; prefer fetch + GIT_DEPTH. | | parallel-overcommit | warn | parallel: > 8 multiplies job minutes; sanity-check the matrix. | | missing-needs | info | Stages without needs: block on the entire previous stage. | | wide-rules | info | No rules: and no workflow:rules runs on every push and every MR. | | include-no-pin | warn | Remote/project includes without an immutable ref give upstream control of your pipeline. |

CI usage (GitLab native)

ci-doctor:
  stage: lint
  image: node:22-alpine
  interruptible: true
  cache:
    key: "$CI_COMMIT_REF_SLUG-npx"
    paths:
      - .npm/
  script:
    - npx --yes gitlab-ci-doctor --markdown > ci-doctor.md
    - cat ci-doctor.md
  artifacts:
    when: always
    paths:
      - ci-doctor.md
    expire_in: 1 week
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

Programmatic use

const { auditPipeline, summarize } = require('gitlab-ci-doctor');
const fs = require('node:fs');

const findings = auditPipeline(fs.readFileSync('.gitlab-ci.yml', 'utf8'), '.gitlab-ci.yml');
console.log(summarize(findings));

License

MIT. PRs welcome.

Sponsor / support depmedic

If this saved you 10 minutes of CI debugging, consider one of these. All of them keep the free CLIs free:

• Tip what you want — pay-what-you-want, $0 minimum: https://buy.polar.sh/polar_cl_tipjar?utm_source=npm&utm_medium=readme&utm_campaign=gitlab-ci-doctor
• depmedic Pro $5/mo — one license, unlocks Pro tier in every depmedic CLI + the VS Code / Cursor extension, free access to every paid playbook for as long as you stay subscribed: https://buy.polar.sh/polar_cl_SUzmX5RCQCV8MJV3dDEBFMu3MGWu2WQhzZ1s02ZhK09?utm_source=npm&utm_medium=readme&utm_campaign=gitlab-ci-doctor
• Everything Bundle $59 once — every paid playbook (current and future): https://buy.polar.sh/polar_cl_everything_bundle?utm_source=npm&utm_medium=readme&utm_campaign=gitlab-ci-doctor
• Sponsor on GitHub — https://github.com/sponsors/depmedicdev-byte

More from depmedic

| | | | --- | --- | | ci-doctor | audit GitHub Actions for cost + security (16 rules) | | gitlab-ci-doctor | same engine for .gitlab-ci.yml (14 rules) | | bitbucket-ci-doctor | for bitbucket-pipelines.yml (8 rules) | | azure-pipelines-ci-doctor | for azure-pipelines.yml (8 rules) | | circleci-ci-doctor | for .circleci/config.yml (8 rules) | | gha-budget | $-denominated cost estimate of any GHA workflow | | pin-actions | one-shot SHA pinner for uses: blocks | | cursor-rules-init | scaffold .cursor/rules/ for your stack | | depmedic | all-in-one cli, finds outdated/risky deps | | depmedic/ci-doctor-action | composite GitHub Action: PR comment + SARIF |

In-browser scanners (no install): GitHub · GitLab · Bitbucket · Azure · CircleCI.

Newsletter (weekly, low-volume): https://depmedicdev-byte.github.io/newsletter.html?utm_source=npm&utm_medium=readme&utm_campaign=gitlab-ci-doctor.