# Generate a Helm Chart README With helm-docs and Fail CI When It Is Stale

Yes. An agent moves your chart's hand-written values table into helm-docs comments and a template, regenerates the README, and adds a CI check for drift.

[Run this on Rush](https://cloud.getrush.ai/run/add-helm-docs/helm/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads the chart before it touches the README. In a chart like `charts/podinfo` in stefanprodan/podinfo, `Chart.yaml` is `apiVersion: v1`, `version: 6.17.0`, `appVersion: 6.17.0`, with `home`, `sources`, one maintainer and `kubeVersion: ">=1.23.0-0"`. `values.yaml` has about forty top-level keys: `replicaCount`, `logLevel`, `host`, `backend`, `backends`, `image` (repository `ghcr.io/stefanprodan/podinfo`, tag, `pullPolicy`, `pullSecrets`), `ui`, `faults`, `service` (ports `9797`, `9898`, `9999`, `nodePort 31198`, `trafficDistribution`), `h2c`, `config`, `extraArgs`, `extraEnvs`, `tls`, `certificate`, `hpa`, `cache`, `redis`, `serviceAccount`, `securityContext`, `ingress`, `httpRoute`, `grpcRoute`, `serviceMonitor`, `resources`, `nodeSelector`, `tolerations`, `affinity`, `podAnnotations`, `podDisruptionBudget` and `probes`. Three keys (`ingress`, `httpRoute`, `grpcRoute`) already carry a `# -- ...` comment in the exact form helm-docs reads; the other 34 comment lines are plain `#` notes.

The chart's `README.md` has three sections: `## Installing the Chart` (the OCI install from `ghcr.io/stefanprodan/charts/podinfo`, the Cosign verification command and the GitHub Pages repository), `## Uninstalling the Chart`, and `## Configuration`, a hand-maintained table of 84 parameter rows with defaults and descriptions. There is no `README.md.gotmpl`. `.github/workflows/test.yml` runs `make test`, `helm lint ./charts/podinfo/`, `helm template` piped into `flux-schema validate`, the Kustomize and Timoni checks, and ends with a step that fails when `git diff --stat` is not empty, printing `run make test and commit changes`. That last step is the hook the agent uses.

The agent installs the helm-docs release binary and starts with the values file: for each of the 84 table rows it adds a `# -- <description>` comment above the matching key, keeping the table's wording, and converts the plain `#` notes that describe a key into the same form. It lists the rows whose key no longer exists in `values.yaml` and the keys that have no row, so nothing is silently dropped or invented, and leaves descriptions empty where the table had none. Then it writes `charts/podinfo/README.md.gotmpl`: the Installing and Uninstalling sections copied verbatim, followed by `{{ template "chart.valuesSection" . }}`, with `chart.header` and `chart.description` from `Chart.yaml` at the top. `helm-docs --chart-search-root charts` regenerates `README.md`, and the agent diffs it against the old one row by row.

For the check, it adds a `helm-docs` target to the `Makefile` and a step in `test.yml`, after `helm lint`, that runs the same command; because the existing final step already fails on a dirty tree, a pull request that changes `values.yaml` without regenerating the README fails with the README diff in the log and the message the maintainers already know. The agent changes no template and no value, and runs `helm lint` and `helm template` once more to show the chart renders as before.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add helm-docs to this repository's Helm chart. Read Chart.yaml, values.yaml, the existing README and the CI workflow first. Move every description from the README's hand-written parameters table into a `# --` comment above the matching key in values.yaml, keeping the wording; list any table row whose key no longer exists and any key with no row. Write a README.md.gotmpl that keeps the existing install and uninstall sections verbatim and renders the values table from the comments, regenerate the README, and diff it against the old one. Add a Makefile target and a CI step that regenerate the README so the workflow's existing dirty-tree check fails when the docs are stale. Change no template and no default value. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

What comes back is a pull request on its own branch that adds `charts/podinfo/README.md.gotmpl`, changes `charts/podinfo/values.yaml` (comments only, no value moved), `charts/podinfo/README.md` (now generated), `Makefile` and `.github/workflows/test.yml`. The description has the row-by-row diff of the old and new tables, the list of stale rows and undocumented keys, and the `helm lint` and `helm template` output from the sandbox showing the rendered manifests are unchanged.

The run's record keeps every command with its output, including the helm-docs version installed, the regeneration and the two Helm runs, so a reviewer can confirm the README was generated and not edited, and that the defaults column matches `values.yaml` exactly.

Before merging, a reviewer reads the stale-rows list and deletes or restores each, writes descriptions for the undocumented keys the agent left blank, and decides whether the release workflow that publishes the chart should also run `helm-docs` so a published chart never ships a README behind its values.

## Run it on every chart values change

The setup is one `POST /o/{org}/sessions` with this body and the repository in `resources`, started from a terminal; the run continues in its sandbox after you close the window, and a follow-up (`POST /o/{org}/sessions/{id}/messages`) can change the template layout without starting over. After the merge, the CI step does the ongoing work: every pull request that touches `values.yaml` has to regenerate the README or it fails.

For a repository with many charts, an automation in the Project with a `github` trigger on `pull_request.opened` and `pull_request.synchronize` can run a shorter prompt that regenerates the README for the charts the pull request touched and pushes the result to its branch, with the event added after the prompt so the agent knows which pull request it is.

## Why run it on Rush?

A chart README goes stale one value at a time, and moving to a generator by hand means copying dozens of descriptions into comments without losing or changing any. The agent does that copy mechanically, reports every mismatch between the table and the values file instead of guessing, and keeps the prose sections exactly as written.

The sandbox has Helm and the helm-docs binary the agent installs, so the regeneration, `helm lint` and `helm template` run for real and the output stays in the run's record. Several charts in a repository, or several repositories, can be done at once in separate sandboxes, each with its own pull request.

## Frequently asked questions

### Will it change my chart's values or templates?

No. Only comments are added to `values.yaml`, and the agent runs `helm template` before and after to show the rendered manifests are identical. Templates, `Chart.yaml` and the hooks are untouched.

### What happens to the parts of my README that are not the table?

They move into `README.md.gotmpl` verbatim, so the install commands, the signature verification and the uninstall section render exactly as they did. Only the parameters table is generated from now on.

### What if the table and values.yaml disagree?

The agent lists each row whose key is gone and each key without a row in the pull request and leaves the description blank rather than inventing one. You decide which rows to drop and what the undocumented keys mean.

### How does CI catch a stale README?

The workflow regenerates the README with helm-docs and then runs its existing check that the working tree is clean. A pull request that changed `values.yaml` without regenerating fails with the README diff in the log. There is no separate tool to learn.

## More Helm jobs

- [Add Helm Test Hooks to a Chart from a Linear Issue](https://getrush.ai/run/add-helm-tests/helm/)
- [Add a Horizontal Pod Autoscaler to a Helm Chart](https://getrush.ai/run/add-horizontal-pod-autoscaler/helm/)
- [Add imagePullSecrets to a Helm Chart for a Private Registry](https://getrush.ai/run/add-image-pull-secrets/helm/)

## More jobs like this: Hand off a long task

- [Add a Horizontal Pod Autoscaler to Kustomize Deployments](https://getrush.ai/run/add-horizontal-pod-autoscaler/kustomize/)
- [Add HTTP Timeouts to a Go CLI](https://getrush.ai/run/add-http-timeouts/go-cli/)
- [Add i18n to a Blazor Web App](https://getrush.ai/run/add-i18n/blazor/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
