CI/CD Integration

Run boringdocs in your CI pipeline to catch documentation drift on every commit.

GitHub Actions

name: Docs Validation
on: [push, pull_request]

jobs:
  boringdocs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install boringdocs
        run: npm install -g boringdocs

      - name: Run validation
        run: boringdocs check

GitLab CI

boringdocs:
  image: node:20
  script:
    - npm install -g boringdocs
    - boringdocs check
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == "main"

Pre-commit Hook

Run boringdocs before each commit using husky:

npx husky add .husky/pre-commit "boringdocs check --staged"

The --staged flag only checks files in the git staging area, making it fast for local development.

Exit Codes

boringdocs uses standard exit codes for CI integration:

Code	Meaning
0	All checks passed
1	Validation errors found
2	Configuration error
3	Runtime error

Annotations

On GitHub Actions, boringdocs outputs annotations that appear directly in the PR diff:

$ boringdocs check --format github

::error file=src/api/users.ts,line=42::POST /users missing description
::warning file=docs/api.md,line=15::Section "Legacy API" has no matching code

Configuration

CI-specific settings in boringdocs.yaml:

ci:
  fail_on: error      # error | warning | info
  format: github      # text | json | github | gitlab
  parallel: true
  cache: true