Improve CI workflows for docs and publishing #187
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #187 +/- ##
=======================================
Coverage 89.23% 89.23%
=======================================
Files 14 14
Lines 2007 2007
=======================================
Hits 1791 1791
Misses 216 216 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@coderabbitai review |
✅ Actions performedReview triggered.
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughRefactors GitHub Actions workflows to modernize tooling and deployment orchestration. The documentation workflow restructures into separate build and deploy jobs with artifact-based deployment paths. The publish workflow replaces direct tool invocations with UV-based execution and introduces automated changelog generation from release notes. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Suggested labels
Suggested reviewers
Poem
Pre-merge checks and finishing touches✅ Passed checks (3 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (3)
.github/workflows/publish.yml (1)
65-88: CRITICAL: CHANGELOG updates won't reach main due to detached HEAD state.The workflow commits CHANGELOG changes while on a detached HEAD (at the release tag), then attempts
git push origin main || true. Since no localmainbranch exists at this point, the push is silently skipped. The subsequentgit checkout main(line 106) resets the worktree, leaving CHANGELOG stale on main.This is the issue flagged in the previous review. To fix, checkout
mainbefore committing the CHANGELOG update:- - name: Commit and push CHANGELOG update - env: - TAG: ${{ steps.notes.outputs.tag }} - run: | - git config user.name github-actions - git config user.email [email protected] + - name: Commit and push CHANGELOG update + env: + TAG: ${{ steps.notes.outputs.tag }} + run: | + git config user.name github-actions + git config user.email [email protected] + git checkout main git add CHANGELOG.md # Avoid CI cycles git commit -m "Changelog: add notes for ${TAG} [skip ci]" || echo "No changelog changes to commit" git push origin main || true.github/workflows/docs-gh-pages.yml (2)
82-96: CRITICAL: deploy-preview will fail for fork PRs due to read-only token.The previous review flagged this: the
deploy-previewjob runs for all PRs, but when triggered from a fork,secrets.GITHUB_TOKENis read-only, causingpeaceiris/actions-gh-pagesto fail. This blocks documentation-only PRs from external contributors.Add a guard condition to skip deployment for fork PRs:
deploy-preview: needs: build - if: github.event_name == 'pull_request' + if: github.event_name == 'pull_request' && !github.event.pull_request.head.repo.fork runs-on: ubuntu-latest + permissions: + contents: write steps:Consider adding a separate step to post the preview URL as a comment for fork PRs (optional enhancement).
67-80: Add permissions block to deploy-main job.The job lacks an explicit permissions statement for GITHUB_TOKEN. Since this job publishes to gh-pages, add a minimal permissions block to limit token scope. This aligns with the permissions patterns used elsewhere in the project (e.g.,
publish.yml).Add permissions to this job:
deploy-main: needs: build if: github.event_name == 'push' && github.ref == 'refs/heads/main' runs-on: ubuntu-latest + permissions: + contents: write steps:Note: The
deploy-previewjob has the same issue and should also receive a permissions block.
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (2)
.github/workflows/docs-gh-pages.yml(1 hunks).github/workflows/publish.yml(2 hunks)
🧰 Additional context used
🧠 Learnings (3)
📓 Common learnings
Learnt from: CR
Repo: projectmesa/mesa-frames PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T18:41:11.772Z
Learning: In pull requests, link issues, summarize changes, note API impacts, and add/adjust tests and documentation
📚 Learning: 2025-12-08T18:41:11.772Z
Learnt from: CR
Repo: projectmesa/mesa-frames PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T18:41:11.772Z
Learning: Use `docs/` directory for MkDocs and Sphinx content for user and API documentation
Applied to files:
.github/workflows/docs-gh-pages.yml
📚 Learning: 2025-12-08T18:41:11.772Z
Learnt from: CR
Repo: projectmesa/mesa-frames PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-08T18:41:11.772Z
Learning: Preview documentation using `uv run mkdocs serve`
Applied to files:
.github/workflows/docs-gh-pages.yml
🪛 actionlint (1.7.9)
.github/workflows/publish.yml
43-43: the runner of "softprops/action-gh-release@v1" action is too old to run on GitHub Actions. update the action's version to fix this issue
(action)
.github/workflows/docs-gh-pages.yml
99-99: "github.head_ref" is potentially untrusted. avoid using it directly in inline scripts. instead, pass it through an environment variable. see https://docs.github.com/en/actions/reference/security/secure-use#good-practices-for-mitigating-script-injection-attacks for more details
(expression)
🪛 GitHub Check: CodeQL
.github/workflows/docs-gh-pages.yml
[warning] 68-82: Workflow does not contain permissions
Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{}}
[warning] 83-100: Workflow does not contain permissions
Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {{}}
🔇 Additional comments (8)
.github/workflows/publish.yml (6)
20-28: UV tooling migration looks good.The setup and version extraction are implemented correctly. The use of
uvx hatchis the correct invocation pattern via uv.
29-41: Build, test, and verification steps are correct.The UV-based commands are properly formatted. The PyPI verification flow is sound.
48-64: Changelog generation from release notes is well-structured.The script safely extracts release data from the GitHub API context with fallback to GITHUB_REF, validates the payload, and handles missing release body gracefully with a clear error message.
89-106: Version branch creation logic is sound, but depends on CHANGELOG fix.Once the CHANGELOG commit issue (lines 79-88) is resolved by checking out
mainfirst, this section will execute correctly. The version branch recreation and main checkout are appropriate.
107-121: Version bumping and commit are correct.The UV-based version commands are properly sequenced, and including CHANGELOG.md in the commit is appropriate. This assumes the main branch checkout from the CHANGELOG step completes successfully.
43-43: Update softprops/action-gh-release to latest version.Static analysis flagged
action-gh-release@v1as too old. Please verify and update to the latest stable version..github/workflows/docs-gh-pages.yml (2)
1-13: Workflow triggers are well-configured.Path-based filters appropriately constrain runs to doc changes only. The split between push (main) and pull_request (all branches) is correct.
16-66: Build job is well-structured and defensive.The job properly exports
short_shafor downstream use, defensively handles notebook conversion with globstar pattern matching, and artifacts the built site. The separation of build from deploy jobs is a good pattern improvement.
EwoutH
left a comment
EwoutH
left a comment
There was a problem hiding this comment.
Haven’t reviewed line by line, but conceptually this seems useful!
…esa-frames into split/gh-workflows
for more information, see https://pre-commit.ci
…improved compatibility
…esa-frames into split/gh-workflows
Documentation:
docs/**build once with a read-only token, upload the static site as an artifact, and a separateworkflow_rundeployer publishes togh-pagesunderpreview/{branch}/{short_sha}/. This split keeps fork PRs safe (no secrets exposed to untrusted builds) while still delivering live previews.docs/general/**/*.pyjupytext notebooks to.ipynbduring the build, so tutorials stay human-readable in git history while still rendering as notebooks.Publishing:
uvto managehatchinto CHANGELOG.mdand push tomainso release metadata stays in sync.Summary by CodeRabbit
Release Notes
✏️ Tip: You can customize this high-level summary in your review settings.