feat(helm): publish the chart to GHCR as a signed OCI artifact

The chart has only ever existed inside the repo, so self-hosters whose
security process requires an officially published artifact could not use
it at all — a chart pulled from a git checkout is not something they can
pin, mirror, or admit.

Publishes helm/sim to oci://ghcr.io/simstudioai/charts/sim on push to
main, signed with Sigstore keyless signing and carrying a SLSA build
provenance attestation, both stored in the registry so they survive a
mirror into an internal registry.

The publish job lives in helm.yml rather than its own publish-*.yml so it
can gate on the existing jobs: nothing ships unless the chart linted,
unit-tested, rendered clean under kubeconform, and installed on kind.
Publishing is idempotent — a version already in the registry is skipped
rather than overwritten, since a published chart version is immutable.

Also pushes helm/artifacthub-repo.yml to the reserved artifacthub.io tag
for the Artifact Hub listing, and switches the chart README and the
Kubernetes docs page off the clone-and-install path.

Author: waleedlatif1

.github/workflows/helm.yml

@@ -5,6 +5,8 @@ on:
     branches: [main, staging, dev]
     paths:
       - 'helm/sim/**'
+      # Repository-level Artifact Hub metadata, republished by the publish job.
+      - 'helm/artifacthub-repo.yml'
       - '.github/workflows/helm.yml'
       # The image inventory is generated from the chart and checked here, so a
       # change to its generator has to run this workflow too.
@@ -14,6 +16,8 @@ on:
     branches: [main, staging, dev]
     paths:
       - 'helm/sim/**'
+      # Repository-level Artifact Hub metadata, republished by the publish job.
+      - 'helm/artifacthub-repo.yml'
       - '.github/workflows/helm.yml'
       # The image inventory is generated from the chart and checked here, so a
       # change to its generator has to run this workflow too.
@@ -181,3 +185,148 @@ jobs:
 
       - name: Run helm test
         run: helm test sim --namespace sim --timeout 5m
+
+  # 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
+  # chart in-repo only is the same as not shipping it.
+  #
+  # Lives here rather than in a `publish-*.yml` of its own so it can gate on the
+  # jobs above: nothing is published unless the chart linted, unit-tested,
+  # rendered clean under kubeconform, and actually installed on a kind cluster.
+  # A separate workflow would race those instead of waiting for them.
+  publish:
+    name: Publish chart to GHCR
+    needs: [chart, install]
+    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
+    permissions:
+      contents: read
+      packages: write
+      # Sigstore signs against the runner's OIDC identity; no key material is stored.
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+
+      - name: Set up Helm
+        uses: azure/setup-helm@1a275c3b69536ee54be43f2070a358922e12c8d4 # v4
+        with:
+          version: v3.16.4
+
+      # oras also reads ~/.docker/config.json, so this one login covers both the
+      # chart push and the Artifact Hub metadata push below.
+      - name: Login to GHCR
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee # v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Package chart
+        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}')
+          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"
+
+      # 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 already in the registry means this commit changed something outside
+      # `helm/sim/` — republishing would either fail or silently move a tag.
+      - name: Skip if this version is already published
+        id: exists
+        run: |
+          set -euo pipefail
+          if helm show chart "oci://${{ steps.package.outputs.repository }}" \
+               --version "${{ steps.package.outputs.version }}" > /dev/null 2>&1; then
+            echo "already=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::${{ steps.package.outputs.name }} ${{ steps.package.outputs.version }} is already published; skipping."
+          else
+            echo "already=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      # `helm push` takes the namespace only — it derives the repository
+      # basename from the chart's name and the tag from its version, so the
+      # result is ghcr.io/<owner>/charts/sim:<version>.
+      - name: Push chart
+        id: push
+        if: steps.exists.outputs.already == 'false'
+        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)
+          if [ -z "$digest" ]; then
+            echo "::error::helm push did not report a digest; refusing to sign an unidentified artifact"
+            exit 1
+          fi
+          echo "digest=${digest}" >> "$GITHUB_OUTPUT"
+
+      - name: Install Cosign
+        if: steps.exists.outputs.already == 'false'
+        uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2
+
+      # Signed by digest, never by tag: a tag is a mutable pointer, so signing
+      # one would attest to whatever it happens to reference later. The verify
+      # is not ceremony — it fails the run if the signature we just wrote cannot
+      # be read back with the identity we expect, which is the whole point of
+      # publishing a signature at all.
+      - name: Sign and verify chart
+        if: steps.exists.outputs.already == 'false'
+        run: |
+          set -euo pipefail
+          ref="${{ steps.package.outputs.repository }}@${{ steps.push.outputs.digest }}"
+          cosign sign --yes "$ref"
+          cosign verify "$ref" \
+            --certificate-identity-regexp "^https://github.com/${GITHUB_REPOSITORY}/" \
+            --certificate-oidc-issuer https://token.actions.githubusercontent.com
+
+      # Stored alongside the chart so a mirrored registry carries the
+      # attestation with it, rather than only being retrievable from GitHub.
+      - name: Attest build provenance
+        if: steps.exists.outputs.already == 'false'
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-name: ${{ steps.package.outputs.repository }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true
+
+      - name: Set up ORAS
+        uses: oras-project/setup-oras@1d808f7d7f6995cc68b7bf507bfe5c5446e1dc9d # v2.0.1
+
+      # Artifact Hub reads repository metadata from the reserved `artifacthub.io`
+      # 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
+        run: |
+          set -euo pipefail
+          oras push "${{ steps.package.outputs.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
+        run: |
+          {
+            if [ "${{ steps.exists.outputs.already }}" = "true" ]; then
+              echo "### Chart ${{ steps.package.outputs.version }} was already published — nothing to do"
+            else
+              echo "### Published chart ${{ steps.package.outputs.version }}"
+              echo
+              echo "Digest: \`${{ steps.push.outputs.digest }}\`"
+            fi
+            echo
+            echo '```bash'
+            echo "helm install sim oci://${{ steps.package.outputs.repository }} --version ${{ steps.package.outputs.version }}"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"

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

@@ -21,10 +21,11 @@ import { FAQ } from '@/components/ui/faq'
 
 ## Installation
 
-```bash
-# Clone repo
-git clone https://github.com/simstudioai/sim.git && cd sim
+The chart is published to GitHub Container Registry as an OCI artifact at
+`oci://ghcr.io/simstudioai/charts/sim`. Install it directly — no clone, and no
+`helm repo add`.
 
+```bash
 # Generate secrets
 BETTER_AUTH_SECRET=$(openssl rand -hex 32)
 ENCRYPTION_KEY=$(openssl rand -hex 32)
@@ -34,7 +35,8 @@ CRON_SECRET=$(openssl rand -hex 32)
 POSTGRES_PASSWORD=$(openssl rand -hex 24)
 
 # Install
-helm install sim ./helm/sim \
+helm install sim oci://ghcr.io/simstudioai/charts/sim \
+  --version 1.9.1 \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
   --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
@@ -56,13 +58,28 @@ helm install sim ./helm/sim \
   This installs the chart's default image tag. For production, **pin `app`, `realtime`, and `migrations` to the same explicit release tag** — see [Upgrades](/platform/self-hosting/upgrades).
 </Callout>
 
+## Verifying the chart
+
+Every published version is signed with Sigstore keyless signing and carries a SLSA build-provenance attestation. Both live in the registry alongside the chart, so they survive a mirror into an internal registry.
+
+```bash
+cosign verify oci://ghcr.io/simstudioai/charts/sim:1.9.1 \
+  --certificate-identity-regexp '^https://github.com/simstudioai/sim/' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+
+gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.1 --repo simstudioai/sim
+```
+
+Signing is Sigstore-only — there is no GPG `.prov` file, so `helm install --verify` does not apply.
+
 ## 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.
 
 ```bash
-helm upgrade --install sim ./helm/sim \
-  --values ./helm/sim/examples/values-aws.yaml \
+helm upgrade --install sim oci://ghcr.io/simstudioai/charts/sim \
+  --version 1.9.1 \
+  --values https://raw.githubusercontent.com/simstudioai/sim/main/helm/sim/examples/values-aws.yaml \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
   --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
@@ -80,7 +97,7 @@ helm upgrade --install sim ./helm/sim \
 
 Every one of those overrides is required. The cloud values files hardcode a placeholder domain in all six places, and overriding only `NEXT_PUBLIC_APP_URL` leaves sign-in pointed at the placeholder, realtime rejecting every socket upgrade, and the Ingress serving the wrong host.
 
-Swap the `--values` file for your cloud: `values-aws.yaml` (EKS), `values-azure.yaml` (AKS), or `values-gcp.yaml` (GKE). Everything else is identical.
+Swap the `--values` file for your cloud: `values-aws.yaml` (EKS), `values-azure.yaml` (AKS), or `values-gcp.yaml` (GKE). Everything else is identical. Helm reads `--values` over HTTPS, so this works without a checkout; the example files are not part of the packaged chart. Download the file and edit it locally if you'd rather not fetch it at install time.
 
 ## Key Configuration
 
@@ -181,8 +198,8 @@ kubectl port-forward deployment/sim-app 3000:3000 -n simstudio
 # View logs
 kubectl logs -l app.kubernetes.io/component=app -n simstudio --tail=100
 
-# Upgrade
-helm upgrade sim ./helm/sim --namespace simstudio
+# Upgrade (always pin the target chart version)
+helm upgrade sim oci://ghcr.io/simstudioai/charts/sim --version 1.9.1 --namespace simstudio
 
 # Uninstall
 helm uninstall sim --namespace simstudio

helm/artifacthub-repo.yml

@@ -0,0 +1,22 @@
+# Artifact Hub repository metadata for the Sim chart.
+#
+# Lives outside `helm/sim/` on purpose: it describes the *repository* rather
+# than the chart, so it must not be packaged into the `.tgz`, and a change to it
+# must not trip the chart's mandatory Chart.yaml version bump.
+#
+# The publish job pushes this file to the OCI registry under the reserved
+# `artifacthub.io` tag, which is where Artifact Hub looks for it:
+#   ghcr.io/simstudioai/charts/sim:artifacthub.io
+#
+# `owners` is what backs an ownership claim — Artifact Hub matches the email of
+# the requesting account against this list, and processes claims immediately
+# rather than waiting for the next repository scan.
+owners:
+  - name: Sim Team
+    email: help@sim.ai
+
+# Set this to the repository's Artifact Hub ID once the repository has been
+# registered at https://artifacthub.io/control-panel/repositories. It is what
+# turns on the "Verified Publisher" badge; until then the listing still works,
+# just unverified.
+# repositoryID: ""

helm/sim/Chart.yaml

@@ -2,7 +2,7 @@ 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.9.0
+version: 1.9.1
 appVersion: "v0.8.18"
 kubeVersion: ">=1.25.0-0"
 home: https://sim.ai

helm/sim/README.md

@@ -2,6 +2,7 @@
 
 Deploy [Sim](https://sim.ai) — the open-source AI workspace where teams build, deploy, and manage AI agents — on Kubernetes.
 
+* **Registry:** `oci://ghcr.io/simstudioai/charts/sim`
 * **Chart version:** see `Chart.yaml`
 * **App version:** tracks the upstream Sim release
 * **Kubernetes:** 1.25+
@@ -19,8 +20,8 @@ export INTERNAL_API_SECRET=$(openssl rand -hex 32)
 export CRON_SECRET=$(openssl rand -hex 32)
 export POSTGRES_PASSWORD=$(openssl rand -base64 24 | tr -d '/+=')
 
-# Install from this repository
-helm install sim ./helm/sim \
+# Install from the registry
+helm install sim oci://ghcr.io/simstudioai/charts/sim \
   --namespace sim --create-namespace \
   --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
   --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
@@ -96,7 +97,42 @@ If you set `app.secrets.existingSecret.enabled=true` and point at a pre-created
 
 ## Installing the chart
 
-### From this repository
+### From the registry
+
+The chart is published to GitHub Container Registry as an OCI artifact. This is
+the supported install path — no clone, no `helm repo add`, and every version is
+immutable once published.
+
+```bash
+# List the published versions
+helm show chart oci://ghcr.io/simstudioai/charts/sim --version 1.9.1
+
+helm install sim oci://ghcr.io/simstudioai/charts/sim \
+  --version 1.9.1 \
+  --namespace sim --create-namespace \
+  --set app.env.BETTER_AUTH_SECRET="$BETTER_AUTH_SECRET" \
+  --set app.env.ENCRYPTION_KEY="$ENCRYPTION_KEY" \
+  --set app.env.INTERNAL_API_SECRET="$INTERNAL_API_SECRET" \
+  --set app.env.CRON_SECRET="$CRON_SECRET" \
+  --set postgresql.auth.password="$POSTGRES_PASSWORD"
+```
+
+Always pass `--version`. Without it Helm resolves to the newest published
+version at install time, which makes the same command produce different
+deployments on different days.
+
+To mirror the chart into an internal registry — the usual requirement for an
+air-gapped or internal-only cluster:
+
+```bash
+helm pull oci://ghcr.io/simstudioai/charts/sim --version 1.9.1
+helm push sim-1.9.1.tgz oci://registry.internal.example.com/charts
+```
+
+The container images the chart references are listed in
+[`images.yaml`](./images.yaml); mirror those alongside it.
+
+### From a checkout
 
 ```bash
 helm install sim ./helm/sim \
@@ -132,6 +168,26 @@ helm install sim ./helm/sim --dry-run --debug \
 
 ---
 
+## Verifying the chart
+
+Every published version is signed with [Sigstore](https://www.sigstore.dev/)
+keyless signing and carries a SLSA build-provenance attestation, both stored in
+the registry next to the chart so they survive a mirror.
+
+```bash
+# The signature: proves this chart was signed by a GitHub Actions run in this repo
+cosign verify oci://ghcr.io/simstudioai/charts/sim:1.9.1 \
+  --certificate-identity-regexp '^https://github.com/simstudioai/sim/' \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com
+
+# The provenance: proves which workflow, commit, and runner produced it
+gh attestation verify oci://ghcr.io/simstudioai/charts/sim:1.9.1 --repo simstudioai/sim
+```
+
+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.
+
 ## Upgrading
 
 ```bash