ci: release process with changelog #2998
Conversation
|
The latest Buf updates on your PR. Results from workflow CI / buf-check (pull_request).
|
|
Claude finished @auricom's task in 2m 10s —— View job Code Review Complete ✅I've reviewed the release process implementation. This is a comprehensive addition that significantly improves the release workflow for ev-node. Below is my detailed feedback organized by priority and category. Critical Issues1. Security: Unpinned GitHub Actions (High Priority)Location: Three third-party actions are using mutable tags instead of pinned commit SHAs: # Line 79
uses: anthropics/claude-code-action@v1
# Line 252
uses: softprops/action-gh-release@v2Risk: Mutable tags can be updated by action maintainers, potentially introducing malicious code or breaking changes without your knowledge. Recommendation: Pin to specific commit SHAs: uses: anthropics/claude-code-action@<commit-sha> # Pin v1 to specific SHA
uses: softprops/action-gh-release@<commit-sha> # Pin v2 to specific SHA2. Missing git-cliff ConfigurationLocation: The documentation references
Issues:
Recommendation: Either:
High Priority Issues3. Tag Validation Regex Too PermissiveLocation: if [[ ! "$CURRENT_TAG" =~ ^[a-zA-Z0-9/_.-]+$ ]]; then
echo "::error::Invalid tag format: $CURRENT_TAG"
exit 1
fiIssues:
Recommendation: Use stricter validation matching the documented format: # Validate format: app-name/vX.Y.Z
if [[ ! "$CURRENT_TAG" =~ ^[a-z0-9/-]+/v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
echo "::error::Invalid tag format: $CURRENT_TAG (expected: app-name/vX.Y.Z)"
exit 1
fi4. Error Handling Gaps in Shell ScriptsLocation: Several bash steps lack robust error handling: Line 43-56: Git diff generation has no error checking git diff --stat "$PREV_TAG"..HEAD > git-diff-stats.txt
git log --oneline "$PREV_TAG"..HEAD > git-commits.txt
git diff "$PREV_TAG"..HEAD > git-full-diff.txt
# No validation that these commands succeededLine 132-162: Branch creation assumes git operations succeed git checkout -b "$BRANCH_NAME"
# No check if branch already exists or checkout failedRecommendation: Add error checking: set -euo pipefail # At the start of each script
# Check command results
if ! git diff --stat "$PREV_TAG"..HEAD > git-diff-stats.txt; then
echo "::error::Failed to generate diff stats"
exit 1
fi5. Potential Command Injection in Branch NamesLocation: TAG="${{ github.ref_name }}"
BRANCH_NAME="release/$TAG"
git checkout -b "$BRANCH_NAME"Risk: While Recommendation: Sanitize the branch name: # Sanitize tag name for branch creation
SAFE_TAG=$(echo "$TAG" | tr -cd 'a-zA-Z0-9/._-')
BRANCH_NAME="release/$SAFE_TAG"Medium Priority Issues6. Documentation Clarity: Release Branch Lifecycle UnclearLocation: The documentation mentions release branches in multiple places but is inconsistent about their lifecycle:
Issues:
This matches Gemini's feedback - the lifecycle and purpose need clarification. Recommendation: Add a clear section explaining: ### Release Branch Lifecycle
The `release/<tag-name>` branch serves as a staging area for changelog refinement:
1. **Created automatically** by the workflow from the tagged commit
2. **Edit the changelog** on this branch if needed
3. **Two options after publishing the GitHub Release:**
- **Merge to main** to keep the refined changelog in the repository, OR
- **Delete the branch** if you updated the GitHub Release directly
4. **Do not merge to version branches** - these are temporary staging branches7. CHANGELOG.md Update Process Needs ClarificationLocation: The documentation says the workflow "reads CHANGELOG.md" and "generates release notes," but:
Recommendation: Clarify the pre-release manual steps: ### Before Tagging a Release
1. **Update `./CHANGELOG.md`** manually:
- Move items from `[Unreleased]` to a new version section
- Add tested upgrade paths
- Commit and push to main
2. **Create and push the tag** (automation takes over from here)8. Missing Rollback/Cleanup Instructions for Failed ReleasesLocation: The troubleshooting section covers validation errors but doesn't address:
Recommendation: Add a "Failed Release Cleanup" section: ### Failed Release Cleanup
If the release workflow fails:
1. Check workflow logs to identify the failure point
2. Delete the failed tag: `git push origin :refs/tags/app/v0.2.0`
3. Delete the release branch: `git push origin :refs/heads/release/app/v0.2.0`
4. Fix the underlying issue
5. Re-tag and push again9. Workflow Permissions Could Be More RestrictiveLocation: Top-level permissions are empty ( Current: generate-changelog:
permissions:
contents: write # Allows all git write operationsRecommendation: Consider if more restrictive permissions are possible. GitHub's Low Priority / Nice-to-Have10. Hardcoded Multi-line Output DelimitersLocation: Uses generic delimiters like Recommendation: Use random delimiters: DELIMITER="EOF_$(openssl rand -hex 8)"
{
echo "commits<<$DELIMITER"
cat git-commits.txt
echo "$DELIMITER"
} >> $GITHUB_OUTPUT11. No Timeout for Claude AI StepLocation: The Claude AI changelog generation has no timeout, which could hang the workflow. Recommendation: Add a timeout: - name: Generate changelog with Claude
timeout-minutes: 5
id: claude
uses: anthropics/claude-code-action@v112. Docker Build Missing Cache ConfigurationLocation: The Docker build doesn't configure layer caching, which could slow down builds. Recommendation: Add cache configuration: - name: Build and push Docker image
uses: docker/build-push-action@v6
with:
cache-from: type=registry,ref=ghcr.io/${{ github.repository_owner }}/${{ needs.parse-tag.outputs.image-name }}:buildcache
cache-to: type=registry,ref=ghcr.io/${{ github.repository_owner }}/${{ needs.parse-tag.outputs.image-name }}:buildcache,mode=max13. Missing Validation for CHANGELOG.md ExistenceLocation: if [ -f "CHANGELOG.md" ]; then
# Add generated changelog
fiThe workflow silently continues if CHANGELOG.md doesn't exist. Since the documentation emphasizes CHANGELOG.md as critical, this should fail loudly. Recommendation: if [ ! -f "CHANGELOG.md" ]; then
echo "::error::CHANGELOG.md not found - required for releases"
exit 1
fiPositive Highlights✅ Excellent documentation structure - RELEASE.md is comprehensive and well-organized SummaryThis PR introduces a solid foundation for automated releases. The main concerns are:
The documentation is comprehensive and the workflow design is sound. With the security and clarity issues addressed, this will significantly improve the release process. Tasks
|
Summary of ChangesHello @auricom, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly overhauls the project's release documentation by introducing a structured and comprehensive release process. It defines clear version support policies, details both automated and manual steps for creating and publishing releases, and establishes robust guidelines for changelog management and external communication. The changes aim to standardize release procedures, enhance transparency, and provide a clearer understanding of release content and upgrade compatibility for users and contributors. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Ignored Files
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![github-advanced-security[bot]](https://d.iamgay.cn/https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| contents: write | ||
| steps: | ||
| - name: Create GitHub Release | ||
| uses: softprops/action-gh-release@v2 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
![gemini-code-assist[bot]](https://d.iamgay.cn/https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive and well-documented release process, including changelog management and automated workflows. The changes are primarily in RELEASE.md and provide detailed steps for both Docker image and Go module releases. My review focuses on improving the clarity of the new process. I've suggested clarifying the manual steps required before tagging a release and detailing the lifecycle of the temporary release branches created by the automation. Overall, this is a great step towards standardizing the release workflow.
| 1. 📝 Review the release branch `release/<tag-name>` | ||
| 2. 📝 Edit and refine the generated changelog if needed | ||
| 3. 📝 Add **recommended upgrade priority** (Critical/High/Medium/Low) | ||
| 4. 📝 Add **general description** of the release | ||
| 5. 📝 Ensure **tested upgrade paths** are documented (1-2 lines in changelog) | ||
| 6. ✅ Merge the release branch or update the GitHub Release directly |
There was a problem hiding this comment.
The process for refining the changelog could be clarified. The 'Quick Steps' (lines 254-258) show editing and pushing to the release/<tag-name> branch. However, it's not clear how these committed changes are then reflected in the final GitHub Release. Does the developer need to manually copy the refined changelog from the branch to the GitHub Release draft?
Additionally, step 6 here says 'Merge the release branch...'. It would be helpful to specify the merge target for this branch (e.g., a version branch like v0.3), or confirm if it should be discarded after the release is published (as suggested on line 666). Clarifying the lifecycle and purpose of the release/<tag-name> branch would prevent confusion.
|
|
||
| ### Changelog Workflow | ||
|
|
||
| The release workflow automatically generates changelogs from `./CHANGELOG.md`: |
There was a problem hiding this comment.
To improve clarity, it would be helpful to explicitly state that CHANGELOG.md needs to be manually updated before the automated workflow is triggered by a tag push. This involves moving changes from [Unreleased] to a new version section. While this is mentioned in other parts of the document (e.g., line 246), adding it here would make the Changelog Workflow section self-contained and easier to follow.
| The release workflow automatically generates changelogs from `./CHANGELOG.md`: | |
| The release workflow starts with a manual update to `./CHANGELOG.md`, after which automation takes over: |
| - name: Generate changelog with Claude | ||
| id: claude | ||
| uses: anthropics/claude-code-action@v1 |
Check warning
Code scanning / CodeQL
Unpinned tag for a non-immutable Action in workflow Medium
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #2998 +/- ##
==========================================
- Coverage 59.25% 58.52% -0.73%
==========================================
Files 106 111 +5
Lines 10023 10405 +382
==========================================
+ Hits 5939 6090 +151
- Misses 3456 3670 +214
- Partials 628 645 +17
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Overview