From 858234d06e6845d75420d2558e236526282e5da6 Mon Sep 17 00:00:00 2001
From: Kelly Guo <kellyg@nvidia.com>
Date: Sun, 19 Jul 2026 16:37:05 -0700
Subject: [PATCH] Migrate docs deployment to Pages artifacts on main (#6612)

# Description

Backport #6571 from `develop` to `main` so the production documentation
workflow can deploy through GitHub Pages artifacts.

The current nightly workflow commits the complete generated
multi-version
site to `gh-pages`. That branch contributes approximately 656 MiB of
compressed Git data and accounts for most of the repository clone
payload.
This change uploads the generated site with
`actions/upload-pages-artifact`
and publishes it with `actions/deploy-pages` instead.

Documentation content, URLs, and multi-version behavior are unchanged.
After
this merges, a repository administrator must set the Pages source to
GitHub
Actions, run the Docs workflow once from `main`, verify the deployment,
and
then delete `gh-pages` after the rollback window.

## Type of change

- Bug fix (non-breaking CI/infrastructure change)

## Validation

- Confirmed the applied patch ID exactly matches merged PR #6571.
- Ran `./isaaclab.sh -f` before committing; all hooks passed.
- Ran `./isaaclab.sh -f` again after committing and before pushing; all
hooks
  passed.
- Validated the production-like workflow in
https://github.com/kellyguo11/IsaacLab-public/actions/runs/29675383308.
- Verified the deployed root redirect, version selector, representative
  branches/tags, and static assets.

## Checklist

- [x] I have read and understood the contribution guidelines.
- [x] I have run the pre-commit checks with `./isaaclab.sh -f`.
- [x] Documentation changes are not required; published content is
unchanged.
- [x] My changes generate no new warnings.
- [x] A code test is not applicable; the deployment workflow was
validated
  end-to-end in the fork.
- [x] A package changelog fragment is not required because no package
changed.
- [x] The contributors from #6571 are already represented in the
project.
---
 .github/workflows/docs.yaml | 28 +++++++++++++---------------
 1 file changed, 13 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
index a3ce358cc79e..c04c8a100cd6 100644
--- a/.github/workflows/docs.yaml
+++ b/.github/workflows/docs.yaml
@@ -114,10 +114,9 @@ jobs:
         git for-each-ref --format="%(refname:short)" refs/heads/ | xargs -r git branch -D
         make multi-docs
 
-    - name: Upload docs artifact
-      uses: actions/upload-artifact@v7
+    - name: Upload GitHub Pages artifact
+      uses: actions/upload-pages-artifact@v4
       with:
-        name: docs-html
         path: ./docs/_build
 
   deploy-docs:
@@ -127,16 +126,15 @@ jobs:
     # deploy only on "deploy" branches
     if: needs.doc-build-type.outputs.trigger-deploy == 'true'
 
-    steps:
-    - name: Download docs artifact
-      uses: actions/download-artifact@v8
-      with:
-        name: docs-html
-        path: ./docs/_build
+    permissions:
+      pages: write
+      id-token: write
 
-    - name: Deploy to gh-pages
-      uses: peaceiris/actions-gh-pages@v4
-      with:
-        github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ./docs/_build
-        keep_files: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+    - name: Deploy GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4