Skip to content

Documentation Deployment

deploy-docs.yml converts the checked-in handbook into a GitHub Pages artifact and deploys that exact artifact. The workflow keeps toolchain discovery, build, verification, artifact selection, permissions, and the Pages environment in one visible custody chain.

flowchart LR
    T[Admitted manual dispatch] --> C[Resolve configuration]
    C --> S[Provision required toolchains]
    S --> B[Run install and build commands]
    B --> R[Resolve site directory]
    R --> V[Verify index and configured checks]
    V --> U[Upload Pages artifact]
    U --> D[Deploy github-pages environment]

Trigger and permission boundary

The workflow supports only workflow_dispatch on refs/heads/main, with an explicit accepted_commit selected by the authorized publication controller. The admission job validates the authenticated actor and exact accepted commit before building. Its product evidence comes from the accepted human pull request; a dependency notice cannot supply publication readiness.

Repository content is read-only for construction. Pages and identity-token write permissions belong to the deployment job, which targets the protected github-pages environment and reports the deployed URL. Concurrency is scoped to the ref, with stale runs canceled.

Configuration precedence

Deploy settings may come from explicit environment, repository variables, or .github/docs-deploy.env, with built-in defaults last. The resolver determines:

  • public site URL and expected site directory;
  • install, build, and verification commands;
  • Python, Node.js, and Rust versions; and
  • whether Python, uv, Node.js, or Rust setup is required.

When commands are not configured, the workflow discovers known Make targets. It refuses the run if no docs build command can be found. Toolchain detection uses checked-in project files; it does not install every ecosystem unconditionally.

Build and artifact resolution

The configured build receives the public site URL. If no recognizable site is produced and the repository has MkDocs plus a docs target, the workflow makes one explicit fallback attempt. It then searches the configured directory and a small set of governed artifact locations.

The selected directory must exist and contain index.html. An optional verify command runs against that exact directory. The Pages bundle is validated again before actions/upload-pages-artifact receives it.

State Meaning
docs build command passed the configured generator completed
site directory resolved one candidate contains a publishable index
verify command passed repository-specific site checks accepted that candidate
Pages artifact uploaded immutable deploy input exists for this run
deploy job passed GitHub Pages accepted and deployed that artifact

Failure interpretation

Failure Inspect
no build command repository variables, deploy environment, and root Make help
no index.html configured output directory and actual MkDocs destination
verification failure DOCS_SITE_DIR, generated links, assets, and public URL
build passes but deploy skips trigger type, ref, and build output flag
deployment denied Pages environment and workflow permissions

Managed-source boundary

The workflow is a synchronized consumer of the shared bijux-std deployment contract. Repository documentation, MkDocs configuration, and supported deploy configuration remain local. Changes to workflow mechanics belong upstream; changes to handbook content and repository-specific build behavior belong here.

The published site is supported only when its source commit, build command, selected directory, uploaded Pages artifact, and deployment result refer to the same workflow run.

Publication documentation environment

make gh-docs-install creates the command-owned environment at artifacts/root/docs/venv and synchronizes only the root docs dependency group. It validates uv.lock with uv sync --locked --only-group docs --no-install-workspace; application packages, editable workspace distributions and the root development environment are not installed or replaced. The standard-library environment is created without bundled pip or virtualenv startup hooks, so renderer inventories retain explicit installed source ownership. The repository's existing development groups and package release contexts remain unchanged. Dependency or plugin changes require an intentional lock review.

make gh-docs-build and make gh-docs-verify use that same documentation interpreter. They retain accepted standard source checks, production URL/output selection, strict rendering, CSP/routes, publication admission and readonly verification. Installation alone does not qualify a renderer profile or authorize publication: a new runtime requires actual hosted Linux fingerprints and reviewed source-owned admission before the publication gate can pass. Unowned environments, symlinked artifact paths and a stale lock are rejected; command-owned interrupted creation can resume without deleting unrelated environments or earlier receipts.