feat(ci): rework release process to make changes before tag is pushed (#917)

* chore(security): pin digest hermitcrab

* feat(ci): rework release process to make changes before tag is pushed

* fix(release): add tag latest when releasing on main

* feat(docs): add documentation for cicd release process

* fix(docs): fix documentaiton & render mermaid

* fix(ci): fix docs triggering mechanisms

* fix(ci): fix triggering of helm job

* chore(sec): pin python dependencies for docs

* fix(docs): fix styles

* fix(docs): remove mermaid rendering

* fix(uv): fix uv lock

* fix(ci): pin action digest uv

Author: Alexandre-BARBIER

.github/workflows/build-and-push.yaml

@@ -2,6 +2,15 @@ name: Build and Push
 
 on:
   workflow_call:
+    inputs:
+      version:
+        description: "Version tag for the image (e.g. v1.2.3)"
+        required: false
+        type: string
+    outputs:
+      digest:
+        description: "The published image manifest digest (sha256:...)"
+        value: ${{ jobs.merge.outputs.digest }}
 
 env:
   REGISTRY_IMAGE: ghcr.io/${{ github.repository }}
@@ -33,7 +42,11 @@ jobs:
       - name: Get Build timestamp and branch name
         run: |
           echo "BUILD_TIMESTAMP=$(date +'%s')" >> $GITHUB_ENV
-          echo "VERSION=$( echo ${{ github.head_ref || github.ref_name }} | tr '/' '-' )" >> $GITHUB_ENV
+          if [[ -n "${{ inputs.version }}" ]]; then
+            echo "VERSION=${{ inputs.version }}" >> $GITHUB_ENV
+          else
+            echo "VERSION=$( echo ${{ github.head_ref || github.ref_name }} | tr '/' '-' )" >> $GITHUB_ENV
+          fi
 
       - name: Docker tags & labels
         id: meta
@@ -46,6 +59,7 @@ jobs:
           # - type=sha,format=long,prefix= -> commit sha
           tags: |
             type=raw,${{ env.VERSION }}
+            type=raw,latest,enable=${{ github.ref == 'refs/heads/main' }}
             type=ref,event=tag
             type=sha,format=long,prefix=
 
@@ -94,6 +108,8 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - build
+    outputs:
+      digest: ${{ steps.inspect.outputs.digest }}
     steps:
       - name: Download digests
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8
@@ -107,7 +123,11 @@ jobs:
 
       - name: Get branch name
         run: |
-          echo "VERSION=$( echo ${{ github.head_ref || github.ref_name }} | tr '/' '-' )" >> $GITHUB_ENV
+          if [[ -n "${{ inputs.version }}" ]]; then
+            echo "VERSION=${{ inputs.version }}" >> $GITHUB_ENV
+          else
+            echo "VERSION=$( echo ${{ github.head_ref || github.ref_name }} | tr '/' '-' )" >> $GITHUB_ENV
+          fi
 
       - name: Docker tags & labels
         id: meta
@@ -120,6 +140,7 @@ jobs:
           # - type=sha,format=long,prefix= -> commit sha
           tags: |
             type=raw,${{ env.VERSION }}
+            type=raw,latest,enable=${{ github.ref == 'refs/heads/main' }}
             type=ref,event=tag
             type=sha,format=long,prefix=
 
@@ -138,6 +159,9 @@ jobs:
             $(printf '${{ env.REGISTRY_IMAGE }}@sha256:%s ' *)
 
       - name: Inspect image
+        id: inspect
         if: env.REGISTRY_PUSH == 'true'
         run: |
           docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }}
+          DIGEST=$(docker buildx imagetools inspect ${{ env.REGISTRY_IMAGE }}:${{ steps.meta.outputs.version }} | grep -m1 '^Digest:' | awk '{print $2}')
+          echo "digest=$DIGEST" >> $GITHUB_OUTPUT

.github/workflows/docs.yaml

@@ -1,10 +1,14 @@
 name: Documentation
 on:
