| name | docs-as-code-ci-setup |
| description | Use when wiring the docs quality gate into CI/CD — turning docs-as-code:validate into a check that blocks pull requests on a docs/frontmatter/link failure. Covers GitHub Actions, GitLab CI, and a generic shell gate, plus making CODEOWNERS enforce doc review. |
Docs-as-Code CI Setup
The point of docs-as-code is that the machine catches the mechanical errors (missing
frontmatter, broken links, drift) so humans review judgement — but only if the check actually runs
on every pull request and blocks merge when it fails. This skill wires that gate.
What runs in CI
The primary gate is docs-validate.sh (frontmatter + Markdown lint + link check). It exits
non-zero on failure, so any CI system blocks the merge. Add docs-trace.sh --check (traceability
gaps) and check-contracts.sh (contract↔code) as additional required checks — a contract break
can hit a consumer who changed nothing of their own, so treat contract-sync as required, not optional.
GitHub Actions
The kit's own real, runnable workflow is
.github/workflows/validate.yml — note it is the kit's
self-test: it first runs validate-skills.sh (plugin manifest + skill linting), then applies the
docs gate (check-contracts.sh, docs-validate.sh, docs-trace.sh) scoped to
examples/nova-superapp. For a target repo you want only the docs steps, pointed at your docs
path — copy the trimmed, target-repo-ready workflow in
references/ci-examples.md, not the kit's self-test verbatim. Then set the job as a required status
check in branch protection so it truly blocks. (The bigger examples/nova-superapp/.github/ workflows/validate.yml is an illustrative super-app pipeline with placeholders — read it for the
multi-mini-app shape, but copy the real one above.)
GitLab CI / generic
For GitLab, add a job that runs bash scripts/docs-validate.sh in the test stage; a non-zero
exit fails the pipeline. For any other system, the rule is the same: run the one script, let its
exit code gate the merge. See references/ci-examples.md for copyable
GitHub Actions and GitLab snippets.
Make review mandatory
CI catches the mechanical; CODEOWNERS makes the human review mandatory. Add a CODEOWNERS that
routes docs/** to the doc owners and each contract to its consumers, then require code-owner
review in branch protection. Now a docs change cannot merge without both the green gate and the
right human sign-off.
Principle
Deployment of the check ≠ enforcement. A validate script that runs but does not block is theatre —
the merge-blocking required-check is what stops drift.
