Skip to content

ci: documentation ci #1

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

Merged
paul58914080 merged 1 commit into from
Jan 18, 2026
Merged

ci: documentation ci #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
96 changes: 91 additions & 5 deletions .github/workflows/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,100 @@
name: Documentation
on:
pull_request:
types: [opened, synchronize, reopened, closed]
branches:
- feature/zensical
push:
branches:
- main
- feature/zensical
permissions:
contents: read
pages: write
id-token: write
contents: write # gh-pages + cleanup
pull-requests: write # PR comments
pages: write # deploy-pages
id-token: write # required by deploy-pages
jobs:
build:
if: github.event.action != 'closed'
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v6

- name: "Set up Python"
uses: actions/setup-python@v6
with:
python-version-file: "pyproject.toml"

- name: Install uv
uses: astral-sh/setup-uv@v7

- name: Sync dependencies
run: uv sync

- name: Build site
run: uv run zensical build --clean

- name: Deploy PR preview
if: github.event_name == 'pull_request'
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: site
destination_dir: pr-${{ github.event.pull_request.number }}

- name: Comment PR with preview URL
if: github.event_name == 'pull_request'
uses: actions/github-script@v7
with:
script: |
const pr = context.payload.pull_request.number;
const { owner, repo } = context.repo;
const url = `https://ff4j.github.io/docs/pr-${pr}/`;
await github.rest.issues.createComment({
owner,
repo,
issue_number: pr,
body: `📘 **Site preview available**:\n\n${url}`
});
Comment on lines +55 to +62
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
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,
});
}

Copilot uses AI. Check for mistakes.
- name: Upload Pages artifact
if: github.event_name == 'push'
uses: actions/upload-pages-artifact@v3
with:
path: site

publish:
if: github.event_name == 'push'
runs-on: ubuntu-latest
needs: build
environment:
name: github-pages
steps:
- name: Deploy to GitHub Pages
Comment on lines +74 to +76
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
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

Copilot uses AI. Check for mistakes.
uses: actions/deploy-pages@v4

cleanup:
if: github.event_name == 'pull_request' &&
github.event.action == 'closed' &&
github.event.pull_request.merged == false
Comment on lines +80 to +82
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
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'

Copilot uses AI. Check for mistakes.
runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v6
- name: Checkout gh-pages branch
uses: actions/checkout@v4
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
uses: actions/checkout@v4
uses: actions/checkout@v6

Copilot uses AI. Check for mistakes.
with:
ref: gh-pages

- 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
Comment on lines +91 to +99
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
- 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 }}"

Copilot uses AI. Check for mistakes.
git push