ADR-003: Publish documentation as GitLab Pages on release tags only¶

Context and Problem Statement¶

The repository has a fully functional MkDocs documentation site covering the project specs, guidelines, and ADRs. The GitLab CI pipeline already produces a release on vX.Y.Z tags. The question is: when should the documentation be built and published as a GitLab Pages site, and under what trigger?

Decision Drivers¶

• Published docs must match a stable, released version — not work-in-progress content.
• CI cost on day-to-day feature branches should be minimal.
• No separate access control or manual workflow should be required to publish.
• Docs must remain online indefinitely after publication.

Considered Options¶

1. Publish on every commit to the default branch.
2. Publish only on vX.Y.Z release tags.
3. Manual publish (pipeline trigger or button).

Decision Outcome¶

Chosen option: Option 2 — publish only on vX.Y.Z release tags, because it aligns documentation publication with the release lifecycle. Only stable, tagged content is ever visible as the public-facing site.

Positive Consequences¶

• Published docs always correspond to a released, versioned state of the tool.
• No extra CI cost on day-to-day commits or feature branches.
• No manual step required — tagging is sufficient.
• GitLab Pages artifact is retained indefinitely (expire_in: never), so the site stays online between releases without any maintenance.

Negative Consequences / Risks¶

• Docs lag behind main between releases. Acceptable: the specs are versioned alongside the binary, and unreleased changes are not production guidance.

Pros and Cons of the Options¶

Option 1 — Publish on every commit to the default branch¶

• Pro: Docs are always up to date with main.
• Con: WIP content (unreviewed guidelines, draft ADRs) appears as authoritative documentation.
• Con: Additional CI cost on every merge to main.

Option 2 — Publish only on vX.Y.Z release tags (chosen)¶

• Pro: Published docs are always stable and reviewed.
• Pro: Zero CI overhead outside the release pipeline.
• Con: Docs lag behind main between releases — mitigated by the fact that specs and guidelines are versioned with the tool.

Option 3 — Manual publish¶

• Pro: Full control over when docs are published.
• Con: Requires a human action for every update; prone to being forgotten.
• Con: Breaks the "automate everything" principle.

Implementation¶

• GitLab CI job named pages (hard requirement by GitLab Pages) in the release stage.
• Uses registry.gitlab.com/hzahnlei/project-templates/mkdocs:latest as the runner image.
• needs: [build] — docs publish only if the binary builds successfully (quality gate).
• artifacts.expire_in: never — Pages artifacts must not expire.
• Build command: /usr/local/bin/entrypoint.sh build -f image/mkdocs.yml --site-dir public (entrypoint injects mermaid.min.js from the image before delegating to mkdocs).

Links¶

• .gitlab-ci.yml — pages job implementation
• image/mkdocs.yml — MkDocs configuration
• image/Dockerfile-mkdocs — docs build image
• specs/guidelines/ci_cd.md — general CI/CD guidelines (Documentation section)