ref(ci): Open a PR before releasing a new version

.github/workflows/docker-build.yml

@@ -7,6 +7,10 @@ on:
         description: "Docker image (e.g. docker.io/<org>/<repo>)"
         type: string
         required: true
+      checkout_ref:
+        description: "Git ref (branch, SHA, or tag) to check out"
+        type: string
+        required: false
       file:
         description: "Path to Dockerfile relative to the repository root"
         type: string
@@ -36,7 +40,14 @@ jobs:
     name: Build Docker Image
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
+      - name: Checkout (specific ref)
+        if: inputs.checkout_ref != ''
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ inputs.checkout_ref }}
+
+      - name: Checkout (default)
+        if: inputs.checkout_ref == ''
         uses: actions/checkout@v4
 
       - name: Set up Docker Buildx

.github/workflows/prepare-release.yml

@@ -18,6 +18,7 @@ on:
 
 permissions:
   contents: write
+  pull-requests: write
 
 jobs:
   prepare-release:
@@ -65,16 +66,21 @@ jobs:
           # and prepend it to the existing changelog.
           git cliff --config cliff.toml --tag "v${NEXT_VERSION}" --unreleased --prepend CHANGELOG.md
 
-      - name: Commit and Tag Release
-        env:
-          NEXT_VERSION: ${{ steps.ver.outputs.next }}
-        run: |
-          set -euo pipefail
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git add .
-          git commit -m "chore(release): v${NEXT_VERSION}"
-          git tag -a "v${NEXT_VERSION}" -m "Release v${NEXT_VERSION}"
-          # Push to main and tags; assume release is performed from main.
-          git push origin HEAD:main
-          git push origin --tags
+      - name: Create Release Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: chore(release): v${{ steps.ver.outputs.next }}
+          title: chore(release): v${{ steps.ver.outputs.next }}
+          body: |
+            This PR prepares release v${{ steps.ver.outputs.next }}.
+
+            - Bumps workspace versions.
+            - Updates CHANGELOG.md with unreleased changes.
+
+            Merging this PR into `main` will trigger the release workflow which tags the commit, publishes Docker images, and creates the GitHub Release.
+          branch: release/v${{ steps.ver.outputs.next }}
+          base: main
+          labels: |
+            release
+            automated
+          delete-branch: true

.github/workflows/release.yml

@@ -5,9 +5,9 @@ concurrency:
   cancel-in-progress: false
 
 on:
-  push:
-    tags:
-      - 'v*'
+  pull_request:
+    types: [closed]
+    branches: [main]
   workflow_dispatch:
     inputs:
       version:
@@ -22,9 +22,17 @@ jobs:
   version:
     name: Determine Version
     runs-on: ubuntu-latest
+    # Gate: manual dispatch OR merged PRs labeled 'release'.
+    if: |
+      github.event_name == 'workflow_dispatch' || (
+        github.event_name == 'pull_request' &&
+        github.event.pull_request.merged == true &&
+        contains(github.event.pull_request.labels.*.name, 'release')
+      )
     outputs:
       tag: ${{ steps.ver.outputs.tag }}
       version: ${{ steps.ver.outputs.version }}
+      is_pr_merge: ${{ steps.ver.outputs.is_pr_merge }}
     steps:
       - name: Extract Tag and Version
         id: ver
@@ -34,9 +42,18 @@ jobs:
           if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
             RAW="${{ inputs.version }}"
             TAG="v${RAW#v}"
+            PR_MERGE=false
           else
-            TAG="${GITHUB_REF_NAME}"
-            RAW="${TAG#v}"
+            # pull_request closed event (merged into main)
+            HEAD_REF="${{ github.event.pull_request.head.ref }}"
+            if [[ "$HEAD_REF" =~ ^release/v([0-9]+\.[0-9]+\.[0-9]+)$ ]]; then
+              RAW="${BASH_REMATCH[1]}"
+            else
+              echo "Failed to extract version from PR branch name: $HEAD_REF (expected release/vX.Y.Z)" >&2
+              exit 1
+            fi
+            TAG="v${RAW}"
+            PR_MERGE="${{ github.event.pull_request.merged }}"
           fi
           CLEANED="${RAW#v}"
           if [[ ! "$CLEANED" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
@@ -45,10 +62,45 @@ jobs:
           fi
           echo "tag=${TAG}" >> "$GITHUB_OUTPUT"
           echo "version=${CLEANED}" >> "$GITHUB_OUTPUT"
+          echo "is_pr_merge=${PR_MERGE}" >> "$GITHUB_OUTPUT"
+
+  create-tag:
+    name: Create Tag
+    needs: version
+    if: needs.version.outputs.is_pr_merge == 'true' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout merge commit (PR merge)
+        if: github.event_name == 'pull_request'
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.merge_commit_sha }}
+
+      - name: Checkout main (manual dispatch)
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/checkout@v4
+
+      - name: Create and Push Tag
+        shell: bash
+        env:
+          TAG: ${{ needs.version.outputs.tag }}
+        run: |
+          set -euo pipefail
+          git fetch --tags
+          if git rev-parse "$TAG" >/dev/null 2>&1; then
+            echo "Tag $TAG already exists; skipping creation."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git tag -a "$TAG" -m "Release $TAG"
+          git push origin "$TAG"
 
   build-and-push:
     name: Build and Push Docker Images
-    needs: version
+    needs: [version, create-tag]
     strategy:
       matrix:
         image: [etl-api, etl-replicator]
@@ -60,11 +112,12 @@ jobs:
       push: true
       tag_with_version: true
       version: ${{ needs.version.outputs.version }}
+      checkout_ref: refs/tags/${{ needs.version.outputs.tag }}
     secrets: inherit
 
   github-release:
     name: Create GitHub Release
-    needs: [version, build-and-push]
+    needs: [version, create-tag, build-and-push]
     runs-on: ubuntu-latest
     steps:
       - name: Generate Release Notes