chore(helm): harden the chart workflow against zizmor and document cosign v3

Ran the two standard workflow linters over helm.yml. actionlint reported one
shellcheck style issue; zizmor reported 22 findings, including two High.

Both High findings predate this PR: the version gate expanded
github.base_ref straight into a run block. The three Medium findings were
checkouts leaving the token in .git/config. Fixed all of them here rather
than leaving known findings in a file this PR already rewrites -- the gate
only reads history and fetches a public branch, so it never needed the
credential.

The 16 informational findings were mine: every ${{ }} in a run block is
template expansion before the shell sees it, so the documented fix is to
pass values through env and reference them as shell variables. Done for the
whole publish job, which also removes the shellcheck nit.

zizmor now reports zero findings on the file in pedantic mode, with no
suppressions, and actionlint is clean.

Separately, cosign v3 writes the Sigstore protobuf bundle format by default
and cosign v2 cannot read it, so the verification instructions now state the
required version. The in-workflow verify uses the same binary it signs with,
so it could never have caught this.

Re-verified the existence guard's four branches after the env refactor, and
confirmed it also fails closed when the registry login has not happened.

Author: waleedlatif1

.github/workflows/helm.yml

@@ -38,6 +38,8 @@ jobs:
     timeout-minutes: 15
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
 
       - name: Set up Helm
         uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4
@@ -129,11 +131,16 @@ jobs:
       - 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/${{ github.base_ref }}"
-          git fetch origin "${{ github.base_ref }}"
+          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
@@ -155,6 +162,8 @@ jobs:
     timeout-minutes: 25
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
 
       - name: Set up Helm
         uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4
@@ -202,11 +211,10 @@ jobs:
     runs-on: ${{ (vars.CI_PROVIDER == '' || vars.CI_PROVIDER == 'blacksmith') && 'blacksmith-2vcpu-ubuntu-2404' || 'ubuntu-latest' }}
     timeout-minutes: 15
     permissions:
-      contents: read
-      packages: write
-      # Sigstore signs against the runner's OIDC identity; no key material is stored.
-      id-token: write
-      attestations: write
+      contents: read # Read the chart source.
+      packages: write # Push the chart, its signature, and its attestations to GHCR.
+      id-token: write # Sigstore signs against the runner's OIDC identity; no key material is stored.
+      attestations: write # Let actions/attest-build-provenance record the SLSA provenance.
     steps:
       - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
         with:
@@ -230,13 +238,16 @@ jobs:
         id: package
         run: |
           set -euo pipefail
-          name=$(helm show chart helm/sim | awk '/^name:/ {print $2}')
-          version=$(helm show chart helm/sim | awk '/^version:/ {print $2}')
+          chart=$(helm show chart helm/sim)
+          name=$(printf '%s\n' "$chart" | awk '/^name:/ {print $2}')
+          version=$(printf '%s\n' "$chart" | awk '/^version:/ {print $2}')
           helm package helm/sim --destination dist
-          echo "name=${name}" >> "$GITHUB_OUTPUT"
-          echo "version=${version}" >> "$GITHUB_OUTPUT"
-          echo "path=dist/${name}-${version}.tgz" >> "$GITHUB_OUTPUT"
-          echo "repository=ghcr.io/${GITHUB_REPOSITORY_OWNER}/charts/${name}" >> "$GITHUB_OUTPUT"
+          {
+            echo "name=${name}"
+            echo "version=${version}"
+            echo "path=dist/${name}-${version}.tgz"
+            echo "repository=ghcr.io/${GITHUB_REPOSITORY_OWNER}/charts/${name}"
+          } >> "$GITHUB_OUTPUT"
 
       # Chart versions are immutable once published: whoever pinned a version
       # must keep resolving the same bytes forever. The PR gate above already
@@ -256,17 +267,20 @@ jobs:
       # do not match and stop the job instead.
       - name: Skip if this version is already published
         id: exists
+        env:
+          REPOSITORY: ${{ steps.package.outputs.repository }}
+          NAME: ${{ steps.package.outputs.name }}
+          VERSION: ${{ steps.package.outputs.version }}
         run: |
           set -euo pipefail
-          if err=$(helm show chart "oci://${{ steps.package.outputs.repository }}" \
-                     --version "${{ steps.package.outputs.version }}" 2>&1 >/dev/null); then
+          if err=$(helm show chart "oci://${REPOSITORY}" --version "${VERSION}" 2>&1 >/dev/null); then
             echo "already=true" >> "$GITHUB_OUTPUT"
-            echo "::notice::${{ steps.package.outputs.name }} ${{ steps.package.outputs.version }} is already published; skipping."
+            echo "::notice::${NAME} ${VERSION} is already published; skipping."
           elif printf '%s\n' "$err" | grep -q ': not found'; then
             echo "already=false" >> "$GITHUB_OUTPUT"
           else
             printf '%s\n' "$err"
-            echo "::error::Could not determine whether ${{ steps.package.outputs.name }} ${{ steps.package.outputs.version }} is already published. Refusing to push, because an unchecked push can overwrite a published version."
+            echo "::error::Could not determine whether ${NAME} ${VERSION} is already published. Refusing to push, because an unchecked push can overwrite a published version."
             exit 1
           fi
 
@@ -276,12 +290,13 @@ jobs:
       - name: Push chart
         id: push
         if: steps.exists.outputs.already == 'false'
+        env:
+          CHART_PATH: ${{ steps.package.outputs.path }}
         run: |
           set -euo pipefail
