ci: move docs deploy into a separate workflow by jiwenc-nv · Pull Request #372 · NVIDIA/IsaacTeleop

jiwenc-nv · 2026-04-08T22:18:56Z

Docs PR Preview Deploy — How It Works

The fork PR problem

When a PR comes from a fork, GitHub runs the pull_request-triggered workflow in the fork's context. The GITHUB_TOKEN it gets is scoped to the fork — it can read the base repo but cannot write to it. That's why git push origin gh-pages on NVIDIA/IsaacTeleop returns 403.

Why `workflow_run` fixes it

workflow_run is special: it always runs in the base repo's context, even when the triggering workflow ran on a fork PR. So:

	`pull_request` trigger	`workflow_run` trigger
Runs as	Fork repo	Base repo (`NVIDIA/IsaacTeleop`)
`GITHUB_TOKEN` can write to base?	No	Yes
Has access to repo secrets?	No	Yes

By splitting build (safe, no write needed) from deploy (needs write), the deploy runs with base-repo permissions.

Why the two-artifact handoff?

Since this is a separate workflow run, it doesn't share the workspace of the build workflow. The three download-artifact steps use run-id to reach back and grab artifacts from the triggering build run. That's also why actions: read permission is needed — downloading artifacts cross-run requires it.

Why the PR number is passed via artifact

In a workflow_run context, github.event.pull_request doesn't exist — the event payload is about the workflow run, not the PR. So the build workflow saves the PR number to a file, and this workflow reads it back to construct the preview/pr-<N>/ destination path.

The `environment: docs-preview` gate

This is the manual approval layer. Without it, the deploy would run automatically for every fork PR — which means untrusted code could generate arbitrary HTML and push it to your GitHub Pages. The environment's required reviewers ensure someone with write access eyeballs the build before it goes live.

Setup

Create a docs-preview environment in repo Settings → Environments, then add required reviewers (anyone with write access to the repo).

Does this block PR merging?

No. workflow_run is completely decoupled from the PR's status checks. It runs as a separate workflow associated with the default branch, not the PR's head commit.

Never approved → sits pending indefinitely, PR is unaffected
Approved but fails → PR is unaffected
Approved and succeeds → PR is unaffected (preview just appears)

Only workflows triggered directly by pull_request / push events can appear as status checks on a PR, and only those added to branch protection's "required status checks" can block merging. The workflow_run workflow won't show up there at all.

The preview deploy is entirely opt-in / best-effort — it never gates merging.

Flow summary

Fork PR opened
  → "Build & deploy docs" runs (fork context, read-only)
    → builds docs + webapp, uploads artifacts + PR number
    → deploy-docs job: skipped (not a deploy branch)
    → workflow completes with conclusion=success
  → "Deploy docs PR preview" fires (base repo context, write access)
    → waits for "docs-preview" environment approval
    → reviewer approves
    → downloads artifacts from the build run
    → pushes to gh-pages at preview/pr-<N>/

coderabbitai · 2026-04-08T22:19:11Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 0edf9699-ce38-459e-869b-f31bfdb61d97

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

📝 Walkthrough

Walkthrough

This change implements a separation of concerns for documentation deployment by introducing a new GitHub Actions workflow (docs-deploy-preview.yaml) that handles PR preview deployments independently. The existing docs.yaml workflow is simplified to focus solely on building documentation and capturing PR metadata as an artifact. The new workflow subscribes to the completion of the build workflow, downloads the prebuilt documentation and webapp artifacts, merges the webapp into the documentation build output, and deploys the combined content to a GitHub Pages preview directory under environment protection (manual approval required).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: refactoring docs deployment into a separate workflow by adding a new workflow file and simplifying the existing one.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

Create PR with unit tests

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

coderabbitai

Actionable comments posted: 3

🧹 Nitpick comments (1)

.github/workflows/docs.yaml (1)
189-194: Consider upgrading peaceiris/actions-gh-pages to v4.

While peaceiris/actions-gh-pages@v3 will still execute on GitHub Actions runners as of April 2026, the v3 line is no longer actively maintained. Upgrade to peaceiris/actions-gh-pages@v4 (current major release) to use the maintained version and avoid future compatibility warnings.
Suggested change
      - name: Deploy to gh-pages
        uses: peaceiris/actions-gh-pages@v3
