DaedalusG · Oct 14, 2026
diff --git a/.buildkite/pipeline.yaml b/.buildkite/pipeline.yaml
@@ -26,6 +26,16 @@ steps:
       - "[[ -z $(git status -s) ]]"
     agents: { queue: standard }
 
+  # Releases rewrite image digests and the registry in values.yaml. If a README
+  # renders either, the release branch fails the helm-docs check above.
+  - label: ":book: Verify READMEs do not render release-managed values"
+    command: |
+      if grep -rnE --include=README.md '@sha256:[0-9a-f]{64}|index\.docker\.io/sourcegraph' charts/; then
+        echo "Add a '# @default --' annotation to these values in values.yaml, then run ./scripts/helm-docs.sh"
+        exit 1
+      fi
+    agents: { queue: standard }
+
   - label: "(internal) Release: test"
     if: build.branch =~ /^internal\/release-.*/
     plugins:

diff --git a/AGENTS.md b/AGENTS.md
@@ -9,3 +9,5 @@ After making changes to any `values.yaml` file, regenerate the helm docs and ver
 ```
 
 If the README was updated, stage and commit the changes alongside your other modifications.
+
+Releases rewrite every pinned image `defaultTag` and the `sourcegraph.image.repository` registry in `values.yaml`. When adding one of these values, give it a `# -- ` description and a `# @default -- ` annotation, like the existing images, so the README does not change on release.
diff --git a/charts/sourcegraph-executor/dind/README.md b/charts/sourcegraph-executor/dind/README.md
@@ -71,7 +71,7 @@ In addition to the documented values, the `executor` and `private-docker-registr
 | executor.frontendExistingSecret | string | `""` | Name of existing k8s Secret to use for frontend password. The k8s Secret must contain the key EXECUTOR_FRONTEND_PASSWORD matching the site config executors.accessToken value. frontendPassword is ignored if this is set. |
 | executor.frontendPassword | string | `""` | The shared secret configured in the Sourcegraph instance site config under executors.accessToken. Required if frontendExistingSecret is not configured. |
 | executor.frontendUrl | string | `""` | The external URL of the Sourcegraph instance. Required. **Recommended:** set to the internal service endpoint (e.g. `http://sourcegraph-frontend.sourcegraph.svc.cluster.local:30080` if Sourcegraph is deployed in the `sourcegraph` namespace). This will avoid unnecessary network charges as traffic will stay within the local network. |
-| executor.image.defaultTag | string | `"6.0.0@sha256:0be94a7c91f8273db10fdf46718c6596340ab2acc570e7b85353806e67a27508"` |  |
+| executor.image.defaultTag | string | `<appVersion>@sha256:<digest>`, pinned by each release | Docker image tag for the `executor` image |
 | executor.image.name | string | `"executor"` |  |
 | executor.log.format | string | `"json"` |  |
 | executor.log.level | string | `"warn"` | Possible values are dbug, info, warn, eror, crit. |
