Add Netlify preview deployment for pull requests

[Copilot]

• Remove PUT .../pin call — GitHub's pin-comment API rejects PR issue numbers and requires write access the GITHUB_TOKEN doesn't have on pull_request events
• Keep create/update comment logic intact

Original prompt

Goal

Add a netlify-preview job to the existing .github/workflows/sphinxbuild.yml workflow that deploys a full documentation preview to Netlify for every pull request, with a stable per-PR URL.

How the existing workflow works

The sphinxbuild.yml workflow already:

1. build job: builds all 3 manuals (user_manual, admin_manual, developer_manual) and uploads them as artifacts
2. stage-and-check job: downloads all artifacts, assembles them into stage/<branch_name>/ (e.g. stage/latest/), and saves it to an Actions cache keyed by staged-docs-${{ github.sha }}
3. deploy job: only runs on push (not PRs), deploys to gh-pages

What needs to be added

Add a new job netlify-preview to the workflow with the following behaviour:

Trigger

• Only runs on pull_request events (if: github.event_name == 'pull_request')
• Runs after stage-and-check (needs: stage-and-check)

Steps

1. Restore the staged cache using actions/cache/restore with key staged-docs-${{ github.sha }} — this is already saved by stage-and-check, so no rebuild is needed.

2. Assemble the Netlify deploy directory: The stage/ folder has the structure stage/<branch_name>/<manual_name>/. Flatten this into a netlify-deploy/ directory like:

   netlify-deploy/
   ├── index.html           ← simple root index linking to the 3 manuals
   ├── user_manual/         ← contents of stage/<branch>/user_manual/
   ├── admin_manual/        ← contents of stage/<branch>/admin_manual/
   └── developer_manual/   ← contents of stage/<branch>/developer_manual/
   

   The root index.html should be a minimal HTML page with links to each manual subdirectory.

3. Deploy to Netlify using nwtgck/actions-netlify@v3 with:

   • publish-dir: netlify-deploy
   • alias: pr-${{ github.event.pull_request.number }} — gives a stable per-PR URL like https://pr-42--<site-name>.netlify.app
   • github-token: ${{ secrets.GITHUB_TOKEN }} — so it posts a comment on the PR with the preview URL
   • deploy-message: "PR #${{ github.event.pull_request.number }} preview"
   • enable-pull-request-comment: true
   • enable-commit-comment: false
   • overwrites-pull-request-comment: true
   • NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
   • NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}

Permissions

The netlify-preview job needs:

permissions:
  contents: read
  pull-requests: write

Summary job update

Update the existing summary job's needs array to include netlify-preview, and update the summary step logic to handle it correctly:

• On pull_request: netlify-preview must succeed (or be skipped if secrets aren't set)
• On push: netlify-preview must be skipped

The condition in the summary should gracefully handle the case where NETLIFY_AUTH_TOKEN / NETLIFY_SITE_ID secrets are not yet configured (the netlify action will simply fail in that case, so the summary should treat result == 'skipped' || result == 'success' as acceptable for PRs).

Notes

• Do not modify the build, stage-and-check, or deploy jobs.
• Do not re-download artifacts or re-run sphinx — reuse the cache from stage-and-check.
• Pin the nwtgck/actions-netlify action to a specific commit SHA (use v3 tag resolved to its SHA, or use nwtgck/actions-netlify@v3.0.0 if a specific SHA isn't available — check the action's repo for the latest pinnable SHA).
• The stage/<branch_name>/ subfolder name comes from needs.stage-and-check.outputs.branch_name.
• Add a comment in the workflow explaining that NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID must be set as repository secrets.

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

User: Do you think you can use the sphinxbuild workflow and deploy the documentation on netlify so we can have a temporary overview of a PR ?
The staging step should provide a full set of how the docs is supposed to look.

Assistant: Yes, absolutely! I have a clear picture of what's needed. Here's what the existing workflow already has:

• ✅ build job: builds all 3 manuals (user, admin, developer) as artifacts
• ✅ stage-and-check job: assembles them into a stage/<branch>/ folder, cached by SHA
• ✅ deploy job: deploys to gh-pages (push only)

The plan is to add a new netlify-preview job that:

1. Runs only on PRs, after stage-and-check
2. Reuses the already-cached stage/ folder (no extra build cost)
3. Assembles a full deploy dir with all 3 manuals + a root index
4. Deploys to Netlify as a named alias (pr-<number>) for a stable URL
5. Posts the preview URL as a PR comment automatically

This requires two repository secrets to be configured: NETLIFY_AUTH_TOKEN and NETLIFY_SITE_ID.

Shall I open a PR with the workflow changes?

User: What would the URLs look like ? Ideally one for each PR ?

Assistant: With the `alias: pr-${{ github.event.pull_req...

This pull request was created from Copilot chat.

[skjnldsv]

@copilot the gh-pages already contains everything. You don't have to build a new index.html or something. Maybe you can just add the netlify step into the deploy job ? So we avoid caching and restoring 2GB again?

If it's a PR, deploy to detlify, if not, create the PR against gh-pages as it currently is ?

[Copilot]

@skjnldsv I've opened a new pull request, #14406, to work on those changes. Once the pull request is ready, I'll request review from you.

[Copilot]

@copilot the gh-pages already contains everything. You don't have to build a new index.html or something. Maybe you can just add the netlify step into the deploy job ? So we avoid caching and restorin...

Done in 937510e. The separate netlify-preview job is gone. The existing deploy job now handles both events:

• push → apply staged artifacts to gh-pages and open the deployment PR (unchanged)
• pull_request → same checkout + artifact-apply, then deploy server/ (full gh-pages content with new artifacts on top) to Netlify

No new cache step is needed since gh-pages is already checked out and the staged artifacts are applied before the Netlify deploy runs.

[github-actions]

🚀 Netlify preview deployed: https://pr-14401--nextcloud-documentation.netlify.app