+       uses: peaceiris/actions-gh-pages@v4
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/docs.yaml around lines 189 - 194, Update the GitHub Action
step that uses the peaceiris deployment action by changing the version reference
from peaceiris/actions-gh-pages@v3 to peaceiris/actions-gh-pages@v4 in the
"Deploy to gh-pages" job; ensure the step name "Deploy to gh-pages" and its
inputs (github_token, publish_dir, keep_files) remain unchanged and run CI to
confirm there are no breaking input changes between v3 and v4.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/docs-deploy-preview.yaml:
- Around line 21-30: Add a per-PR concurrency group to the deploy-preview job so
preview deploys are serialized and older runs are cancelled when a newer run for
the same PR starts; update the deploy-preview job (job name: deploy-preview) to
include a concurrency block that sets group to a PR-specific value using the
event payload (e.g. github.event.workflow_run.pull_requests[0].number) and set
cancel-in-progress: true so stale runs cannot complete and overwrite newer
previews.
- Around line 64-70: The workflow step "Deploy PR preview to gh-pages" uses
peaceiris/actions-gh-pages@v3 which targets Node16 and will fail on modern
runners; update the `uses:` value to peaceiris/actions-gh-pages@v4 (leave other
inputs like github_token, publish_dir, destination_dir, and keep_files
unchanged) so the action runs on Node18-compatible runners.
- Around line 29-57: The workflow's permissions block is missing the actions:
read scope required for cross-run artifact downloads; update the permissions
object to include actions: read alongside contents: write so the
actions/download-artifact@v7 steps (the "Download PR metadata", "Download docs
artifact", and "Download web app artifact" steps) can access artifacts from
another run using run-id and github-token without 403 errors. Ensure the
permissions entry is added at the same level as the existing contents: write so
the three download steps succeed.

---

Nitpick comments:
In @.github/workflows/docs.yaml:
- Around line 189-194: Update the GitHub Action step that uses the peaceiris
deployment action by changing the version reference from
peaceiris/actions-gh-pages@v3 to peaceiris/actions-gh-pages@v4 in the "Deploy to
gh-pages" job; ensure the step name "Deploy to gh-pages" and its inputs
(github_token, publish_dir, keep_files) remain unchanged and run CI to confirm
there are no breaking input changes between v3 and v4.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 8d4b0e88-0325-4f0e-b5de-9c5798319c10

📥 Commits

Reviewing files that changed from the base of the PR and between f420f71 and 9791d39.

📒 Files selected for processing (2)

.github/workflows/docs-deploy-preview.yaml
.github/workflows/docs.yaml

jiwenc-nv requested a review from aristarkhovNV April 8, 2026 22:19

jiwenc-nv force-pushed the jiwenc/docs-deploy-preview branch from 745b1d2 to 9791d39 Compare April 8, 2026 22:19

coderabbitai Bot reviewed Apr 8, 2026

View reviewed changes

Comment thread .github/workflows/docs-deploy-preview.yaml Outdated

Comment thread .github/workflows/docs-deploy-preview.yaml

Comment thread .github/workflows/docs-deploy-preview.yaml

ci: move docs deploy into a separate workflow

f71313b

jiwenc-nv force-pushed the jiwenc/docs-deploy-preview branch from 9791d39 to f71313b Compare April 8, 2026 23:32

aristarkhovNV approved these changes Apr 9, 2026

View reviewed changes

jiwenc-nv had a problem deploying to dev April 9, 2026 21:59 — with GitHub Actions Failure

jiwenc-nv had a problem deploying to dev April 9, 2026 22:06 — with GitHub Actions Failure

Skip pushblish wheel for 3rd parth PR

2ff2fb7

jiwenc-nv merged commit d033855 into NVIDIA:main Apr 10, 2026
36 checks passed

jiwenc-nv deleted the jiwenc/docs-deploy-preview branch April 10, 2026 00:22

jiwenc-nv had a problem deploying to dev April 10, 2026 01:37 — with GitHub Actions Failure

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ci: move docs deploy into a separate workflow#372

ci: move docs deploy into a separate workflow#372
jiwenc-nv merged 2 commits intoNVIDIA:mainfrom
jiwenc-nv:jiwenc/docs-deploy-preview

jiwenc-nv commented Apr 8, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Apr 8, 2026 •

edited

Loading

Review skipped

Walkthrough

Estimated code review effort

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

jiwenc-nv commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Docs PR Preview Deploy — How It Works

The fork PR problem

Why workflow_run fixes it

Why the two-artifact handoff?

Why the PR number is passed via artifact

The environment: docs-preview gate

Setup

Does this block PR merging?

Flow summary

Uh oh!

coderabbitai Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Walkthrough

Estimated code review effort

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

jiwenc-nv commented Apr 8, 2026 •

edited

Loading

Why `workflow_run` fixes it

The `environment: docs-preview` gate

coderabbitai Bot commented Apr 8, 2026 •

edited

Loading