ci: release process with changelog

[auricom]

Overview

[github-actions]

The latest Buf updates on your PR. Results from workflow CI / buf-check (pull_request).

Build	Format	Lint	Breaking	Updated (UTC)
✅ passed	⏩ skipped	✅ passed	✅ passed	Jan 19, 2026, 2:51 PM

[claude]

Claude finished @auricom's task in 2m 17s —— View job

---

Code Review Complete ✅

I've performed a comprehensive review of the release workflow and documentation changes. Here are my findings:

---

🎯 Overall Assessment

This PR introduces a solid automated release workflow with good documentation. The workflow handles Docker image releases with changelog generation, and the RELEASE.md provides comprehensive guidance. However, there are several important issues to address before this is production-ready.

---

🔴 Critical Issues

1. Missing git-cliff Configuration (.github/workflows/release.yml:33)

The workflow uses git cliff --unreleased --strip all but there's no cliff.toml configuration file in the repository. This will cause the workflow to fail or produce unpredictable output.

Impact: Workflow will fail or generate incorrect changelogs.

Recommendation: Add a .cliff.toml configuration file. Example minimal config:

[changelog]
header = """
# Changelog\n
"""
body = """
{% for group, commits in commits | group_by(attribute="group") %}
    ### {{ group | upper_first }}
    {% for commit in commits %}
        - {{ commit.message | upper_first }}\
    {% endfor %}
{% endfor %}
"""

[git]
conventional_commits = true
filter_unconventional = true
commit_parsers = [
    { message = "^feat", group = "Features"},
    { message = "^fix", group = "Bug Fixes"},
    { message = "^doc", group = "Documentation"},
    { message = "^perf", group = "Performance"},
    { message = "^refactor", group = "Refactor"},
    { message = "^style", group = "Styling"},
    { message = "^test", group = "Testing"},
    { message = "^chore", skip = true},
]

Fix this →

---

2. Logic Error in Changelog File Handling (.github/workflows/release.yml:60-64)

if [ -f "CHANGELOG.md" ]; then
  # Add generated changelog to CHANGELOG_RELEASE_NOTES.md
  cat RELEASE_CHANGELOG.md >> CHANGELOG_RELEASE_NOTES.md
  echo "Changelog prepared for release: $TAG" >> CHANGELOG_RELEASE_NOTES.md
fi

Problems:

• Creates CHANGELOG_RELEASE_NOTES.md but never adds it to the commit
• The condition checks for CHANGELOG.md but doesn't use it
• The generated file is not referenced anywhere else in the workflow
• The commit at line 67 uses git add -A, which would stage this file but it's unclear why it's created

Expected behavior (based on RELEASE.md): The workflow should either:

1. Update CHANGELOG.md with the new release section, OR
2. Just use the generated changelog for the GitHub Release (not commit it)

Recommendation: Clarify the intent. If the goal is to update CHANGELOG.md:

if [ -f "CHANGELOG.md" ]; then
  # Prepend the new release to CHANGELOG.md
  echo -e "## [$TAG] - $(date +%Y-%m-%d)\n" > temp_changelog.md
  cat RELEASE_CHANGELOG.md >> temp_changelog.md
  echo -e "\n" >> temp_changelog.md
  cat CHANGELOG.md >> temp_changelog.md
  mv temp_changelog.md CHANGELOG.md
fi

Fix this →

---

3. Hardcoded GitHub Token in Environment (.github/workflows/release.yml:208)

env:
  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

While GITHUB_TOKEN is a default secret, this is redundant as softprops/action-gh-release@v2 automatically uses GITHUB_TOKEN from the context. However, this isn't a security issue, just unnecessary.

Recommendation: Remove the env block as it's redundant.

---

⚠️ High Priority Issues

4. No Validation of Dockerfile Context (.github/workflows/release.yml:154)

The workflow uses context: . (repository root) for Docker builds but doesn't validate that the Dockerfile is designed to work with a root context. Many Dockerfiles expect to be built from their own directory.

Recommendation: Add context validation or document the requirement:

- name: Validate Dockerfile context
  run: |
    DOCKERFILE="${{ needs.parse-tag.outputs.dockerfile }}"
    # Check if Dockerfile uses COPY with paths that require root context
    if grep -q "COPY \.\." "$DOCKERFILE"; then
      echo "::warning::Dockerfile may not work with root context"
    fi

