docs-as-code-ci-setup

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.