Migrate docs deployment to Pages artifacts

[rdsa-nv]

Description

Migrate the multi-version documentation deployment from commits on the
gh-pages branch to GitHub Pages artifacts.

The current nightly workflow uses peaceiris/actions-gh-pages, which commits
the complete generated documentation site to gh-pages after every deploy.
That branch now contributes approximately 656 MiB of compressed Git data and
accounts for about 95% of the repository's clone payload.

This change uploads the generated site with actions/upload-pages-artifact
and deploys it with actions/deploy-pages. It also grants the deploy job the
minimal pages: write and id-token: write permissions and records the
deployment URL on the github-pages environment.

After this workflow is merged and a deployment is verified, a repository
administrator must:

1. Set Settings > Pages > Build and deployment > Source to GitHub Actions.
2. Run the Docs workflow once and verify the versioned documentation site.
3. Delete the remote gh-pages branch.

Deleting gh-pages is expected to reduce a normal clone's compressed Git
payload from approximately 694 MiB to 84 MiB without requiring users to pass
--single-branch or --depth 1.

Type of change

• Bug fix (non-breaking change which fixes an issue)

Screenshots

Not applicable; the generated documentation content and URLs are unchanged.

Validation

• ./isaaclab.sh -f
• YAML validation through the repository pre-commit hooks

Checklist

• I have read and understood the contribution guidelines
• I have run the pre-commit checks with ./isaaclab.sh -f
• I have made corresponding changes to the documentation (not applicable)
• My changes generate no new warnings
• I have added tests that prove the fix is effective (workflow-only change)
• I have added a changelog fragment (no package is changed)
• I have added my name to CONTRIBUTORS.md or my name already exists there

[greptile-apps]

Greptile Summary

This PR replaces the peaceiris/actions-gh-pages deployment approach (which commits the full docs site to a gh-pages branch on every nightly run) with GitHub's native Pages artifact pipeline (actions/upload-pages-artifact + actions/deploy-pages). The change is expected to reduce the repository's clone payload from ~694 MiB to ~84 MiB after the gh-pages branch is deleted.

• The build-multi-docs job now calls actions/upload-pages-artifact@v4 instead of actions/upload-artifact@v7; the fixed artifact name (github-pages) is inferred automatically by the action, so no name: key is needed.
• The deploy-docs job drops the explicit artifact download and peaceiris/actions-gh-pages step, replacing them with actions/deploy-pages@v4; it gains the minimal required permissions (pages: write, id-token: write) and registers the github-pages environment with the deployment URL.

Confidence Score: 4/5

The change is straightforward and well-scoped: it swaps three GitHub Actions for the two official Pages actions, adds the correct minimal permissions, and wires up the github-pages environment.

The action wiring (upload-pages-artifact → deploy-pages), permissions (pages: write, id-token: write), and environment name (github-pages) are all correct. The sole concern is that the workflow-level concurrency group is keyed on github.sha rather than the recommended fixed 'pages' group, meaning two simultaneous manual or scheduled runs could both proceed to the deploy stage. GitHub serialises these internally, so it is not a hard failure, but it diverges from the recommended pattern and could leave a stale deployment queued.

.github/workflows/docs.yaml — the concurrency block at the top of the file is the only area worth a second look before merging.

Important Files Changed

Filename	Overview
.github/workflows/docs.yaml	Migrates docs deployment to GitHub Pages artifacts; permissions, environment, and action versions look correct, but the workflow-level concurrency group does not follow the GitHub-recommended 'pages' group pattern for preventing simultaneous Pages deployments.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant S as Schedule / workflow_dispatch
    participant DBT as doc-build-type job
    participant BMD as build-multi-docs job
    participant DD as deploy-docs job
    participant GHP as GitHub Pages

    S->>DBT: trigger
    DBT-->>BMD: "trigger-deploy == true"
    BMD->>BMD: git fetch + make multi-docs
    BMD->>GHP: upload-pages-artifact (artifact: github-pages)
    DBT-->>DD: "trigger-deploy == true"
    BMD-->>DD: build-multi-docs complete
    DD->>GHP: deploy-pages (fetches github-pages artifact)
    GHP-->>DD: page_url
    DD-->>DD: "environment url = page_url"

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant S as Schedule / workflow_dispatch
    participant DBT as doc-build-type job
    participant BMD as build-multi-docs job
    participant DD as deploy-docs job
    participant GHP as GitHub Pages

    S->>DBT: trigger
    DBT-->>BMD: "trigger-deploy == true"
    BMD->>BMD: git fetch + make multi-docs
    BMD->>GHP: upload-pages-artifact (artifact: github-pages)
    DBT-->>DD: "trigger-deploy == true"
    BMD-->>DD: build-multi-docs complete
    DD->>GHP: deploy-pages (fetches github-pages artifact)
    GHP-->>DD: page_url
    DD-->>DD: "environment url = page_url"

Loading

Comments Outside Diff (1)

1. .github/workflows/docs.yaml, line 28-31 (link)

   Pages-specific concurrency group missing

   GitHub's own starter workflows for Pages deployments recommend a dedicated group: "pages" concurrency group with cancel-in-progress: false to serialise deployments and avoid a race between two simultaneous workflow_dispatch triggers (or a stale scheduled run that overlaps a manual one). The current workflow-level group is keyed on github.sha, which is unique per run for scheduled events, so two concurrent runs will not cancel each other and both will attempt to deploy. GitHub Pages does queue concurrent deployments internally, but the recommended pattern is to express the intent explicitly in the workflow.

_{Reviews (1): Last reviewed commit: "Migrate docs deployment to Pages artifac..." | Re-trigger Greptile}