---

5. Missing Error Handling in Bash Scripts

The bash scripts in the workflow don't use set -euo pipefail, which means errors might be silently ignored.

Recommendation: Add error handling to all bash script blocks:

- name: Generate changelog
  id: cliff
  run: |
    set -euo pipefail
    # ... rest of script

---

6. Race Condition in Branch Creation (.github/workflows/release.yml:77)

If two tags are pushed simultaneously (e.g., evm/v0.2.0 and testapp/v1.0.0), the branch push at line 77 could fail if another job is pushing at the same time. The workflow doesn't handle this gracefully.

Recommendation: Add retry logic or handle the race condition:

# Push the branch with retry
for i in {1..3}; do
  if git push origin "$BRANCH_NAME"; then
    break
  fi
  echo "Push failed, retrying in 5s..."
  sleep 5
done

---

🟡 Medium Priority Issues

7. Incomplete Documentation in RELEASE.md

Line 32: "Generates changelog from ./CHANGELOG.md using git-cliff"

This is misleading. Based on the workflow code (line 33), git cliff --unreleased --strip all generates the changelog from commit history, not from CHANGELOG.md file content. The flag --unreleased means it processes commits since the last tag.

Correction needed in RELEASE.md:

- Generates changelog from commit history (since last tag) using [git-cliff](https://github.com/orhun/git-cliff)
- The generated changelog should follow the format established in `./CHANGELOG.md`

---

8. Inconsistent Documentation About CHANGELOG.md Purpose (RELEASE.md:67-89)

The documentation states:

• Line 68: "Source of Truth: GitHub Releases"
• Line 69: "Base Document: ./CHANGELOG.md"
• Line 75: "When you push a tag, the workflow reads ./CHANGELOG.md"

But the workflow actually reads git commit history, not the CHANGELOG.md file. The CHANGELOG.md appears to be a manually maintained file that should be kept in sync, but it's not the source for the automated workflow.

Recommendation: Clarify the relationship:

- **Source of Truth**: GitHub Releases (manually curated after automation)
- **Automation Input**: Git commit history (via git-cliff)
- **Manual Reference**: `./CHANGELOG.md` (maintained separately for documentation)

---

9. Missing Tested Upgrade Paths in Automation (RELEASE.md:139, 176)

The documentation emphasizes documenting "Tested Upgrade Paths" but the workflow doesn't extract or validate this information from CHANGELOG.md. This is purely a manual step, which is fine, but should be clearer.

Recommendation: Add a note in the workflow that this is a manual step:

- [ ] Document **Tested Upgrade Paths** from your E2E test runs (not automated)

---

10. No Validation of Tag Format Before Expensive Operations (.github/workflows/release.yml:5)

The workflow trigger uses **/v*.*.* which is broad. The validation happens in the parse-tag job (line 96), but by that time, the generate-changelog job has already run (they run in parallel). This wastes resources on invalid tags.

Recommendation: Add a validation job that runs first, or make parse-tag run before generate-changelog.

---

11. Misleading Job Dependency (.github/workflows/release.yml:164)

create-github-release:
  needs: [generate-changelog, parse-tag, build-and-push]

The release creation waits for the Docker build to complete. If the Docker build fails (which can happen for reasons unrelated to the release notes), the GitHub Release isn't created. This might not be the desired behavior.

Recommendation: Consider if the release should be created even if Docker build fails, with a note about the failure.

---

🔵 Low Priority / Improvements

12. Workflow Could Use Reusable Workflows

The release workflow could be split into reusable components:

• Changelog generation
• Docker building
• Release creation

This would improve maintainability and allow other workflows to reuse these components.

---

13. Missing Job Summaries

The workflow doesn't use $GITHUB_STEP_SUMMARY to provide rich summaries in the Actions UI. Adding summaries would improve UX.

Example:

- name: Generate Summary
  run: |
    echo "## Release Summary" >> $GITHUB_STEP_SUMMARY
    echo "- Tag: ${{ github.ref_name }}" >> $GITHUB_STEP_SUMMARY
    echo "- Release Branch: ${{ steps.create-branch.outputs.branch-name }}" >> $GITHUB_STEP_SUMMARY

---

14. Permissions Could Be More Granular (.github/workflows/release.yml:7)

Top-level permissions: {} is good, but each job grants contents: write. The build-and-push job also needs packages: write, which is correct. Consider if contents: write is needed for all jobs.

---

15. Docker Build Platforms (.github/workflows/release.yml:157)

platforms: linux/amd64,linux/arm64 is good for broad compatibility, but significantly increases build time. Consider if both are needed or if arm64 could be optional for some apps.

---

16. No Changelog Validation

The workflow generates a changelog but doesn't validate its content. If git-cliff fails or produces empty output, the release will have an empty changelog.

Recommendation: Add validation:

if [ ! -s RELEASE_CHANGELOG.md ]; then
  echo "::error::Generated changelog is empty"
  exit 1
fi

---

17. RELEASE.md Line Length

Some lines exceed 100 characters (e.g., lines 30-36). While not critical, breaking these improves readability.

---

✅ What's Done Well

1. Security:

   • Minimal permissions at job level ✓
   • Uses pinned action versions with SHA (v6, v3, v2) ✓
   • No hardcoded credentials ✓
   • GITHUB_TOKEN properly scoped ✓

2. Workflow Design:

   • Good job separation with clear responsibilities ✓
   • Proper use of job outputs for data passing ✓
   • Draft releases prevent accidental publishing ✓
   • Multi-architecture Docker builds ✓

3. Documentation:

   • Comprehensive RELEASE.md covering multiple scenarios ✓
   • Clear examples and templates ✓
   • Good troubleshooting section ✓
   • Helpful checklists ✓

4. Git Practices:

   • Fetch depth 0 for full history (needed for changelog) ✓
   • Proper git config for bot commits ✓
   • Release branches for review ✓

---

📋 Recommended Action Items

Before merging:

1. ✅ Add .cliff.toml configuration file (Critical)
2. ✅ Fix the changelog file handling logic in lines 60-64 (Critical)
3. ✅ Add set -euo pipefail to all bash scripts (High)
4. ✅ Fix documentation about CHANGELOG.md vs commit history (High)
5. ✅ Add validation for empty changelog output (Medium)

Post-merge improvements:

6. Add retry logic for branch push race conditions
7. Add Dockerfile context validation
8. Improve job dependencies (consider decoupling release from Docker build)
9. Add GitHub Step Summaries for better UX
10. Consider splitting into reusable workflows

---

📊 Code Quality Metrics

• Correctness: 6/10 (critical logic errors)
• Security: 9/10 (well-scoped permissions, good practices)
• Documentation: 7/10 (comprehensive but has inaccuracies)
• Maintainability: 7/10 (could use more modularization)
• Testing: 4/10 (no validation of generated outputs)

Overall: This is a good foundation but needs critical fixes before production use.

---

[gemini-code-assist]

Summary of Changes

Hello @auricom, I'm Gemini Code Assist¹! 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

• Support Policy Definition: A new section clearly outlines the version support policy, specifying support for the current and previous major versions with security and critical bug fixes.
• Comprehensive Release Workflow: Detailed automated and manual steps for the release process are introduced, covering everything from tag pushes and automated changelog generation to manual review, GitHub Release publication, and public announcements.
• Structured Changelog Management: New guidelines for maintaining CHANGELOG.md are added, including a specific format, content categories (e.g., Added, Changed, Fixed, Security, Tested Upgrades), and the use of git-cliff for automated generation.
• Clear Communication Protocols: Templates and instructions are provided for consistent release announcements on GitHub, Slack, and Telegram, ensuring stakeholders are well-informed.
• Enhanced Release Scenarios & Checklists: The document now includes updated examples for various release scenarios (single app, multiple apps, Go modules, hotfixes) and a comprehensive checklist template to ensure all release steps are followed.
• Tested Upgrade Paths Emphasis: A new requirement and dedicated section highlight the importance of documenting tested upgrade paths within the changelog, improving clarity for users.

🧠 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

• Ignored by pattern: .github/workflows/** (1)
  • .github/workflows/release.yml

Using Gemini Code Assist

The 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 /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

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 .gemini/ folder in the base of the repository. Detailed instructions can be found here.

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

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

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.

[gemini-code-assist]

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.

[gemini-code-assist]

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.

Suggested change

	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: