ci: documentation ci #1
Conversation
|
📘 Site preview available: |
There was a problem hiding this comment.
Pull request overview
This PR introduces a comprehensive documentation CI/CD workflow that builds documentation, deploys PR previews, publishes to GitHub Pages, and cleans up closed PR previews.
Changes:
- Added PR preview deployment with automated preview URLs posted as comments
- Configured separate publish job for production documentation deployment to GitHub Pages
- Implemented cleanup job to remove preview folders from unmerged PRs
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| await github.rest.issues.createComment({ | ||
| owner, | ||
| repo, | ||
| issue_number: pr, | ||
| body: `📘 **Site preview available**:\n\n${url}` | ||
| }); | ||
There was a problem hiding this comment.
The PR comment step creates a new comment on every push to the PR, which will result in multiple comments cluttering the PR conversation. Consider checking if a preview comment already exists and updating it instead of creating a new one each time. You can search for existing comments and update them, or delete the old one before creating a new one.
| await github.rest.issues.createComment({ | |
| owner, | |
| repo, | |
| issue_number: pr, | |
| body: `📘 **Site preview available**:\n\n${url}` | |
| }); | |
| const marker = '<!-- zensical-docs-preview -->'; | |
| const body = `${marker}\n📘 **Site preview available**:\n\n${url}`; | |
| // Find existing preview comment (if any) | |
| const comments = await github.paginate( | |
| github.rest.issues.listComments, | |
| { | |
| owner, | |
| repo, | |
| issue_number: pr, | |
| per_page: 100, | |
| } | |
| ); | |
| const existing = comments.find( | |
| (comment) => typeof comment.body === 'string' && comment.body.includes(marker) | |
| ); | |
| if (existing) { | |
| await github.rest.issues.updateComment({ | |
| owner, | |
| repo, | |
| comment_id: existing.id, | |
| body, | |
| }); | |
| } else { | |
| await github.rest.issues.createComment({ | |
| owner, | |
| repo, | |
| issue_number: pr, | |
| body, | |
| }); | |
| } |
| if: github.event_name == 'pull_request' && | ||
| github.event.action == 'closed' && | ||
| github.event.pull_request.merged == false |
There was a problem hiding this comment.
The cleanup job only runs when a PR is closed without being merged. This means preview folders for merged PRs will remain in the gh-pages branch indefinitely, accumulating over time. Consider also cleaning up preview folders for merged PRs by adjusting the condition to trigger on any PR closure.
| if: github.event_name == 'pull_request' && | |
| github.event.action == 'closed' && | |
| github.event.pull_request.merged == false | |
| if: github.event_name == 'pull_request' && github.event.action == 'closed' |
| steps: | ||
| - uses: actions/checkout@v6 | ||
| - name: Checkout gh-pages branch | ||
| uses: actions/checkout@v4 |
There was a problem hiding this comment.
There's a version mismatch in the checkout actions. Line 22 uses actions/checkout@v6 for the build job, but line 87 uses actions/checkout@v4 for the cleanup job. This inconsistency could lead to unexpected behavior. Use the same version across the workflow for consistency.
| uses: actions/checkout@v4 | |
| uses: actions/checkout@v6 |
| - name: Remove PR preview folder | ||
| run: | | ||
| rm -rf pr-${{ github.event.pull_request.number }} | ||
| - name: Commit cleanup | ||
| run: | | ||
| git config user.name "github-actions" | ||
| git config user.email "github-actions@github.com" | ||
| git commit -am "chore: remove preview for PR #${{ github.event.pull_request.number }}" || exit 0 |
There was a problem hiding this comment.
The cleanup step removes the preview folder but doesn't check if the folder exists before attempting to commit. If the folder doesn't exist (e.g., if the workflow was run before this change was implemented), the git commit will be empty. While the "|| exit 0" handles this case, it's better practice to check if the folder exists first and only proceed if it does, to avoid unnecessary git operations.
| - name: Remove PR preview folder | |
| run: | | |
| rm -rf pr-${{ github.event.pull_request.number }} | |
| - name: Commit cleanup | |
| run: | | |
| git config user.name "github-actions" | |
| git config user.email "github-actions@github.com" | |
| git commit -am "chore: remove preview for PR #${{ github.event.pull_request.number }}" || exit 0 | |
| - name: Remove PR preview folder and commit cleanup | |
| run: | | |
| PR_DIR="pr-${{ github.event.pull_request.number }}" | |
| if [ ! -d "$PR_DIR" ]; then | |
| echo "Preview directory $PR_DIR does not exist; nothing to clean." | |
| exit 0 | |
| fi | |
| rm -rf "$PR_DIR" | |
| git config user.name "github-actions" | |
| git config user.email "github-actions@github.com" | |
| # If there are no changes after removing the directory, skip commit and push | |
| if git diff --quiet; then | |
| echo "No changes to commit after removing $PR_DIR; skipping git commit and push." | |
| exit 0 | |
| fi | |
| git commit -am "chore: remove preview for PR #${{ github.event.pull_request.number }}" |
| name: github-pages | ||
| steps: | ||
| - name: Deploy to GitHub Pages |
There was a problem hiding this comment.
The publish job should have an explicit url output to indicate where the documentation was deployed. This would improve traceability and make it easier to know where the production documentation is hosted after deployment.
| name: github-pages | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| name: github-pages | |
| outputs: | |
| url: ${{ steps.deploy.outputs.page_url }} | |
| steps: | |
| - name: Deploy to GitHub Pages | |
| id: deploy |
No description provided.