Skip to content

Preview docs on forked repo #428

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jiwenc-nv wants to merge 2 commits into from
Closed

Preview docs on forked repo #428

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
2609e24
Revert "ci: move docs deploy into a separate workflow"
jiwenc-nv Apr 29, 2026
e5c886e
docs: instruction on previewing docs
jiwenc-nv Apr 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
92 changes: 0 additions & 92 deletions .github/workflows/docs-deploy-preview.yaml
View file
Open in desktop

This file was deleted.

60 changes: 39 additions & 21 deletions .github/workflows/docs.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,8 @@
# SPDX-License-Identifier: Apache-2.0
#
# Build docs and Teleop web app, then deploy to GitHub Pages.
# - Push to main/release (canonical repo): build + deploy docs at site root, web app at /client/.
# - Pull requests: build only; preview deploy is handled by docs-deploy-preview.yaml
# via workflow_run (runs in base-repo context so fork PRs get write access).
# - Push to main (canonical repo): deploy docs at site root, web app at /client/.
# - Pull requests: deploy to preview/pr-<N>/ (docs at root of preview, app at preview/pr-<N>/client/).
#
# PR: docs always built; web client (npm) built with public SDK for all, or private SDK only for allowlisted authors.
# Main/release (push): key used → private NGC for SDK.
Expand Down Expand Up @@ -96,17 +95,6 @@ jobs:
name: docs-html
path: ./docs/build

- name: Save PR number
if: github.event_name == 'pull_request'
run: echo "${{ github.event.pull_request.number }}" > pr-number.txt

- name: Upload PR metadata
if: github.event_name == 'pull_request'
uses: actions/upload-artifact@v6
with:
name: pr-metadata
path: pr-number.txt

build-app:
name: Build Teleop Web App
runs-on: ubuntu-latest
Expand Down Expand Up @@ -163,9 +151,7 @@ jobs:
name: Deploy docs
runs-on: ubuntu-latest
needs: [check-repo, build-docs, build-app]
if: >-
needs.check-repo.outputs.is-canonical-repo == 'true'
&& needs.check-repo.outputs.is-deploy-branch == 'true'
if: needs.check-repo.outputs.is-canonical-repo == 'true' && (needs.check-repo.outputs.is-deploy-branch == 'true' || github.event_name == 'pull_request')
permissions:
contents: write # push to gh-pages
steps:
Expand All @@ -183,12 +169,44 @@ jobs:

- name: Place web app under subpath
run: |
mkdir -p ./docs/build/client
cp -r ./webapp/. ./docs/build/client/
if [ "${{ github.event_name }}" = 'pull_request' ]; then
CLIENT_DIR=./docs/build/current/client
else
CLIENT_DIR=./docs/build/client
fi
mkdir -p "$CLIENT_DIR"
cp -r ./webapp/. "$CLIENT_DIR/"

- name: Deploy to gh-pages
uses: peaceiris/actions-gh-pages@v4
- name: Deploy to gh-pages (main branch)
if: github.event_name == 'push' && needs.check-repo.outputs.is-deploy-branch == 'true'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/build
keep_files: true

- name: Deploy PR preview to gh-pages
if: github.event_name == 'pull_request'
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/build/current
destination_dir: preview/pr-${{ github.event.pull_request.number }}
keep_files: true
Comment on lines +180 to +195
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Apr 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify affected references in this workflow
rg -n 'peaceiris/actions-gh-pages@v3|peaceiris/actions-gh-pages@v4' .github/workflows/docs.yaml

Repository: NVIDIA/IsaacTeleop

Length of output: 158

🌐 Web query:

peaceiris/actions-gh-pages v3 v4 compatibility GitHub runners deprecation

💡 Result:

