codegen-guard

Fail CI when a generated file drifts from its source of truth — on any CI system, not just GitHub Actions.

Most codebases with codegen (protobuf, GraphQL codegen, OpenAPI/AsyncAPI clients, Prisma, ORM migrations, generated changelogs, generated docs...) end up hand-rolling the same step: run the generator, then git diff --exit-code and fail if anything changed. If you're on GitHub Actions, there are good existing GitHub-Actions-only tools for this — tj-actions/verify-changed-files and CatChen/check-git-status-action are both solid, established, and worth using. If you're on GitLab CI, CircleCI, Jenkins, Azure Pipelines, Buildkite, or you just want the same check locally via a pre-commit hook, there wasn't a dedicated tool — people were asking how to hand-roll it. codegen-guard is a plain Node CLI (not a GitHub Action), so it runs anywhere node and git do — one config, any CI, and your laptop.

npm run generate:types
git diff --exit-code -- src/generated/

becomes

codegen-guard

Install

npm install --save-dev codegen-guard

Configure

Create codegen-guard.config.json at your project root:

{
  "tasks": [
    {
      "name": "api-types",
      "command": "npm run generate:types",
      "paths": ["src/generated/"]
    },
    {
      "name": "changelog",
      "command": "npm run generate:changelog",
      "paths": ["CHANGELOG.md"]
    }
  ]
}

• command — runs with child_process.execSync in your project root (inherits stdio, so its own output streams through).
• paths — files/directories to check for drift after the command runs. Passed straight to git diff and git status, so glob-like directory paths work.

See examples/ for ready-to-copy generator configs (protobuf, GraphQL Codegen, OpenAPI clients, Prisma, and a multi-task monorepo setup), and examples/ci/ for drop-in snippets covering GitHub Actions, GitLab CI, CircleCI, Jenkins, Azure Pipelines, and a local pre-commit hook.

Use

codegen-guard          # same as: codegen-guard check
codegen-guard check    # run each task, fail (exit 1) if any output differs from what's committed
codegen-guard fix      # run each task and leave the regenerated output in place, for you to review/commit
codegen-guard --json   # machine-readable output, for scripting around it
codegen-guard --version
codegen-guard --help

Exit code is 0 only when every task ran successfully and produced no drift. In check mode, a failing task prints the actual git diff so you can see exactly what changed.

CI examples

# GitHub Actions / GitLab CI / Azure Pipelines / anywhere with npm
- run: npm ci
- run: npx codegen-guard

Full working examples for GitHub Actions, GitLab CI, CircleCI, Jenkins, and Azure Pipelines are in examples/ci/.

If someone edits a source of truth (a .proto, an OpenAPI spec, a schema) but forgets to regenerate and commit the derived file, this step fails with the diff instead of the stale file silently merging.

Why not just a shell script, or an existing action?

If you're on GitHub Actions specifically, tj-actions/verify-changed-files and CatChen/check-git-status-action are mature, well-adopted options — genuinely consider them first. codegen-guard exists for everyone else: teams on GitLab CI, CircleCI, Jenkins, Azure Pipelines, or who want the exact same check to run locally in a pre-commit hook, not just in CI. One config file, one CLI, works everywhere node and git do. It also handles the untracked-new-file case that a plain git diff --exit-code misses, and fix/check share one config instead of drifting from each other.

Design

Zero runtime dependencies. Node's built-in child_process and git CLI only (git is assumed to already be available in any CI environment that has something to diff).

License

MIT