ci: automate release via GitHub Actions

.codebuddy/rules/versioning.mdc

@@ -1,6 +1,6 @@
 ---
 description: Version numbering and release process rules. Apply when releasing versions, creating tags, or updating changelogs.
-globs: "**/CHANGELOG*.md,**/version.go,Makefile"
+globs: "**/CHANGELOG*.md,**/version.go,Makefile,.github/workflows/release.yml"
 ---
 
 # Versioning Rules
@@ -26,17 +26,31 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/).
 1. Tags MUST start with `v` prefix
 2. Tags MUST be annotated tags (not lightweight)
 3. Tag message should summarize the release
+4. Tags are created **automatically by GitHub Actions** when a `release/*` branch PR is merged into `main`
+
+## Branch Protection
+
+The `main` branch is protected and only accepts changes via Pull Requests. Direct pushes to `main` are not allowed.
+
+## Release Workflow
+
+1. Create a `release/vX.Y.Z` branch from `main`
+2. Update CHANGELOG files and any other release-related changes on the release branch
+3. Push the release branch and create a PR to `main`
+4. After PR review and merge, GitHub Actions automatically creates the annotated tag and GitHub Release
 
 ## Release Checklist
 
-Before creating a release tag:
+Before merging the release PR:
 
 1. [ ] All tests pass
 2. [ ] CHANGELOG.md updated with new version section
 3. [ ] CHANGELOG-zh.md updated (bilingual sync)
 4. [ ] Version moved from `[Unreleased]` to `[x.y.z] - YYYY-MM-DD`
 5. [ ] README.md updated if needed
 6. [ ] README-zh.md updated (bilingual sync)
+7. [ ] Release branch named `release/vX.Y.Z`
+8. [ ] PR title follows format: `chore: release vX.Y.Z`
 
 ## CHANGELOG Update Process
 

.codebuddy/skills/release/SKILL.md

@@ -1,16 +1,16 @@
 ---
 name: release
-description: This skill automates the version release process including changelog generation, git tagging, and bilingual documentation updates. Use this skill when the user wants to create a new release, bump version, generate changelog, or tag a new version.
+description: This skill automates the version release process including changelog generation and bilingual documentation updates via release branch workflow. Tags are created automatically by GitHub Actions after the release PR is merged. Use this skill when the user wants to create a new release, bump version, generate changelog, or prepare a release PR.
 ---
 
 # Release Automation Skill
 
-This skill handles the complete release workflow for this Go CLI project, ensuring bilingual documentation stays in sync.
+This skill handles the complete release workflow for this Go CLI project, ensuring bilingual documentation stays in sync. The `main` branch is protected and only accepts changes via Pull Requests. Tags are created automatically by GitHub Actions.
 
 ## When to Use
 
 - User requests to "release a new version"
-- User wants to "bump version" or "create a tag"
+- User wants to "bump version" or "prepare a release"
 - User asks to "generate changelog" or "update changelog"
 - User mentions "prepare release" or "cut a release"
 
@@ -63,7 +63,18 @@ git describe --tags --abbrev=0 2>/dev/null || echo "v0.0.0"
 | v0.0.1 | minor | v0.1.0 |
 | v0.0.1 | major | v1.0.0 |
 
-### Step 2: Gather Changes
+### Step 2: Create Release Branch
+
+Create a release branch from the latest `main`:
+
+```bash
+git checkout main && git pull origin main
+git checkout -b release/vX.Y.Z
+```
+
+**Important**: The branch MUST be named `release/vX.Y.Z` (e.g., `release/v0.1.3`). The GitHub Actions workflow extracts the version from this branch name.
+
+### Step 3: Gather Changes
 
 Collect commits since last tag:
 
@@ -78,9 +89,9 @@ Categorize commits into:
 - **Fixed**: Bug fixes (commits with "fix:", "bug:", "patch:")
 - **Removed**: Removals (commits with "remove:", "delete:", "deprecate:")
 
-### Step 3: Update CHANGELOG Files
+### Step 4: Update CHANGELOG Files
 
