ci: add PR documentation preview workflow#14
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a GitHub Actions workflow to build the Sphinx documentation for each pull request, upload the HTML output as an artifact, and post/update a PR comment with download instructions.
Changes:
- Add
PR Documentation Previewworkflow triggered on PR open/sync/reopen. - Build docs via
make htmland uploadbuild/html/as an artifact. - Find and create/update a PR comment pointing to the artifact download.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| permissions: | ||
| contents: read | ||
| pull-requests: write |
There was a problem hiding this comment.
peter-evans/find-comment / create-or-update-comment create an issue comment via the Issues API. The workflow grants pull-requests: write but not issues: write, which can cause the comment steps to fail with insufficient permissions. Add issues: write (and keep/remove pull-requests: write as needed).
| pull-requests: write | |
| pull-requests: write | |
| issues: write |
| - name: Find existing comment | ||
| uses: peter-evans/find-comment@v3 | ||
| id: find-comment | ||
| with: | ||
| issue-number: ${{ github.event.pull_request.number }} | ||
| comment-author: 'github-actions[bot]' | ||
| body-includes: 'Documentation Preview' | ||
|
|
||
| - name: Create or update comment | ||
| uses: peter-evans/create-or-update-comment@v4 | ||
| with: | ||
| comment-id: ${{ steps.find-comment.outputs.comment-id }} | ||
| issue-number: ${{ github.event.pull_request.number }} | ||
| edit-mode: replace |
There was a problem hiding this comment.
On pull_request events from forks, GITHUB_TOKEN is read-only and cannot write PR/issue comments. Without a guard, the comment steps will fail and the whole job will be marked failed for fork PRs. Consider gating the find/create comment steps to same-repo PRs (e.g. only when github.event.pull_request.head.repo.full_name == github.repository) or making the comment steps non-fatal.
| HTML documentation has been built for this PR. | ||
|
|
||
| **Download the preview:** | ||
| 1. Go to [Artifacts](#{{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) |
There was a problem hiding this comment.
The Artifacts link in the PR comment is prefixed with #, which turns it into a page fragment (e.g. #https://...) instead of a navigable URL. Remove the leading # so the link points to the workflow run URL directly.
| 1. Go to [Artifacts](#{{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) | |
| 1. Go to [Artifacts](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) |
No description provided.