peaceiris/actions-gh-pages v4.0.0 (released April 8, 2024) is fully compatible with current GitHub-hosted runners including ubuntu-latest, macos-latest, and windows-latest. It requires Node.js >=20.11.0, addressing the prior Node 16 deprecation. v3 (e.g., v3.9.3) uses Node >=16.19.0, which faced deprecation warnings after GitHub Actions transitioned from Node 16 to Node 20 (enforced June 2024). Users were recommended to upgrade to v4. As of 2026-04-29: - Node 20 (v4's requirement) reaches EOL on 2026-04-30 but remains supported on runners until June 2, 2026 (default switch to Node 24), with full removal later in 2026. - An open issue (#1143, March 2026) proposes bumping to Node 24, but v4.0.0 remains current release and functional. - No deprecation of the action itself; compatible with all listed runners (ubuntu-22.04/20.04/latest, macos-latest, windows-latest). - Recommendation: Use @v4 or @v4.0.0 for stability; pin to commit hash for maximum reliability.

Citations:

peaceiris/actions-gh-pages@v3 uses Node 16, which is no longer compatible with current GitHub runners.

Lines 182 and 190 use @v3, which requires Node >=16.19.0. GitHub deprecated Node 16 from runners (enforced June 2024). Deployment jobs will fail on current runners. Upgrade to @v4, which requires Node 20 and is the current stable release.

Suggested fix 
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4

(Apply to both lines 182 and 190)

🧰 Tools
🪛 actionlint (1.7.12)

[error] 182-182: the runner of "peaceiris/actions-gh-pages@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

[error] 190-190: the runner of "peaceiris/actions-gh-pages@v3" action is too old to run on GitHub Actions. update the action's version to fix this issue

(action)

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/docs.yaml around lines 180 - 195, Update the GitHub Action
steps that use peaceiris/actions-gh-pages to the v4 major release: change the
two occurrences of "uses: peaceiris/actions-gh-pages@v3" (the "Deploy to
gh-pages (main branch)" and "Deploy PR preview to gh-pages" steps) to "uses:
peaceiris/actions-gh-pages@v4" so the workflow runs on current runners with Node
20 compatibility.


- name: Add preview URL to workflow summary
if: github.event_name == 'pull_request'
run: |
base="https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/preview/pr-${{ github.event.pull_request.number }}/"
client_url="${base}client/"
{
echo "## Docs preview"
echo
echo "Built docs for this PR are available at:"
echo
echo "**${base}**"
echo
echo "Teleop web app (subpath \`/client/\`): **${client_url}**"
echo
echo "(It may take a minute to appear after the workflow completes.)"
} >> "$GITHUB_STEP_SUMMARY"
44 changes: 44 additions & 0 deletions docs/source/getting_started/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,3 +9,47 @@ We welcome contributions. Please see the repository's `CONTRIBUTING.md <https://
- Code of conduct and how to contribute
- Development setup and coding standards
- Pull request process

Previewing documentation changes
--------------------------------

Local build
~~~~~~~~~~~

Build the docs locally to catch broken links and rendering issues before opening
a pull request:

.. code-block:: bash

cd docs
pip install -r requirements.txt
make current-docs

The output is written to ``docs/build/current/``. Open ``index.html`` in a
browser to inspect it. Sphinx is run with ``-W --keep-going``, so warnings are
treated as errors — fix them locally before pushing.

PR preview on GitHub Pages
~~~~~~~~~~~~~~~~~~~~~~~~~~

Pull requests that touch the documentation automatically trigger the
``Build & deploy docs`` workflow. When the PR branch lives in
``NVIDIA/IsaacTeleop`` (not a fork), the workflow publishes a preview to
GitHub Pages at:

.. code-block:: text

https://nvidia.github.io/IsaacTeleop/preview/pr-<N>/

The preview link is also added to the workflow run's *Summary* tab. It is
refreshed on each push to the PR. Previews accumulate on the ``gh-pages``
branch under ``preview/``; maintainers can clear them by manually running the
``Cleanup docs PR previews`` workflow from the Actions tab.

.. note::

Pull requests opened **from a fork** do not get an automatic preview because
the workflow's ``GITHUB_TOKEN`` is read-only in that context and cannot push
to ``gh-pages``. If you have write access to ``NVIDIA/IsaacTeleop``, push
your branch there directly to get a preview; otherwise, attach screenshots of
your local build to the PR description.
Loading