-          output=$(helm push "${{ steps.package.outputs.path }}" \
-            "oci://ghcr.io/${GITHUB_REPOSITORY_OWNER}/charts" 2>&1)
-          echo "$output"
-          digest=$(echo "$output" | grep -oE 'sha256:[a-f0-9]{64}' | head -1 || true)
+          output=$(helm push "${CHART_PATH}" "oci://ghcr.io/${GITHUB_REPOSITORY_OWNER}/charts" 2>&1)
+          printf '%s\n' "$output"
+          digest=$(printf '%s\n' "$output" | grep -oE 'sha256:[a-f0-9]{64}' | head -1 || true)
           if [ -z "$digest" ]; then
             echo "::error::helm push did not report a digest; refusing to sign an unidentified artifact"
             exit 1
@@ -299,9 +314,12 @@ jobs:
       # publishing a signature at all.
       - name: Sign and verify chart
         if: steps.exists.outputs.already == 'false'
+        env:
+          REPOSITORY: ${{ steps.package.outputs.repository }}
+          DIGEST: ${{ steps.push.outputs.digest }}
         run: |
           set -euo pipefail
-          ref="${{ steps.package.outputs.repository }}@${{ steps.push.outputs.digest }}"
+          ref="${REPOSITORY}@${DIGEST}"
           cosign sign --yes "$ref"
           cosign verify "$ref" \
             --certificate-identity-regexp "^https://github.com/${GITHUB_REPOSITORY}/" \
@@ -324,24 +342,31 @@ jobs:
       # tag on the chart's own OCI repository. Pushed on every run, including
       # version-skip runs, so an edit to the metadata file alone still lands.
       - name: Publish Artifact Hub metadata
+        env:
+          REPOSITORY: ${{ steps.package.outputs.repository }}
         run: |
           set -euo pipefail
-          oras push "${{ steps.package.outputs.repository }}:artifacthub.io" \
+          oras push "${REPOSITORY}:artifacthub.io" \
             --config /dev/null:application/vnd.cncf.artifacthub.config.v1+yaml \
             helm/artifacthub-repo.yml:application/vnd.cncf.artifacthub.repository-metadata.layer.v1.yaml
 
       - name: Summary
+        env:
+          ALREADY: ${{ steps.exists.outputs.already }}
+          REPOSITORY: ${{ steps.package.outputs.repository }}
+          VERSION: ${{ steps.package.outputs.version }}
+          DIGEST: ${{ steps.push.outputs.digest }}
         run: |
           {
-            if [ "${{ steps.exists.outputs.already }}" = "true" ]; then
-              echo "### Chart ${{ steps.package.outputs.version }} was already published — nothing to do"
+            if [ "${ALREADY}" = "true" ]; then
+              echo "### Chart ${VERSION} was already published — nothing to do"
             else
-              echo "### Published chart ${{ steps.package.outputs.version }}"
+              echo "### Published chart ${VERSION}"
               echo
-              echo "Digest: \`${{ steps.push.outputs.digest }}\`"
+              echo "Digest: \`${DIGEST}\`"
             fi
             echo
             echo '```bash'
-            echo "helm install sim oci://${{ steps.package.outputs.repository }} --version ${{ steps.package.outputs.version }}"
+            echo "helm install sim oci://${REPOSITORY} --version ${VERSION}"
             echo '```'
           } >> "$GITHUB_STEP_SUMMARY"

apps/docs/content/docs/platform/self-hosting/kubernetes.mdx

@@ -72,6 +72,10 @@ gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.1 --repo simstudi
 
 Signing is Sigstore-only — there is no GPG `.prov` file, so `helm install --verify` does not apply.
 
+<Callout type="warn">
+  Verification requires **cosign v3.0 or newer**. Signatures use the Sigstore protobuf bundle format, which cosign v3 writes by default and cosign v2 cannot read. cosign v3.1+ auto-detects both formats.
+</Callout>
+
 ## Cloud-Specific Values
 
 These are cloud-tuned **alternatives** to the generic install above — pick one path, don't run both. The commands reuse the `$BETTER_AUTH_SECRET`, `$ENCRYPTION_KEY`, `$INTERNAL_API_SECRET`, `$API_ENCRYPTION_KEY`, `$CRON_SECRET`, and `$POSTGRES_PASSWORD` variables generated in [Installation](#installation) above, so run that block's `openssl` lines first in the same shell. They use `helm upgrade --install`, so they work whether or not a release exists yet. Two caveats when converting an existing generic install rather than starting fresh: (1) **reuse the original secret values** — recover them with `helm get values sim -n simstudio` if your shell no longer has them; supplying a newly generated `ENCRYPTION_KEY` makes every previously encrypted value (workspace environment variables, stored provider keys, MCP OAuth credentials) undecryptable. (2) The cloud values rename the bundled PostgreSQL database to `simstudio`, but Postgres only applies that setting on first initialization — add `--set postgresql.auth.database=sim` to keep your existing database. If you'd rather start clean, `helm uninstall sim -n simstudio`, delete its PVCs, and run the cloud command fresh.

helm/sim/README.md

@@ -189,6 +189,8 @@ There is no GPG `.prov` file — signing is Sigstore-only, so there is no
 long-lived private key to hold or rotate. `helm install --verify` expects the
 GPG provenance format and will not work; use `cosign verify` above.
 
+> **Requires cosign v3.0 or newer.** Signatures use the Sigstore protobuf bundle format, which cosign v3 writes by default and cosign v2 cannot read. cosign v3.1+ auto-detects both formats.
+
 ## Upgrading
 
 ```bash