Switch scheduled Pages deployment from concurrent git pushes to single artifact-based deploy

[Copilot]

• Set publish to false on push by adding github.event_name != 'push' to the deploy job's if condition

Original prompt

Create a pull request in repository m-aciek/python-docs-offline that updates the scheduled GitHub Actions workflow responsible for generating and publishing documentation/PDF builds so that it avoids concurrent pushes/commit conflicts to gh-pages.

Implement the recommended GitHub Pages custom workflow pattern:

• Build outputs in concurrent jobs (matrix or parallel jobs are fine).
• Each build job uploads its generated files as uniquely named artifacts.
• A single deploy job runs after all build jobs (needs:), downloads/merges artifacts into one publish directory, and publishes to GitHub Pages using:
  • actions/configure-pages
  • actions/upload-pages-artifact
  • actions/deploy-pages

Requirements:

1. Do not git push to gh-pages from multiple jobs.
2. Ensure the scheduled workflow continues to run on its existing schedule (cron) and still supports manual workflow_dispatch if currently present.
3. Add the required permissions for Pages deployment (pages: write, id-token: write, and keep contents: read unless additional permissions are strictly needed).
4. Add a concurrency group appropriate for Pages deployments so that overlapping scheduled runs don’t deploy simultaneously (e.g., group per branch/ref).
5. Preserve existing build logic as much as possible (commands, caching, dependencies). Only refactor what’s needed to route outputs through artifacts and deploy once.
6. Ensure the merged site directory structure matches what the repo expects for GitHub Pages (choose _site/ or site/ as appropriate based on existing workflow).
7. Update or add comments in the workflow YAML explaining why artifacts + single deploy job is used.

Deliverables in the PR:

• Modified scheduled workflow YAML under .github/workflows/ implementing the above.
• Any necessary small supporting script changes (only if required to make merging artifacts reliable).
• PR description should mention it fixes push conflicts by switching to artifact-based GitHub Pages deployment.

Notes:

• If there is currently a workflow that commits generated files to gh-pages, replace that mechanism with deploy-pages.
• If the repo uses a custom Pages branch setting, assume standard GitHub Pages with Actions deployment.

Repository: m-aciek/python-docs-offline

The following is the prior conversation context from the user's chat exploration (may be truncated):

User: I'd like to commit generated files in concurrent GH workflow jobs to gh-pages. How to do that avoiding conflicts when pushing?

Assistant: To avoid push conflicts, don’t have multiple concurrent jobs commit/push to gh-pages. Instead: build in parallel → upload artifacts → deploy once in a single job. This is the approach GitHub recommends for Pages with custom workflows (it removes Git race conditions entirely). See: Using custom workflows with GitHub Pages.

Recommended pattern (no git push to gh-pages at all)

1) Build jobs run concurrently and upload artifacts

Use a matrix to generate outputs in parallel, and upload each output as an artifact (name them uniquely per matrix entry).

2) One deploy job runs after all builds

A single deploy job:

• downloads/merges the artifacts into one publish directory
• uploads one Pages artifact
• runs actions/deploy-pages

GitHub documents the upload-pages-artifact + deploy-pages flow here: Using custom workflows with GitHub Pages and the overall “publish with Actions” setup here: Configuring a publishing source for your GitHub Pages site.

Minimal workflow sketch

name: Build & Deploy Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages-${{ github.ref }}
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        part: [a, b, c]   # whatever you split by
    steps:
      - uses: actions/checkout@v5

      # ... generate files for this matrix part into ./out ...

      - name: Upload part artifact
        uses: actions/upload-artifact@v4
        with:
          name: site-${{ matrix.part }}
          path: out/

  deploy:
    runs-on: ubuntu-latest
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/configure-pages@v5

      - name: Download all build artifacts
        uses: actions/download-artifact@v4
        with:
          path: _site_parts/

      - name: Merge into final site dir
        run: |
          mkdir -p _site
        ...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

*This pull request was created from Copilot chat.*
>