helm-scribe

A CLI tool that generates a Helm parameters table and a values.schema.json (JSON Schema) from an annotated values.yaml. It documents your chart and produces a schema Helm uses to validate values on install and upgrade.

It is a helm-docs alternative that also generates the JSON Schema, and can resolve real Kubernetes API types into the schema.

This tool was inspired by helm-docs and readme-generator-for-helm, which I found helpful, but limited in some ways.

How does it work

helm-scribe parses your values.yaml, extracts parameter metadata from YAML comments, and produces:

1. A formatted markdown table inserted into your README.md between marker comments
2. A values.schema.json file for Helm value validation (JSON Schema draft-07)

Place these markers in your README where the table should appear:

<!-- helm-scribe:start -->
<!-- helm-scribe:end -->

For more information check out the wiki tab.

Quickstart

Installation

Pre-built binaries for Linux, macOS, and Windows (amd64/arm64) are available on the GitHub Releases page.

Or, if you wish to install with go:

go install github.com/miosp/helm-scribe@latest

Add README markers

Insert these where the parameters table should appear:

<!-- helm-scribe:start -->
<!-- helm-scribe:end -->

Annotate values.yaml

# @section Network

# Service port
# @min 1
# @max 65535
port: 80

# Image pull policy
# @type string
# @enum [Always, IfNotPresent, Never]
pullPolicy: IfNotPresent

# Optional description
# @type string?
serviceDescription:

# Internal setting
# @skip
reconcileInterval: 30s

Kubernetes types

Reference a Kubernetes API type with @type k8s:<group>/<version>/<Kind>:

# @type k8s:core/v1/ResourceRequirements
resources: {}

By default k8s-typed fields are treated as partial overlays: the generated schema validates the value's types, enums, and structure but does not require subfields to be present. This matches how Helm values work (values are partial; templates fill in the rest) and keeps the chart's own values valid against the schema it generates.

Append ! to enforce a complete object instead, keeping the upstream required fields (useful when a value is inserted as a whole object rather than exposing individual knobs):

# @type k8s:apps/v1/Deployment!
deployment: {}

The ! marker applies only to k8s: types and is unrelated to the --strict CLI flag.

Run

helm-scribe

This writes a parameters table into your README and generates values.schema.json next to values.yaml.

README table:

Key	Description	Default
port	Service port	80
pullPolicy	Image pull policy	"IfNotPresent"
serviceDescription	Optional description	null

reconcileInterval is excluded by @skip.

Schema: A JSON Schema draft-07 file with types, enum, minimum/maximum, nullable fields, and required-field logic. Helm validates values against this schema during helm install and helm upgrade.

GitHub Action

Run helm-scribe in CI with the Miosp/helm-scribe Action.

Generate mode

Regenerate the table and schema, then let a later step commit or open a PR:

- uses: actions/checkout@v4
- uses: Miosp/helm-scribe@v0
  with:
    chart-directory: charts/my-app

Check mode

Fail a pull request when the generated files are out of date. Requires a checkout so the Action can diff the working tree:

- uses: actions/checkout@v4
- uses: Miosp/helm-scribe@v0
  with:
    chart-directory: charts/my-app
    check: "true"

Inputs

Input	Default	Description
chart-directory	.	Chart directory to process.
values-file	unset	Path to the values file (--values-file).
readme-file	unset	Path to the README file (--readme-file).
config	unset	Path to the config file (--config).
truncate-length	unset	Max default length before truncation (--truncate-length).
heading-level	unset	Section heading level, 1-6 (--heading-level).
schema-file	unset	Path to the schema output file (--schema-file).
dry-run	false	Print to stdout instead of writing (--dry-run).
no-pretty	false	Disable table alignment (--no-pretty).
schema-only	false	Only generate the schema (--schema-only).
readme-only	false	Only generate the README (--readme-only).
strict	false	Treat warnings as errors (--strict).
type-column	false	Show the type column (--type-column).
version	0	Version constraint: 0, 0.3, 0.3.1, or latest.
check	false	Fail when generated files drift.
binary	unset	Advanced: use a prebuilt binary instead of downloading.

Outputs

Output	Description
version	Resolved release tag used (local with binary).
drift	true/false; whether check mode found stale files.
changed-files	Newline-separated list of files that drifted.