-Update both `CHANGELOG.md` and `CHANGELOG-zh.md` simultaneously.
+Update both `CHANGELOG.md` and `CHANGELOG-zh.md` simultaneously on the release branch.
 
 #### English CHANGELOG.md Format
 
@@ -130,35 +141,50 @@ All notable changes to this project will be documented in this file.
 - 移除描述
 ```
 
-### Step 4: Create Git Tag
+### Step 5: Commit and Push Release Branch
 
-After changelog updates are committed:
+```bash
+git add -A
+git commit -m "chore: release vX.Y.Z"
+git push origin release/vX.Y.Z
+```
+
+### Step 6: Create Pull Request
+
+Create a PR from `release/vX.Y.Z` to `main`:
+
+- **Title**: `chore: release vX.Y.Z`
+- **Description**: Include the changelog entries for this version
+
+If `gh` CLI is available:
 
 ```bash
-# Create annotated tag
-git tag -a vX.Y.Z -m "Release vX.Y.Z"
+gh pr create --base main --head release/vX.Y.Z \
+  --title "chore: release vX.Y.Z" \
+  --body "## Release vX.Y.Z
 
-# Show tag info
-git show vX.Y.Z
+<paste changelog entries here>"
 ```
 
-### Step 5: Verification Checklist
+### Step 7: Verification Checklist
 
-Before finalizing, verify:
+Before merging the PR, verify:
 
 1. [ ] CHANGELOG.md has new version section
 2. [ ] CHANGELOG-zh.md has matching Chinese version
 3. [ ] Both changelogs have same structure and content
-4. [ ] Git tag created with correct version
-5. [ ] Tag message is descriptive
+4. [ ] Release branch named `release/vX.Y.Z`
+5. [ ] PR title follows format: `chore: release vX.Y.Z`
+6. [ ] All CI checks pass
 
-### Step 6: Push (Optional)
+### Step 8: After PR Merge (Automatic)
 
-If user confirms, push tag to remote:
+Once the PR is merged into `main`, GitHub Actions will automatically:
 
-```bash
-git push origin vX.Y.Z
-```
+1. Create an annotated tag `vX.Y.Z` on the merge commit
+2. Create a GitHub Release with auto-generated release notes
+
+**No manual tag creation or pushing is needed.**
 
 ## Section Header Translations
 
@@ -192,6 +218,6 @@ This skill recognizes conventional commit prefixes:
 - If no tags exist, start from v0.0.1-alpha
 - If CHANGELOG files don't exist, create them with proper headers
 - Always create both language versions together
-- Never push tags without user confirmation
 - For pre-release versions, increment the numeric suffix (alpha.1 → alpha.2)
 - When transitioning phases (alpha → beta), reset the suffix
+- If `gh` CLI is not available, instruct user to create PR via GitHub web UI

.github/workflows/release.yml

@@ -0,0 +1,54 @@
+name: Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    # Only run when a release/* branch PR is merged (not just closed)
+    if: >-
+      github.event.pull_request.merged == true &&
+      startsWith(github.event.pull_request.head.ref, 'release/')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Extract version from branch name
+        id: version
+        run: |
+          BRANCH="${{ github.event.pull_request.head.ref }}"
+          VERSION="${BRANCH#release/}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Extracted version: $VERSION"
+
+      - name: Validate version format
+        run: |
+          VERSION="${{ steps.version.outputs.version }}"
+          if [[ ! "$VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z]+(\.[0-9]+)?)?$ ]]; then
+            echo "Error: Invalid version format '$VERSION'"
+            echo "Expected format: vX.Y.Z or vX.Y.Z-pre.N"
+            exit 1
+          fi
+
+      - name: Create annotated tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "${{ steps.version.outputs.version }}" \
+            -m "Release ${{ steps.version.outputs.version }}"
+          git push origin "${{ steps.version.outputs.version }}"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.version.outputs.version }}
+          name: ${{ steps.version.outputs.version }}
+          generate_release_notes: true