@@ -95,7 +95,7 @@ In addition to the documented values, the `executor` and `private-docker-registr
 | sourcegraph.affinity | object | `{}` | Affinity, learn more from the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) |
 | sourcegraph.image.defaultTag | string | `"{{ .Chart.AppVersion }}"` | Global docker image tag |
 | sourcegraph.image.pullPolicy | string | `"IfNotPresent"` | Global docker image pull policy |
-| sourcegraph.image.repository | string | `"index.docker.io/sourcegraph"` | Global docker image registry or prefix |
+| sourcegraph.image.repository | string | Sourcegraph's public Docker Hub registry | Global docker image registry or prefix |
 | sourcegraph.image.useGlobalTagAsDefault | bool | `false` | When set to true, sourcegraph.image.defaultTag is used as the default defaultTag for all services, instead of service-specific default defaultTags |
 | sourcegraph.imagePullSecrets | list | `[]` | Mount named secrets containing docker credentials |
 | sourcegraph.labels | object | `{}` | Add a global label to all resources |

diff --git a/charts/sourcegraph-executor/dind/values.yaml b/charts/sourcegraph-executor/dind/values.yaml
@@ -8,6 +8,7 @@ sourcegraph:
     # -- Global docker image pull policy
     pullPolicy: IfNotPresent
     # -- Global docker image registry or prefix
+    # @default -- Sourcegraph's public Docker Hub registry
     repository: index.docker.io/sourcegraph
     # -- When set to true, sourcegraph.image.defaultTag is used as the default defaultTag for all services, instead of service-specific default defaultTags
     useGlobalTagAsDefault: false
@@ -111,6 +112,8 @@ executor:
   # Each queue can override this with its own resources field.
   resources: {}
   image:
+    # -- Docker image tag for the `executor` image
+    # @default -- `<appVersion>@sha256:<digest>`, pinned by each release
     defaultTag: 6.0.0@sha256:0be94a7c91f8273db10fdf46718c6596340ab2acc570e7b85353806e67a27508
     name: "executor"
   replicaCount: 1

diff --git a/charts/sourcegraph-executor/k8s/README.md b/charts/sourcegraph-executor/k8s/README.md
@@ -66,7 +66,7 @@ In addition to the documented values, the `executor` and `private-docker-registr
 | executor.frontendExistingSecret | string | `""` | Name of existing k8s Secret to use for frontend password The name of the secret must match `executor.name`, i.e., the name of the helm release used to deploy the helm chart. The k8s Secret must contain the key `EXECUTOR_FRONTEND_PASSWORD` matching the site config `executors.accessToken` value. `executor.frontendPassword` is ignored if this is enabled. |
 | executor.frontendPassword | string | `""` | The shared secret configured in the Sourcegraph instance site config under executors.accessToken. Required if `executor.frontendExistingSecret`` is not configured. |
 | executor.frontendUrl | string | `""` | The external URL of the Sourcegraph instance. Required. **Recommended:** set to the internal service endpoint (e.g. `http://sourcegraph-frontend.sourcegraph.svc.cluster.local:30080` if Sourcegraph is deployed in the `sourcegraph` namespace). This will avoid unnecessary network charges as traffic will stay within the local network. |
-| executor.image.defaultTag | string | `"6.0.0@sha256:6dc771a0c281a41ef676213f2f84a63d99045cf2e58d43022554a8022070ed65"` |  |
+| executor.image.defaultTag | string | `<appVersion>@sha256:<digest>`, pinned by each release | Docker image tag for the `executor-kubernetes` image |
 | executor.image.name | string | `"executor-kubernetes"` |  |
 | executor.kubeconfigPath | string | `""` | The path to the kubeconfig file. If not specified, the in-cluster config is used. |
 | executor.kubernetesJob.deadline | string | `"1200"` | The number of seconds after which a Kubernetes job will be terminated. |
@@ -107,7 +107,7 @@ In addition to the documented values, the `executor` and `private-docker-registr
 | sourcegraph.affinity | object | `{}` | Affinity, learn more from the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) |
 | sourcegraph.image.defaultTag | string | `"{{ .Chart.AppVersion }}"` | Global docker image tag |
 | sourcegraph.image.pullPolicy | string | `"IfNotPresent"` | Global docker image pull policy |
-| sourcegraph.image.repository | string | `"index.docker.io/sourcegraph"` | Global docker image registry or prefix |
+| sourcegraph.image.repository | string | Sourcegraph's public Docker Hub registry | Global docker image registry or prefix |
 | sourcegraph.image.useGlobalTagAsDefault | bool | `false` | When set to true, sourcegraph.image.defaultTag is used as the default defaultTag for all services, instead of service-specific default defaultTags |
 | sourcegraph.imagePullSecrets | list | `[]` | Mount named secrets containing docker credentials |
 | sourcegraph.labels | object | `{}` | Add a global label to all resources |

diff --git a/charts/sourcegraph-executor/k8s/values.yaml b/charts/sourcegraph-executor/k8s/values.yaml
@@ -8,6 +8,7 @@ sourcegraph:
     # -- Global docker image pull policy
     pullPolicy: IfNotPresent
     # -- Global docker image registry or prefix
+    # @default -- Sourcegraph's public Docker Hub registry
     repository: index.docker.io/sourcegraph
     # -- When set to true, sourcegraph.image.defaultTag is used as the default defaultTag for all services, instead of service-specific default defaultTags
     useGlobalTagAsDefault: false
@@ -40,6 +41,8 @@ executor:
   # -- Whether to configure the necessary RBAC resources. Required only once for all executor deployments.
   configureRbac: true
   image:
+    # -- Docker image tag for the `executor-kubernetes` image
+    # @default -- `<appVersion>@sha256:<digest>`, pinned by each release
     defaultTag: 6.0.0@sha256:6dc771a0c281a41ef676213f2f84a63d99045cf2e58d43022554a8022070ed65
     name: "executor-kubernetes"
   resources:

diff --git a/charts/sourcegraph-migrator/README.md b/charts/sourcegraph-migrator/README.md
@@ -32,7 +32,7 @@ helm repo add sourcegraph https://helm.sourcegraph.com/release
 
 By default, the [sourcegraph/sourcegraph-migrator] chart references database credentials from a Kubernetes `Secret` created by the parent [sourcegraph/sourcegraph] chart. If you provide your own `Secret` resources, update the `codeInsightsDB.auth.existingSecret`, `codeIntelDB.auth.existingSecret` and `pgsql.auth.existingSecret` settings in values.yaml to match. Learn more about [using your own PostgreSQL server].
 
-You should consult the list of available [migrator commands]. Below is some example usage.
+You should consult the list of available [migrator commands]. Below is some example usage. Replace `<chart-version>` with the chart version that matches your Sourcegraph version.
 
 ### Run database migration
 
@@ -42,7 +42,7 @@ You should consult the list of available [migrator commands]. Below is some exam
 - Perform initial migrations against external PostgreSQL databases prior to the Sourcegraph deployment
 
 ```sh
