Skip to main content

CI/CD pipeline

The publishing pipeline moves a Markdown change from pull request to live site with no manual deployment step. This page explains the pipeline configuration and the decisions behind it.

What the pipeline does​

StageTriggerOutput
ValidateEvery pull requestBuild check, broken-link check
BuildMerge to mainStatic site artifact
PublishAfter successful buildUpdated site on hosting target

A writer or engineer opens a pull request, gets feedback from reviewers and CI, and after merge the site updates automatically.

Sample workflow​

The repository uses a GitHub Actions workflow similar to this:

name: Build and deploy docs

on:
push:
branches: [main]
pull_request:
branches: [main]

jobs:
build:
runs-on: ubuntu-latest
steps:
- name: Check out repository
uses: actions/checkout@v4

- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm

- name: Install dependencies
run: npm ci

- name: Generate API reference from OpenAPI
run: npm run docusaurus -- gen-api-docs all

- name: Build site
run: npm run build

- name: Upload build artifact
if: github.ref == 'refs/heads/main'
uses: actions/upload-artifact@v4
with:
name: site
path: build

A second job (omitted here for brevity) picks up the artifact and publishes it to the container-based hosting target.

Design decisions​

  • Build on every pull request, not just on merge. Catching broken Markdown, links, or MDX before merge prevents more errors than detecting them after merge.
  • Generate API reference inside CI. The OpenAPI specification is the source of truth. CI regenerates reference pages on every build so the spec and documentation stay in sync.
  • Use npm ci, not npm install. npm ci produces the same install on every run.
  • Cache the package manager, not the build output. Build output is small and changes often; dependencies are large and change rarely.
  • Separate build from publish. The build job produces an artifact; the publish job consumes it. You can change the hosting target without changing the build job.

What the writer sees​

For authors, the pipeline runs automatically:

  1. Edit Markdown in a branch.
  2. Open a pull request.
  3. Address review comments and any CI failures.
  4. Merge.

A couple of minutes later, the site reflects the change. That integration is intentional: documentation follows the same code review process and does not need a separate publishing step.

Outcomes​

  • No manual publishing step. Documentation releases follow the same cadence as the team's pull-request flow.
  • Changes publish in minutes. Typos, clarifications, and small structural changes ship without a separate deploy.
  • Broken links and MDX errors fail in CI. CI reports broken links and broken MDX before publication, so those errors do not reach the live site.
  • Engineers can merge doc fixes directly. They can contribute fixes without waiting for a writer to publish them.