A continuous documentation audit for your CI pipeline

What is a continuous documentation audit?

It's a check that runs every time you push code, re-reads your app, and asks: can this build still be explained, and did anything get worse since last time? Instead of documenting your app once and watching the docs rot, you keep a living grade that moves as your code moves.

Traditional documentation is a snapshot. You write it, it's accurate for a week, then you ship three changes and it quietly becomes a lie. A continuous audit closes that gap by re-running on every change and telling you when your app has drifted away from what your docs claim.

Explain My Build's CI audit produces two signals on every run:

• A build grade — how well your current code can be explained and documented, as an at-a-glance score.
• A regression signal — a plain-English list of what got worse since the last scan: features that lost coverage, new gaps, things that were clear and now aren't.

Both are cited to your actual code. When the audit can't verify something, it flags it rather than guessing — the same honesty that governs every artifact we produce (see limitations).

What is the regression signal and why does it matter?

The regression signal is the answer to one question: what got worse since my last scan? A regression is anything that worked or was clear before and isn't now — a feature that lost its documentable shape, a config that went undefined, a data-access rule that loosened.

This matters because AI-assisted changes are notorious for side effects. You ask for one fix; three unrelated things shift. On a single manual review you'll never catch that. On every push, a diff-aware audit will.

Rather than re-reading a wall of text each time, you read a short list: here is what changed for the worse. That's the signal you actually act on.

How is this different from Codacy or SonarQube?

Codacy and SonarQube grade your code's quality and security. Explain My Build grades your build's documentability and docs-drift. They're complementary, not competing — and they answer different questions.

Codacy and SonarQube (and SonarQube Cloud, formerly SonarCloud) are excellent at what they do: static analysis (SAST), software composition analysis, secrets detection, infrastructure-as-code scanning, code complexity, duplication, and quality gates that can block a merge. They tell you if your code is buggy, insecure, or messy. That's genuinely valuable, and if you're CI-comfortable you should probably run one.

What they don't do is tell you whether your app can be explained to the people who use it, or whether your understanding of your own app has drifted from the code. That's the gap Explain My Build fills.

In short: run Codacy or SonarQube for code health. Run Explain My Build for the story your app tells and how that story drifts.

Does my code leave my infrastructure?

No. In CI, the audit runs inside your own pipeline, on your own runners, against code that never leaves your infrastructure. There's no upload step and no copy of your repo sitting on our servers.

This is the same privacy stance as the rest of the product. For public repos, we read from the GitHub URL you paste and delete the code after generating — never stored. For private repos and local folders, everything runs entirely in your browser or via CLI so the code never leaves your machine. In CI, it runs in your infra. Pick whichever fits your risk tolerance.

How do I wire the CI audit into my pipeline?

Add one step to your existing CI workflow. It runs the audit, produces the grade and regression signal, and reports back on the run — no code leaves your infra. Here's the shape of it:

1. Add the audit step to your CI config. In your workflow file (for example a GitHub Actions job), add a step that runs the Explain My Build CLI against your repo checkout.

   - name: Explain My Build audit
     run: npx explainmybuild audit --ci

2. Point it at your repo root. The CLI reads your checked-out source in place. Nothing is uploaded; the read and the grading happen on your runner.
3. Let it write the grade and regression signal. Each run produces a build grade and a "what got worse since last scan" list, saved as a build artifact you can open from the run.
4. Compare against your last scan. The audit reads the previous run's baseline (stored in your repo or CI cache) to compute the regression diff. First run establishes the baseline; every run after shows drift.
5. Decide your policy. Start by treating the audit as informational — read the signal, act on it. When you trust it, you can fail the build on a dropped grade or a new regression, the same way you'd gate on a quality check.

That's it. One step, in your infra, on every push. See how the underlying read works, or try a one-off scan first before wiring CI.