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
| Stage | Trigger | Output |
|---|---|---|
| Validate | Every pull request | Build check, broken-link check |
| Build | Merge to main | Static site artifact |
| Publish | After successful build | Updated 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, notnpm install.npm ciproduces 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:
- Edit Markdown in a branch.
- Open a pull request.
- Address review comments and any CI failures.
- 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.