feat(helm): derive chart appVersion from the release, and lint with ct (#7643)

* improvement(helm): lint the chart with ct instead of hand-rolled checks

Replaces `helm lint` and the bespoke version-bump job with chart-testing,
the CNCF chart linter that ingress-nginx, prometheus-community and
external-secrets all gate on. It subsumes both: `helm lint` plus yamllint
over Chart.yaml and every values file, Chart.yaml schema validation, and
--check-version-increment, which is on by default and is exactly what the
33 lines of bash were reimplementing.

One trap worth recording. Passing `--charts` silently DISABLES the version
check -- it prints "Version increment checking disabled." and still exits 0,
so wiring it that way would have swapped a working gate for one that can
never fail. The PR path uses `--chart-dirs helm --target-branch <base>`; a
push has no base to diff, so `--charts` is correct there. Verified both
directions in a scratch repo with a real remote: content changed without a
bump gives "chart version not ok. Needs a version bump!" and exit 1, the
same change with a bump gives "Chart version ok."

Three chart fixes ct's yamllint required: 66 lines of trailing whitespace in
values.yaml, one inline comment a space short of the two yamllint wants, and
brace spacing in ci/full-values.yaml. Nothing but whitespace -- no
non-comment line changed, and both rendered manifest sets are byte-identical
before and after.

Renames ci/kind-values.yaml to ci/kind-overlay.yaml. ct treats every
ci/*-values.yaml as a standalone values set, but that file is a partial
layered on default-values.yaml, so linting it alone tripped the chart's own
required-secret guards. The new name is outside the glob and the header says
why.

Maintainer validation stays off: it resolves maintainers[].name against real
forge accounts and ours is the display name "Sim Team", so enabling it would
change what Artifact Hub shows.

* feat(helm): derive chart appVersion from the release instead of gating on it

appVersion is what the chart's image tags default to, so a stale one publishes
a chart that installs an older Sim than the release it ships with, and
images.yaml -- the list an operator mirrors into a disconnected registry --
names the wrong tags with it. Published chart versions are immutable, so each
stale value is frozen the moment it ships.

It was bumped by hand, drifted forty releases, and drifted twice more after a
check started catching it. That is the tell: the check could refuse to publish
but could not supply the value, so the only thing it reliably produced was a
red build on every release and a chart that never shipped. Only 1.11.0 was
ever published for exactly this reason.

The publish jobs now derive it. On a release merge the tag does not exist yet
-- this commit is what cuts it -- so the version comes from the commit
subject, and from the latest release for every other push. Both publish paths
run the same script before packaging, so the OCI artifact and the HTTP repo
cannot disagree.

Removes the post-merge check, which is now unreachable by construction, and
does not replace it with the pre-merge title gate that was considered: that
one guarded ground truth with a heuristic, and its failure mode was passing
silently.

Precedent is cert-manager, whose chart also lives in its application repo and
which injects the version at package time. The projects that commit the value
and bump by hand -- argo-cd, ingress-nginx, prometheus-community -- all keep
the chart in a separate repository, where a human is already editing
Chart.yaml as the unit of change. We are the former shape.

Verified the resolution across six subjects: release commit, multi-line body
carrying a decoy version, ordinary push, leading whitespace, shell
metacharacters (no expansion), and a version that is not at the start. Also
verified the script's exit codes directly rather than through a pipe, since a
gate that cannot fail is the thing being replaced here.

Sets appVersion to v0.8.26, two releases ahead of where it was stuck, and
regenerates images.yaml with it.

* fix(helm): match ci.yml's release predicate and resolve the version once

Two review findings, both real.

The leading-whitespace tolerance was wrong here. detect-version in ci.yml is
what actually cuts the tag and builds the images, and it anchors the version
at the first character. Accepting a subject it rejects meant the chart could
publish naming a release that was never created, pointing at images that do
not exist. The pattern is now identical to ci.yml's, with a comment saying it
has to stay that way. The tolerance came from a PR-title parsing problem in an
earlier design; commit subjects have a different authority.

The two publish jobs also resolved the version independently, and they run in
parallel. A release becoming public between those two API calls would package
the same immutable chart version with different appVersions, so the OCI
artifact and the HTTP repo would install different Sims. Resolution moved to
one job both consume, which also removes the duplicated logic.

Separately, --check only inspected Chart.yaml while the script writes both
that and the inventory derived from it, so it could report success over a
stale inventory. It now verifies both halves; confirmed it exits 1 when the
inventory is stale and 0 once regenerated.

Author: waleedlatif1

.github/workflows/helm.yml

@@ -39,13 +39,19 @@ jobs:
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
+          # ct diffs the chart against the PR base to decide whether the version
+          # was bumped, so a shallow clone would leave it nothing to compare.
+          fetch-depth: 0
           persist-credentials: false
 
       - name: Set up Helm
         uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4
         with:
           version: v3.16.4
 
+      - name: Set up chart-testing
+        uses: helm/chart-testing-action@6ec842c01de15ebb84c8627d2744a0c2f2755c9f # v2.8.0
+
       - name: Setup Bun
         uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
         with:
@@ -64,8 +70,33 @@ jobs:
       - name: Image inventory is current
         run: bun run images:check
 
-      - name: Helm lint
-        run: helm lint helm/sim --values helm/sim/ci/default-values.yaml
+      # ct is the CNCF chart linter (ingress-nginx, prometheus-community and
+      # external-secrets all gate on it). Beyond `helm lint` it runs yamllint over
+      # Chart.yaml and every values file, validates Chart.yaml against a schema,
+      # and — the reason the hand-rolled version-bump job is gone — enforces that
+      # the chart version increases whenever chart content changes.
+      #
+      # `--chart-dirs helm --target-branch` is load-bearing. Passing `--charts`
+      # instead silently DISABLES the version-increment check ("Version increment
+      # checking disabled.") and still exits 0, which would leave a gate that
+      # never fails. On a push there is no base to diff, so `--charts` is correct
+      # there and the version check simply does not apply.
+      #
+      # Maintainer validation is off because it resolves `maintainers[].name`
+      # against real forge accounts, and ours is the display name "Sim Team".
+      # Turning it on means changing what Artifact Hub shows.
+      - name: Chart lint (ct)
+        env:
+          BASE_REF: ${{ github.base_ref }}
+        run: |
+          set -euo pipefail
+          args=(--validate-maintainers=false)
+          if [ "${GITHUB_EVENT_NAME}" = "pull_request" ]; then
+            args+=(--chart-dirs helm --target-branch "${BASE_REF}")
+          else
+            args+=(--charts helm/sim)
+          fi
+          ct lint "${args[@]}"
 
       - name: Helm unit tests
         run: |
@@ -122,39 +153,6 @@ jobs:
               --set externalDatabase.password=ci-dummy-password > /dev/null
           done
 
-  version-bump:
-    name: Chart version bumped
-    if: github.event_name == 'pull_request'
-    runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
-    timeout-minutes: 5
-    steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
-        with:
-          fetch-depth: 0
-          # The version gate only reads history and fetches a public branch, so
-          # it never needs the token left behind in .git/config.
-          persist-credentials: false
-      - name: Require a Chart.yaml version bump when chart content changes
-        env:
-          BASE_REF: ${{ github.base_ref }}
-        run: |
-          set -euo pipefail
-          base="origin/${BASE_REF}"
-          git fetch origin "${BASE_REF}"
-          merge_base=$(git merge-base "$base" HEAD)
-          changed=$(git diff --name-only "$merge_base" HEAD)
-          if echo "$changed" | grep -q '^helm/sim/'; then
-            base_version=$(git show "$merge_base:helm/sim/Chart.yaml" | awk '/^version:/ {print $2}')
-            head_version=$(awk '/^version:/ {print $2}' helm/sim/Chart.yaml)
-            echo "base=$base_version head=$head_version"
-            if [ "$base_version" = "$head_version" ]; then
-              echo "::error::helm/sim/** changed but Chart.yaml version did not (still $head_version). Bump it per SemVer."
-              exit 1
-            fi
-          else
-            echo "No chart changes; skipping."
-          fi
-
   install:
     name: Install on kind and run helm test
     needs: chart
@@ -180,7 +178,7 @@ jobs:
           helm install sim helm/sim \
             --namespace sim --create-namespace \
             --values helm/sim/ci/default-values.yaml \
-            --values helm/sim/ci/kind-values.yaml \
+            --values helm/sim/ci/kind-overlay.yaml \
             --wait --timeout 15m
 
       - name: Diagnostics on failure
@@ -195,6 +193,49 @@ jobs:
       - name: Run helm test
         run: helm test sim --namespace sim --timeout 5m
 
+  # Resolved once and shared, so the two publish paths cannot package the same
+  # immutable chart version with different appVersions -- they run in parallel,
+  # and a release becoming public between two independent API calls would be
+  # enough to make the OCI artifact and the HTTP repo install different Sims.
+  release-version:
+    name: Resolve the app release
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'simstudioai/sim'
+    runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
+    timeout-minutes: 5
+    permissions:
+      contents: read # Read the release list.
+    outputs:
+      version: ${{ steps.resolve.outputs.version }}
+    steps:
+      # On a release merge the tag does not exist yet -- this commit is what cuts
+      # it -- so the subject is the only source available, and the latest release
+      # is the source of truth for every other push.
+      #
+      # The subject pattern MUST stay identical to detect-version in ci.yml, which
+      # is what actually creates the tag and builds the images. If this one
+      # matched a subject that one rejects, the chart would publish naming a
+      # release that was never cut.
+      - name: Resolve the app release
+        id: resolve
+        env:
+          HEAD_COMMIT_MESSAGE: ${{ github.event.head_commit.message }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          subject=${HEAD_COMMIT_MESSAGE%%$'\n'*}
+          if [[ "$subject" =~ ^(v[0-9]+\.[0-9]+\.[0-9]+): ]]; then
+            resolved="${BASH_REMATCH[1]}"
+            echo "Release commit; shipping the chart with ${resolved}."
+          else
+            resolved=$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq .tag_name)
+            echo "Not a release commit; shipping the chart with the latest release ${resolved}."
+          fi
+          if [ -z "$resolved" ]; then
+            echo "::error::Could not resolve an app release to ship this chart with."
+            exit 1
+          fi
+          echo "version=${resolved}" >> "$GITHUB_OUTPUT"
+
   # Publishes the chart to GHCR as an OCI artifact. Self-hosters cannot admit a
   # chart pulled from a git checkout — they need an immutable, versioned artifact
   # they can pin by digest and mirror into an internal registry — so shipping the
@@ -206,7 +247,7 @@ jobs:
   # A separate workflow would race those instead of waiting for them.
   publish:
     name: Publish chart to GHCR
-    needs: [chart, install]
+    needs: [chart, install, release-version]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'simstudioai/sim'
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 15
@@ -234,6 +275,19 @@ jobs:
           username: ${{ github.repository_owner }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: 1.4.1
+
+      # Derives appVersion rather than checking it, so the published chart cannot
+      # be pinned to an older Sim than the release it ships with. The committed
+      # value is kept current too, but nothing depends on a human remembering.
+      - name: Sync chart appVersion to the release
+        env:
+          APP_VERSION: ${{ needs.release-version.outputs.version }}
+        run: bun run scripts/sync-chart-appversion.ts --version "${APP_VERSION}"
+
       - name: Package chart
         id: package
         run: |
@@ -249,44 +303,6 @@ jobs:
             echo "repository=ghcr.io/${GITHUB_REPOSITORY_OWNER}/charts/${name}"
           } >> "$GITHUB_OUTPUT"
 
-      # `appVersion` is what the image tags default to, so a stale one publishes
-      # a chart that silently installs an old Sim -- and because published chart
-      # versions are immutable, every stale value is frozen forever. It sat six
-      # releases behind before this check existed, bumped only by hand.
-      #
-      # BEHIND is the failure. AHEAD is normal and must not be blocked: a
-      # version tag is cut by the main-branch merge commit that releases it
-      # (detect-version in ci.yml), so appVersion legitimately names a release
-      # that does not exist yet while that release is still being built. Failing
-      # on any mismatch would race that workflow and block the very publish the
-      # bump was for. `helm/sim/ci/kind-values.yaml` documents the same
-      # circularity, and it is why appVersion went unbumped for so long.
-      #
-      # Compares against the latest GitHub release rather than a hardcoded value
-      # so the check cannot go stale itself. Prereleases and drafts are excluded:
-      # the `/releases/latest` endpoint already returns neither.
-      - name: appVersion does not lag the app release
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          set -euo pipefail
-          app_version=$(helm show chart helm/sim | awk '/^appVersion:/ {print $2}' | tr -d '"')
-          latest=$(gh api "repos/${GITHUB_REPOSITORY}/releases/latest" --jq .tag_name)
-          if [ -z "$latest" ]; then
-            echo "::error::Could not resolve the latest release; refusing to publish unverified."
-            exit 1
-          fi
-          if [ "$app_version" = "$latest" ]; then
-            echo "appVersion ${app_version} matches the latest release."
-            exit 0
-          fi
-          oldest=$(printf '%s\n%s\n' "$app_version" "$latest" | sort -V | head -1)
-          if [ "$oldest" = "$app_version" ]; then
-            echo "::error::Chart.yaml appVersion is ${app_version} but the latest release is ${latest}. Bump appVersion (and the chart version) so the chart does not publish an install pinned to an older Sim."
-            exit 1
-          fi
-          echo "::notice::appVersion ${app_version} is ahead of the latest release ${latest}, which is expected while that release is still being cut."
-
       # Chart versions are immutable once published: whoever pinned a version
       # must keep resolving the same bytes forever. The PR gate above already
       # forces a version bump on every chart change, so a version that is
@@ -424,7 +440,7 @@ jobs:
   # the job holding the signing identity.
   publish-http:
     name: Publish chart to the Helm repo
-    needs: [chart, install]
+    needs: [chart, install, release-version]
     if: github.event_name == 'push' && github.ref == 'refs/heads/main' && github.repository == 'simstudioai/sim'
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 15
@@ -454,6 +470,20 @@ jobs:
             echo "::warning::No gh-pages branch, so the HTTP chart repo was not updated. Create it and point GitHub Pages at it to activate this job. The OCI publish is unaffected."
           fi
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2
+        with:
+          bun-version: 1.4.1
+
+      # Derives appVersion rather than checking it, so the published chart cannot
+      # be pinned to an older Sim than the release it ships with. The committed
+      # value is kept current too, but nothing depends on a human remembering.
+      - name: Sync chart appVersion to the release
+        if: steps.pages.outputs.exists == 'true'
+        env:
+          APP_VERSION: ${{ needs.release-version.outputs.version }}
+        run: bun run scripts/sync-chart-appversion.ts --version "${APP_VERSION}"
+
       - name: Configure Git
         if: steps.pages.outputs.exists == 'true'
         env:

helm/sim/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: sim
 description: A Helm chart for Sim - the open-source AI workspace where teams build, deploy, and manage AI agents
 type: application
-version: 1.11.1
-appVersion: "v0.8.24"
+version: 1.11.2
+appVersion: "v0.8.26"
 kubeVersion: ">=1.25.0-0"
 home: https://sim.ai
 icon: https://raw.githubusercontent.com/simstudioai/sim/main/apps/sim/public/logo/primary/primary.svg

helm/sim/ci/full-values.yaml

@@ -21,10 +21,10 @@ ingress:
   enabled: true
   app:
     host: ci.example.com
-    paths: [{ path: /, pathType: Prefix }]
+    paths: [{path: /, pathType: Prefix}]
   realtime:
     host: ci-ws.example.com
-    paths: [{ path: /, pathType: Prefix }]
+    paths: [{path: /, pathType: Prefix}]
   tls:
     enabled: true
 

helm/sim/ci/kind-values.yaml helm/sim/ci/kind-overlay.yamlhelm/sim/ci/kind-values.yaml renamed to helm/sim/ci/kind-overlay.yaml

@@ -1,6 +1,10 @@
-# CI-only overlay for the kind install test: shrink resource requests so the
-# default configuration schedules on a small CI runner. Layered on top of
-# ci/default-values.yaml. Dummy sizing — never use in a deployment.
+# CI-only OVERLAY for the kind install test. The name deliberately avoids the
+# `ci/*-values.yaml` suffix: `ct lint` treats every file matching that glob as a
+# standalone values set, and this one is a partial layered on default-values.yaml.
+#
+# Shrinks resource requests so the default configuration schedules on a small CI
+# runner. Layered on top of ci/default-values.yaml. Dummy sizing — never use in
+# a deployment.
 
 # Pin every first-party image to the published :latest rather than letting the
 # tag default to Chart.AppVersion. appVersion names the release the chart ships

helm/sim/images.yaml

@@ -22,22 +22,22 @@
 # render it twice. That override also CHANGES where the chart pulls from, to
 # `<your-registry>/nvidia/k8s-device-plugin` — mirror the device plugin there
 # instead of to the `mirror` path listed below, or the pull fails.
-appVersion: v0.8.24
+appVersion: v0.8.26
 images:
   - source: busybox:1.36
     mirror: busybox:1.36
   - source: curlimages/curl:8.5.0
     mirror: curlimages/curl:8.5.0
-  - source: ghcr.io/simstudioai/copilot:v0.8.24
-    mirror: simstudioai/copilot:v0.8.24
-  - source: ghcr.io/simstudioai/migrations:v0.8.24
-    mirror: simstudioai/migrations:v0.8.24
-  - source: ghcr.io/simstudioai/pii:v0.8.24
-    mirror: simstudioai/pii:v0.8.24
-  - source: ghcr.io/simstudioai/realtime:v0.8.24
-    mirror: simstudioai/realtime:v0.8.24
-  - source: ghcr.io/simstudioai/simstudio:v0.8.24
-    mirror: simstudioai/simstudio:v0.8.24
+  - source: ghcr.io/simstudioai/copilot:v0.8.26
+    mirror: simstudioai/copilot:v0.8.26
+  - source: ghcr.io/simstudioai/migrations:v0.8.26
+    mirror: simstudioai/migrations:v0.8.26
+  - source: ghcr.io/simstudioai/pii:v0.8.26
+    mirror: simstudioai/pii:v0.8.26
+  - source: ghcr.io/simstudioai/realtime:v0.8.26
+    mirror: simstudioai/realtime:v0.8.26
+  - source: ghcr.io/simstudioai/simstudio:v0.8.26
+    mirror: simstudioai/simstudio:v0.8.26
   - source: nvcr.io/nvidia/k8s-device-plugin:v0.18.2
     mirror: nvcr.io/nvidia/k8s-device-plugin:v0.18.2
   - source: ollama/ollama:0.23.2