feat(helm): publish the chart to ghcr.io and keep its version in step with releases (#383)

The chart pinned appVersion 3.24.0 and nothing bumped it on release, so a default install ran an image six minor versions old, and the docs example pointed at a tag without the v prefix that does not exist on the registry.

The chart version now equals the application version. The tag build's sync job updates Chart.yaml alongside package.json, and a new job in the tag build packages the chart after the image is pushed and publishes it to oci://ghcr.io/raylabshq/charts/gitea-mirror. Docs and the website install tab show the OCI install.

Claude-Session: https://claude.ai/code/session_01Tp9pmi65a8k5jLMQFLf4JX

.github/workflows/docker-build.yml

@@ -321,7 +321,7 @@ jobs:
           sarif_file: scout-results.sarif
 
   sync-version-main:
-    name: Sync package.json version back to main
+    name: Sync package.json and Chart.yaml versions back to main
     if: startsWith(github.ref, 'refs/tags/v')
     runs-on: ubuntu-latest
     needs: docker
@@ -334,7 +334,7 @@ jobs:
         with:
           ref: ${{ github.event.repository.default_branch }}
 
-      - name: Update package.json version on main
+      - name: Update package.json and Chart.yaml versions on main
         env:
           TAG_VERSION: ${{ github.ref_name }}
           TARGET_BRANCH: ${{ github.event.repository.default_branch }}
@@ -345,18 +345,90 @@ jobs:
           fi
 
           APP_VERSION="${TAG_VERSION#v}"
-          echo "Syncing ${TARGET_BRANCH}/package.json to ${APP_VERSION}"
+          echo "Syncing ${TARGET_BRANCH} package.json and Chart.yaml to ${APP_VERSION}"
 
           jq --arg version "${APP_VERSION}" '.version = $version' package.json > package.json.tmp
           mv package.json.tmp package.json
 
-          if git diff --quiet -- package.json; then
-            echo "package.json on ${TARGET_BRANCH} already at ${APP_VERSION}; nothing to commit."
+          # The chart version tracks the app version so the default image tag
+          # always points at the release the chart was published with.
+          sed -i -E \
+            -e "s/^version: .*/version: ${APP_VERSION}/" \
+            -e "s/^appVersion: .*/appVersion: \"${APP_VERSION}\"/" \
+            helm/gitea-mirror/Chart.yaml
+
+          if git diff --quiet -- package.json helm/gitea-mirror/Chart.yaml; then
+            echo "Versions on ${TARGET_BRANCH} already at ${APP_VERSION}; nothing to commit."
             exit 0
           fi
 
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add package.json
+          git add package.json helm/gitea-mirror/Chart.yaml
           git commit -m "chore: sync version to ${APP_VERSION}"
           git push origin "HEAD:${TARGET_BRANCH}"
+
+  publish-helm-chart:
+    name: Publish Helm chart to ghcr.io
+    # Runs after the image for this tag is on the registry, so the chart never
+    # points at an image that does not exist yet. The chart version and
+    # appVersion both follow the release version.
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    needs: docker
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout tag
+        uses: actions/checkout@v4
+
+      - name: Resolve version
+        id: version
+        env:
+          TAG_VERSION: ${{ github.ref_name }}
+        run: |
+          if [[ ! "$TAG_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::Release tag '${TAG_VERSION}' is invalid. Expected semver tag format like v1.2.3 or v1.2.3-rc.1"
+            exit 1
+          fi
+          echo "version=${TAG_VERSION#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Setup Helm
+        uses: azure/setup-helm@v4
+        with:
+          version: v3.19.0
+
+      - name: Lint and package chart
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          helm lint ./helm/gitea-mirror
+          helm package ./helm/gitea-mirror \
+            --version "$VERSION" \
+            --app-version "$VERSION" \
+            --destination dist
+
+      - name: Log into registry
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ACTOR: ${{ github.actor }}
+        run: |
+          echo "$GITHUB_TOKEN" | helm registry login "$REGISTRY" --username "$ACTOR" --password-stdin
+
+      - name: Push chart
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          OWNER_LC="$(echo "$OWNER" | tr '[:upper:]' '[:lower:]')"
+          helm push "dist/gitea-mirror-${VERSION}.tgz" "oci://${REGISTRY}/${OWNER_LC}/charts"
+          {
+            echo "### Helm chart ${VERSION} published"
+            echo
+            echo '```bash'
+            echo "helm upgrade --install gitea-mirror oci://${REGISTRY}/${OWNER_LC}/charts/gitea-mirror --version ${VERSION}"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"