From c49aa812ed8a102534ae8cedd604fdeaa2adccbd Mon Sep 17 00:00:00 2001 From: Jared Galloway Date: Mon, 20 Jul 2026 18:27:30 -0600 Subject: [PATCH] ci: fix docs workflow PEP 668 failure + gate it on PRs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit debian:bookworm (adopted when we moved off EOL debian:buster) marks its system Python as externally managed per PEP 668, so `pip install` into it now fails with 'externally-managed-environment'. Pass --break-system-packages on the two pip calls — this job builds docs in a throwaway container, so system-Python install is fine and keeps sphinx on PATH for buildDocs.sh. Also add a pull_request trigger: this workflow previously ran only on push to main, so its failure slipped past PR #200's checks and only surfaced after merge. Now a broken docs build gates the PR. Co-Authored-By: Claude Fable 5 --- .github/workflows/docs_pages_workflow.yml | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs_pages_workflow.yml b/.github/workflows/docs_pages_workflow.yml index b2650fa..f99fd31 100644 --- a/.github/workflows/docs_pages_workflow.yml +++ b/.github/workflows/docs_pages_workflow.yml @@ -1,9 +1,12 @@ name: docs_pages_workflow -# execute this workflow automatically when we push to main +# execute this workflow automatically when we push to main, and on PRs to +# main so a broken docs build gates the PR instead of only failing after merge on: push: branches: [ main ] + pull_request: + branches: [ main ] jobs: @@ -46,8 +49,12 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | - python3 -m pip install --upgrade pip - python3 -m pip install -e ".[dev]" + # debian:bookworm marks its system Python as externally managed + # (PEP 668), so pip refuses to install into it without this flag. + # This job builds docs in a throwaway container, so installing into + # system Python is fine and keeps sphinx on PATH for buildDocs.sh. + python3 -m pip install --upgrade --break-system-packages pip + python3 -m pip install --break-system-packages -e ".[dev]" shell: bash - name: Execute script to build our documentation and update pages