From b4fbfbbdfc0a8ae3be7bb470fe28e48115946d91 Mon Sep 17 00:00:00 2001 From: konard Date: Fri, 3 Jul 2026 16:06:32 +0000 Subject: [PATCH 1/2] Initial commit with task details Adding .gitkeep for PR creation (default mode). This file will be removed when the task is complete. Issue: https://github.com/link-foundation/python-ai-driven-development-pipeline-template/issues/26 --- .gitkeep | 1 + 1 file changed, 1 insertion(+) create mode 100644 .gitkeep diff --git a/.gitkeep b/.gitkeep new file mode 100644 index 0000000..0aec987 --- /dev/null +++ b/.gitkeep @@ -0,0 +1 @@ +# .gitkeep file auto-generated at 2026-07-03T16:06:32.067Z for PR creation at branch issue-26-ac9237118bd1 for issue https://github.com/link-foundation/python-ai-driven-development-pipeline-template/issues/26 \ No newline at end of file From ddc0b6fa076d4c705a13bf3929a068617315695b Mon Sep 17 00:00:00 2001 From: konard Date: Fri, 3 Jul 2026 16:11:56 +0000 Subject: [PATCH 2/2] fix(docs): gate pages deployment --- .github/workflows/docs.yml | 20 +++++++---- .gitkeep | 1 - README.md | 33 +++++++++++-------- .../20260703_issue_26_docs_pages_opt_in.md | 3 ++ tests/test_workflows.py | 29 ++++++++++++++++ 5 files changed, 64 insertions(+), 22 deletions(-) delete mode 100644 .gitkeep create mode 100644 changelog.d/20260703_issue_26_docs_pages_opt_in.md diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 2bf418b..1c12a13 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -2,12 +2,14 @@ name: Docs # Builds Sphinx documentation on every push and PR that touches docs/, src/, or # this workflow. On pushes to main the rendered site is published to GitHub -# Pages. PRs only build to verify the docs still compile. +# Pages only after deployment is explicitly enabled. PRs only build to verify +# the docs still compile. # # One-time setup: in the repository's Settings -> Pages, set Source to -# "GitHub Actions". Without this, the first run of the deploy job fails on -# actions/deploy-pages with "Get Pages site failed". This cannot be configured -# from a workflow. See README.md "Deploying API documentation". +# "GitHub Actions", then set the DEPLOY_GITHUB_PAGES repository variable to +# "true". Without the variable, deployment is skipped with a notice. Without +# Pages configured, actions/deploy-pages fails with "Get Pages site failed". +# See README.md "Deploying API documentation". on: push: @@ -64,12 +66,16 @@ jobs: path: _site if-no-files-found: error + - name: Report skipped GitHub Pages deployment + if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_GITHUB_PAGES != 'true' + run: echo "::notice::Skipping GitHub Pages deployment. To enable publishing, set Settings -> Pages -> Source = GitHub Actions, then add repository variable DEPLOY_GITHUB_PAGES=true." + - name: Configure GitHub Pages - if: github.event_name == 'push' && github.ref == 'refs/heads/main' + if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_GITHUB_PAGES == 'true' uses: actions/configure-pages@v6 - name: Upload GitHub Pages artifact - if: github.event_name == 'push' && github.ref == 'refs/heads/main' + if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_GITHUB_PAGES == 'true' uses: actions/upload-pages-artifact@v5 with: path: _site @@ -77,7 +83,7 @@ jobs: deploy: name: Deploy to GitHub Pages needs: [build] - if: github.event_name == 'push' && github.ref == 'refs/heads/main' + if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.DEPLOY_GITHUB_PAGES == 'true' runs-on: ubuntu-latest timeout-minutes: 10 environment: diff --git a/.gitkeep b/.gitkeep deleted file mode 100644 index 0aec987..0000000 --- a/.gitkeep +++ /dev/null @@ -1 +0,0 @@ -# .gitkeep file auto-generated at 2026-07-03T16:06:32.067Z for PR creation at branch issue-26-ac9237118bd1 for issue https://github.com/link-foundation/python-ai-driven-development-pipeline-template/issues/26 \ No newline at end of file diff --git a/README.md b/README.md index 207ef6e..ee18e73 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ A comprehensive template for AI-driven Python development with full CI/CD pipeli - **CI/CD pipeline**: GitHub Actions CI/CD with Python 3.13 - **Changelog management**: Scriv for conflict-free changelog (like Changesets in JS) - **Release automation**: Automatic PyPI publishing and GitHub releases -- **API documentation**: Sphinx + GitHub Pages deploy on push to `main` +- **API documentation**: Sphinx + opt-in GitHub Pages deploy on push to `main` ## Quick Start @@ -88,7 +88,7 @@ ruff check . && ruff format --check . && mypy src/ && python scripts/check_file_ . ├── .github/ │ └── workflows/ -│ ├── docs.yml # Sphinx build + GitHub Pages deploy +│ ├── docs.yml # Sphinx build + opt-in GitHub Pages deploy │ └── release.yml # CI checks + release automation (PyPI + GitHub) ├── changelog.d/ # Changelog fragments (like .changeset/) │ ├── README.md # Fragment instructions @@ -189,9 +189,9 @@ The GitHub Actions workflow provides: ### API Documentation -API documentation is built with [Sphinx](https://www.sphinx-doc.org/) and deployed -to GitHub Pages on every push to `main`. Pull requests build the docs (without -deploying) to catch regressions before they merge. +API documentation is built with [Sphinx](https://www.sphinx-doc.org/) and can be +deployed to GitHub Pages on pushes to `main`. Pull requests build the docs +(without deploying) to catch regressions before they merge. ```bash # Install docs dependencies @@ -213,15 +213,20 @@ this template, update `project`, `author`, and the autosummary target in #### Deploying API documentation The `Docs` workflow (`.github/workflows/docs.yml`) builds on every push and -pull request, and deploys to GitHub Pages only on `push` to `main` (matching -the JS and Rust template patterns; see -[link-foundation/relative-meta-logic#170](https://github.com/link-foundation/relative-meta-logic/pull/170) -for the bug this guards against). - -**One-time setup per repository**: open `Settings → Pages` and set -`Source = GitHub Actions`. Without this, the first deploy run fails on -`actions/deploy-pages` with `Get Pages site failed`. This cannot be configured -from a workflow. +pull request. On `push` to `main`, it deploys to GitHub Pages only when the +repository variable `DEPLOY_GITHUB_PAGES` is set to `true`. This keeps fresh +repositories green while still validating their docs before Pages is configured. + +**One-time setup per repository**: + +1. Open `Settings -> Pages` and set `Source = GitHub Actions`. +2. Open `Settings -> Secrets and variables -> Actions -> Variables`, then add + repository variable `DEPLOY_GITHUB_PAGES` with value `true`. + +Without the variable, the workflow logs a notice and skips deployment without +failing. Without the Pages source setting, an opted-in deploy fails on +`actions/deploy-pages` with `Get Pages site failed`. The Pages source setting +cannot be configured from a workflow. ### Preview regeneration parity diff --git a/changelog.d/20260703_issue_26_docs_pages_opt_in.md b/changelog.d/20260703_issue_26_docs_pages_opt_in.md new file mode 100644 index 0000000..d4c9aa5 --- /dev/null +++ b/changelog.d/20260703_issue_26_docs_pages_opt_in.md @@ -0,0 +1,3 @@ +### Fixed + +- GitHub Pages deployment in the docs workflow is now opt-in via the `DEPLOY_GITHUB_PAGES` repository variable, so fresh repositories still validate docs without failing on unconfigured Pages. diff --git a/tests/test_workflows.py b/tests/test_workflows.py index 9334fc6..7b33994 100644 --- a/tests/test_workflows.py +++ b/tests/test_workflows.py @@ -228,3 +228,32 @@ def test_docs_workflow_action_versions_are_current() -> None: assert_action_pin_absent(docs_workflow, "actions/configure-pages", "v5") assert_action_pin_absent(docs_workflow, "actions/upload-pages-artifact", "v3") assert_action_pin_absent(docs_workflow, "actions/deploy-pages", "v4") + + +def test_docs_workflow_deploys_pages_only_when_opted_in() -> None: + """Fresh repositories should build docs without failing Pages deployment.""" + workflow = read_workflow("docs.yml") + build_job = workflow_job_block(workflow, "build") + deploy_job = workflow_job_block(workflow, "deploy") + configure_step = workflow_step_block(build_job, "Configure GitHub Pages") + upload_step = workflow_step_block(build_job, "Upload GitHub Pages artifact") + skip_step = workflow_step_block(build_job, "Report skipped GitHub Pages deployment") + + deploy_condition = ( + "github.event_name == 'push' && " + "github.ref == 'refs/heads/main' && " + "vars.DEPLOY_GITHUB_PAGES == 'true'" + ) + skip_condition = ( + "github.event_name == 'push' && " + "github.ref == 'refs/heads/main' && " + "vars.DEPLOY_GITHUB_PAGES != 'true'" + ) + + assert f"if: {deploy_condition}" in configure_step + assert f"if: {deploy_condition}" in upload_step + assert f"if: {deploy_condition}" in deploy_job + assert f"if: {skip_condition}" in skip_step + assert "::notice::" in skip_step + assert "DEPLOY_GITHUB_PAGES=true" in skip_step + assert "Settings -> Pages" in skip_step