+  workflow_call:
+    inputs:
+      version:
+        description: 'Version to deploy (e.g. v1.2.3)'
+        type: string
+        required: true
   push:
     branches:
       - main
-    tags:
-      - v*
   pull_request:
     branches:
       - main
@@ -22,18 +26,12 @@ jobs:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0  # Fetch all branches to include 'gh-pages' branch
-      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
+      - uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990
         with:
-          python-version: 3.x
-      - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
-        with:
-          key: mkdocs-material-${{ github.ref }}
-          path: .cache
-          restore-keys: |
-            mkdocs-material-
+          enable-cache: true
 
       - name: Install dependencies
-        run: pip install mkdocs-material mike
+        run: uv sync --frozen
 
       - name: Lint Markdown files
         uses: DavidAnson/markdownlint-cli2-action@ce4853d43830c74c1753b39f3cf40f71c2031eb9 # v23
@@ -42,7 +40,7 @@ jobs:
           globs: 'docs/**/*.md'
 
       - name: Build pages
-        run: mkdocs build --strict
+        run: uv run mkdocs build --strict
 
       - name: Configure Git user
         run: |
@@ -51,10 +49,10 @@ jobs:
 
       - name: Deploy pages (unstable)
         if: github.ref == 'refs/heads/main'
-        run: mike deploy --push --update-aliases unstable
+        run: uv run mike deploy --push --update-aliases unstable
 
       - name: Deploy pages (new release)
-        if: startsWith(github.ref, 'refs/tags/')
+        if: github.event_name == 'workflow_call'
         run: |
-          mike deploy --push --update-aliases ${{ github.ref_name }} latest
-          echo "Deployed version ${{ github.ref_name }} to GitHub Pages"
+          uv run mike deploy --push --update-aliases ${{ inputs.version }} latest
+          echo "Deployed version ${{ inputs.version }} to GitHub Pages"

.github/workflows/helm.yaml

@@ -1,18 +1,21 @@
 name: Helm CI/CD
 
 on:
+  workflow_call:
+    inputs:
+      version:
+        description: 'Version to deploy (e.g. v1.2.3)'
+        type: string
+        required: true
   push:
     branches:
       - main
-    tags:
-      - v*
   pull_request:
     branches:
       - main
     paths:
       - ".github/workflows/helm.yaml"
       - "deploy/charts/**"
-
 env:
   CHART_NAME: burrito
   CHART_PATH: ./deploy/charts/burrito
@@ -47,9 +50,9 @@ jobs:
           if [[ ${{ github.event_name }} == 'pull_request' || ${{ github.event_name }} == 'push' && ${{ github.ref_type }} == 'branch' ]]; then
             echo "VERSION=$(echo $CURRENT_VERSION-${{ github.sha }})" >> $GITHUB_ENV
             echo "APP_VERSION=${{ github.sha }}" >> $GITHUB_ENV
-          elif [[ ${{ github.event_name }} == 'push' && ${{ github.ref_type }} == 'tag' ]]; then
-            echo "VERSION=$(echo ${{ github.ref_name }} | sed 's/v//')" >> $GITHUB_ENV
-            echo "APP_VERSION=${{ github.ref_name }}" >> $GITHUB_ENV
+          elif [[ ${{ github.event_name }} == 'workflow_call' ]]; then
+            echo "VERSION=$(echo ${{ inputs.version }} | sed 's/v//')" >> $GITHUB_ENV
+            echo "APP_VERSION=${{ inputs.version }}" >> $GITHUB_ENV
           else
             echo "Unsupported event type"
             exit 1

.github/workflows/release.yaml

@@ -1,19 +1,30 @@
 name: Release
 
 on:
-  push:
-    tags:
-      - "v*"
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Version to release (e.g. v1.2.3)"
+        required: true
+        type: string
 
 permissions:
   contents: write
   packages: write
   pull-requests: write
 
 jobs:
+  build-and-push:
+    uses: ./.github/workflows/build-and-push.yaml
+    with:
+      version: ${{ inputs.version }}
+    permissions:
+      packages: write
+
   version:
     runs-on: ubuntu-latest
     environment: production
