Skip to content

D0022 book-deploy

Rule: A book with a site_url is built strict and published with actions/deploy-pages by one workflow.

Code D0022 (stable, never reused)
Id book-deploy
Category book
Source spirit_level
Fix by hand

Level per tier

Tier Level Reason
small warn a book published by hand falls behind main, and a broken page goes live; one workflow builds it strict and deploys it
small-workspace warn a book published by hand falls behind main, and a broken page goes live; one workflow builds it strict and deploys it
medium warn a book published by hand falls behind main, and a broken page goes live; one workflow builds it strict and deploys it
big warn a book published by hand falls behind main, and a broken page goes live; one workflow builds it strict and deploys it
ai off
embedded off
ui off
egui off
units-strict off
units-paranoid off

Why

A book with a site_url says where readers find it. If it is built and published by hand, the site falls behind the repo, and a page that broke since the last upload goes live unnoticed. A workflow that builds the book strict and publishes it keeps the site at the address equal to main, and a broken page or link fails the run before it reaches anyone.

The workflows are read from .github/workflows/; GitHub's Pages settings are not checked. One workflow must do both, since actions/deploy-pages publishes only an artifact of its own run:

  • a run: step builds strict: zensical build --strict or mkdocs build --strict, or just RECIPE where the recipe's body does;
  • a step uses actions/deploy-pages, usually in a job after the build has uploaded the site with actions/upload-pages-artifact.
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v6
      - run: uv run zensical build --strict
      - uses: actions/upload-pages-artifact@v3
        with:
          path: site/
  deploy:
    needs: build
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    permissions:
      pages: write
      id-token: write
    environment:
      name: github-pages
    steps:
      - uses: actions/deploy-pages@v4

A book without a site_url is not checked.

How to fix

Add the workflow, or the missing build or deploy step to the workflow that has the other one. Set the repository's Pages source to "GitHub Actions" once.

Configure

[lints.book-deploy]
level = "deny"
reason = "why this project wants it at this level"

Allow one finding in the code with // spirit-level: allow(book-deploy) <reason> (waivers); the code works there too, as in [lints.D0022].