Example: a practical CI/CD pipeline for documentation

Worked example

This is a finished illustration to study, not a template - adapt the specific commands to your own static-site generator and hosting platform. For the underlying reasoning, see integrating documentation into development.

The pipeline

name: docs

on:
  pull_request:
  push:
    branches: [main]

jobs:
  build-and-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: npm ci

      - name: Run automated tests
        run: npm test

      - name: Build the site
        run: npm run build

      - name: Check for broken links
        run: npm run check-links

      - name: Deploy preview (pull requests only)
        if: github.event_name == 'pull_request'
        run: npm run deploy:preview

      - name: Deploy to production (main only)
        if: github.ref == 'refs/heads/main'
        run: npm run deploy:production

What each stage catches, and why it’s in this order

1. Automated tests run before the build, not after - a test failure means something is already structurally broken (a malformed redirect table, a schemaSchemaA formal description of the structure a document or data file must follow: which elements or fields are allowed, in what order, and with which values. Validating content against a schema (DTD, XSD, or RELAX NG for XML; JSON Schema for JSON) catches structural errors before publication.View in glossary → violation), and there’s no point spending build time on content that won’t be correct anyway.
2. The build itself is the second gate. A build failure (a broken code sample in a fenced block that the site validates, a missing required frontmatter field) blocks everything downstream automatically.
3. The link checker runs against the built output, not the source MarkdownMarkdownA lightweight plain-text markup language in which formatting is written with simple punctuation, such as a leading # for a heading. It is easy to write and to review under version control, but has no schema to enforce structure, so docs-as-code teams rely on templates and automated checks instead. This manual is written in MDX, a Markdown variant.View in glossary → - link-checking source files misses everything the build pipeline itself generates or rewrites (redirects, generated index pages).
4. Preview deploys only on pull requests. A reviewer gets a real, clickable URL to check the actual rendered result - reviewing a diff of Markdown text alone misses rendering issues a diff can’t show.
5. Production deploy is gated on branchBranchA parallel line of work in a version-control system: changes made on a branch stay isolated until they are reviewed and merged back into the main line, so several writers, releases or languages can progress at the same time.View in glossary →, not on manual approval to trigger - once something merges to main, it has already passed review, so the deploy step is mechanical, not a second decision point.

What this pipeline deliberately doesn’t do

• It doesn’t gate on a subjective “does this read well” check - that’s what technical and editorial review are for, done by humans before the PR reaches CI, not encoded as an automated rule.
• It doesn’t skip tests on the main branch push - the same gate applies whether the trigger is a PR or a direct merge, so nothing reaches production that hasn’t been checked.

Next step

A green pipeline shows that the site builds and its links resolve; it does not show that the documentation is ready to ship with a product release. Use the release readiness checklist as the release gate. To see the pipeline from the writer’s side, follow one change through the basic docs-as-code workflow.