+    needs: build-and-push
     env:
       CHART_PATH: ./deploy/charts/burrito
     steps:
@@ -24,28 +35,30 @@ jobs:
           ref: main
 
       - name: Bump VERSION file
-        run: |
-          echo ${{ github.ref_name }} > VERSION
+        run: echo "${{ inputs.version }}" > VERSION
 
       - name: Bump Helm Chart versions
         run: |
-          export CHART_VERSION=$(echo ${{ github.ref_name }} | sed 's/v//g')
-          export APP_VERSION=${{ github.ref_name }}
+          export CHART_VERSION=$(echo "${{ inputs.version }}" | sed 's/v//g')
+          export APP_VERSION="${{ inputs.version }}"
           yq -i '.version = env(CHART_VERSION)' $CHART_PATH/Chart.yaml
           yq -i '.appVersion = env(APP_VERSION)' $CHART_PATH/Chart.yaml
 
-      - name: Commit version to repository and open PR
+      - name: Pin image tag and digest in values.yaml
+        run: |
+          export IMAGE_TAG="${{ inputs.version }}@${{ needs.build-and-push.outputs.digest }}"
+          yq -i '.global.deployment.image.tag = env(IMAGE_TAG)' $CHART_PATH/values.yaml
+          yq -i '.config.burrito.runner.image.tag = env(IMAGE_TAG)' $CHART_PATH/values.yaml
+
+      - name: Commit and open PR
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          BRANCH_NAME="bump-version-${{ github.ref_name }}"
+          BRANCH_NAME="bump-version-${{ inputs.version }}"
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
           git add .
           git switch -c $BRANCH_NAME
-          git commit -m "chore(release): bump version to ${{ github.ref_name }}"
+          git commit -m "chore(release): bump version to ${{ inputs.version }}"
           git push origin $BRANCH_NAME
           gh pr create --fill --base main --head $BRANCH_NAME
-
-  build-and-push:
-    uses: ./.github/workflows/build-and-push.yaml

.github/workflows/tag-on-release.yaml

@@ -0,0 +1,60 @@
+name: Tag on Release
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - VERSION
+
+permissions:
+  contents: write
+  packages: write
+
+env:
+  CHART_NAME: burrito
+  CHART_PATH: ./deploy/charts/burrito
+  CHART_REPO: ghcr.io/${{ github.repository_owner }}/charts
+
+jobs:
+  tag:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.value }}
+      already_exists: ${{ steps.check.outputs.exists }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+
+      - name: Read version
+        id: version
+        run: echo "value=$(cat VERSION)" >> $GITHUB_OUTPUT
+
+      - name: Check tag does not already exist
+        id: check
+        run: |
+          if git ls-remote --tags origin "${{ steps.version.outputs.value }}" | grep -q "${{ steps.version.outputs.value }}"; then
+            echo "exists=true" >> $GITHUB_OUTPUT
+          else
+            echo "exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create and push tag
+        if: steps.check.outputs.exists == 'false'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "${{ steps.version.outputs.value }}"
+          git push origin "${{ steps.version.outputs.value }}"
+
+  helm-push:
+    uses: ./.github/workflows/helm.yaml
+    needs: tag
+    with:
+      version: ${{ needs.tag.outputs.version }}
+
+  docs-deploy:
+    uses: ./.github/workflows/docs.yaml
+    needs: tag
+    with:
+      version: ${{ needs.tag.outputs.version }}

deploy/charts/burrito/values.yaml

@@ -189,7 +189,7 @@ hermitcrab:
     image:
       pullPolicy: Always
       repository: sealio/hermitcrab
-      tag: main
+      tag: v0.1.7@sha256:2201a99d97d5f1c8071cc19aca631e3f90a92b3f246dc3a0cfb6d4b3a09d9ffd
     # -- Hermitcrab environment variables
     env:
       - name: SERVER_TLS_CERT_FILE