-helm upgrade --install -f <your-override-file.yaml> --version 5.11.0 sg-migrator sourcegraph/sourcegraph-migrator
+helm upgrade --install -f <your-override-file.yaml> --version <chart-version> sg-migrator sourcegraph/sourcegraph-migrator
 ```
 
 ### Add a migration log entry
@@ -52,7 +52,7 @@ helm upgrade --install -f <your-override-file.yaml> --version 5.11.0 sg-migrator
 Add an entry to the migration log after a site administrator has explicitly applied the contents of a migration file, learn more about troubleshooting a [dirty database].
 
 ```sh
-helm upgrade --install -f <your-override-file.yaml> --set "migrator.args={add-log,-db=frontend,-version=1528395834}" --version 5.11.0 sg-migrator sourcegraph/sourcegraph-migrator
+helm upgrade --install -f <your-override-file.yaml> --set "migrator.args={add-log,-db=frontend,-version=1528395834}" --version <chart-version> sg-migrator sourcegraph/sourcegraph-migrator
 ```
 
 ## Rendering manifests for kubectl deployment
@@ -80,15 +80,15 @@ In addition to the documented values, the `migrator` service also supports the f
 | migrator.args | list | `["up","-db=all"]` | Override default `migrator` container args Available commands can be found at https://docs.sourcegraph.com/admin/how-to/manual_database_migrations |
 | migrator.containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"readOnlyRootFilesystem":true,"runAsGroup":101,"runAsUser":100}` | Security context for the `migrator` container, learn more from the [Kubernetes documentation](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/#set-the-security-context-for-a-container) |
 | migrator.env | object | `{}` | Environment variables for the `migrator` container |
-| migrator.image.defaultTag | string | `"6.0.0@sha256:ec295eb0b743da6bf56777ca6524972267a5c442b0288095e2fe12fce38ebacc"` | Docker image tag for the `migrator` image |
+| migrator.image.defaultTag | string | `<appVersion>@sha256:<digest>`, pinned by each release | Docker image tag for the `migrator` image |
 | migrator.image.name | string | `"migrator"` | Docker image name for the `migrator` image |
 | migrator.resources | object | `{"limits":{"cpu":"500m","memory":"100M"},"requests":{"cpu":"100m","memory":"50M"}}` | Resource requests & limits for the `migrator` container, learn more from the [Kubernetes documentation](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/) |
 | pgsql.auth.existingSecret | string | `""` | Name of existing secret to use for pgsql credentials This should match the setting in the sourcegraph chart values |
 | pgsql.name | string | `"pgsql"` |  |
 | sourcegraph.affinity | object | `{}` | Affinity, learn more from the [Kubernetes documentation](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) |
 | sourcegraph.image.defaultTag | string | `"{{ .Chart.AppVersion }}"` | Global docker image tag |
 | sourcegraph.image.pullPolicy | string | `"IfNotPresent"` | Global docker image pull policy |
-| sourcegraph.image.repository | string | `"index.docker.io/sourcegraph"` | Global docker image registry or prefix |
+| sourcegraph.image.repository | string | Sourcegraph's public Docker Hub registry | Global docker image registry or prefix |
 | sourcegraph.image.useGlobalTagAsDefault | bool | `false` | When set to true, sourcegraph.image.defaultTag is used as the default defaultTag for all services, instead of service-specific default defaultTags |
 | sourcegraph.imagePullSecrets | list | `[]` | Mount named secrets containing docker credentials |
 | sourcegraph.labels | object | `{}` | Add a global label to all resources |

diff --git a/charts/sourcegraph-migrator/README.md.gotmpl b/charts/sourcegraph-migrator/README.md.gotmpl
@@ -32,7 +32,7 @@ helm repo add sourcegraph https://helm.sourcegraph.com/release
 
 By default, the [sourcegraph/sourcegraph-migrator] chart references database credentials from a Kubernetes `Secret` created by the parent [sourcegraph/sourcegraph] chart. If you provide your own `Secret` resources, update the `codeInsightsDB.auth.existingSecret`, `codeIntelDB.auth.existingSecret` and `pgsql.auth.existingSecret` settings in values.yaml to match. Learn more about [using your own PostgreSQL server].
 
-You should consult the list of available [migrator commands]. Below is some example usage.
+You should consult the list of available [migrator commands]. Below is some example usage. Replace `<chart-version>` with the chart version that matches your Sourcegraph version.
 
 ### Run database migration
 
@@ -42,7 +42,7 @@ You should consult the list of available [migrator commands]. Below is some exam
 - Perform initial migrations against external PostgreSQL databases prior to the Sourcegraph deployment
 
 ```sh
-helm upgrade --install -f <your-override-file.yaml> --version {{ template "chart.version" . }} sg-migrator sourcegraph/sourcegraph-migrator
+helm upgrade --install -f <your-override-file.yaml> --version <chart-version> sg-migrator sourcegraph/sourcegraph-migrator
 ```
 
 ### Add a migration log entry
@@ -52,7 +52,7 @@ helm upgrade --install -f <your-override-file.yaml> --version {{ template "chart
 Add an entry to the migration log after a site administrator has explicitly applied the contents of a migration file, learn more about troubleshooting a [dirty database].
 
 ```sh
-helm upgrade --install -f <your-override-file.yaml> --set "migrator.args={add-log,-db=frontend,-version=1528395834}" --version {{ template "chart.version" . }} sg-migrator sourcegraph/sourcegraph-migrator
+helm upgrade --install -f <your-override-file.yaml> --set "migrator.args={add-log,-db=frontend,-version=1528395834}" --version <chart-version> sg-migrator sourcegraph/sourcegraph-migrator
 ```
 
 ## Rendering manifests for kubectl deployment

diff --git a/charts/sourcegraph-migrator/values.yaml b/charts/sourcegraph-migrator/values.yaml
@@ -8,6 +8,7 @@ sourcegraph:
     # -- Global docker image pull policy
     pullPolicy: IfNotPresent
     # -- Global docker image registry or prefix
+    # @default -- Sourcegraph's public Docker Hub registry
     repository: index.docker.io/sourcegraph
     # -- When set to true, sourcegraph.image.defaultTag is used as the default defaultTag for all services, instead of service-specific default defaultTags
     useGlobalTagAsDefault: false
@@ -104,6 +105,7 @@ pgsql:
 migrator:
   image:
     # -- Docker image tag for the `migrator` image
+    # @default -- `<appVersion>@sha256:<digest>`, pinned by each release
     defaultTag: 6.0.0@sha256:ec295eb0b743da6bf56777ca6524972267a5c442b0288095e2fe12fce38ebacc
     # -- Docker image name for the `migrator` image
     name: "migrator"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -9,3 +9,5 @@ After making changes to any `values.yaml` file, regenerate the helm docs and ver
		```

		If the README was updated, stage and commit the changes alongside your other modifications.

		Releases rewrite every pinned image `defaultTag` and the `sourcegraph.image.repository` registry in `values.yaml`. When adding one of these values, give it a `# -- ` description and a `# @default -- ` annotation, like the existing images, so the README does not change on release.