Skip to content

forge logo

forge

Fast, Helm-identical helm dependency build / update for charts whose dependencies live in OCI registries, classic chart repositories (https://…/index.yaml) or local file:// directories.

Get started Usage guide GitHub

forge writes the same charts/*.tgz and Chart.lock that Helm would, so helm template, helm install and helm package keep working unchanged — they just get their dependencies faster.

helm forge dep update ./my-chart   # resolve ranges, download, write Chart.lock
helm forge dep build  ./my-chart   # download exactly what Chart.lock pins
helm template my-release ./my-chart

helm forge … (the plugin) and forge … (the standalone binary) take the same commands and flags.

Why forge

  • Parallel

    Every dependency is fetched concurrently, with global and per-host limits.

    Limits and retries

  • One auth handshake per registry

    The first request to a host runs alone; the token it earns is reused by all the others.

    How it works

  • Content-addressed cache

    Archives are stored by sha256 and shared across charts, aliases and processes. A warm dep build makes zero requests.

    The store

  • Atomic charts/

    Nothing in charts/ changes unless every dependency succeeded.

    Atomic charts/

  • Machine-readable reports

    -o json gives CI a stable error code per failed dependency instead of parsing text.

    JSON output

  • Helm-identical output

    Archive bytes, Chart.lock (apart from generated:) and helm template output are checked against real Helm 3 and Helm 4 in CI.

    Helm is the oracle

Install

Pick how you run Helm. The choice is remembered across the docs.

# git sources can't be signature-verified, so --verify=false is required
helm plugin install https://github.com/mmpyro/forge --version v2.1.0 --verify=false
helm forge --version

helm plugin install https://github.com/mmpyro/forge --version v2.1.0
helm forge --version

os=$(uname -s | tr '[:upper:]' '[:lower:]')
arch=$(uname -m); case $arch in x86_64) arch=amd64 ;; aarch64) arch=arm64 ;; esac
curl -fsSL -o forge "https://github.com/mmpyro/forge/releases/download/v2.1.0/forge-$os-$arch"
chmod +x forge && sudo mv forge /usr/local/bin/
forge --version

Download forge-windows-amd64.exe or forge-windows-arm64.exe, rename it to forge.exe and put it in a directory on your PATH.

forge --version

make build            # → bin/forge (Go 1.25+)
bin/forge --version

Mirrors, checksums, upgrades and troubleshooting: Usage → Install.

What's new in 2.1

  • Inspect dependencies. dep tree shows each dependency's constraint, locked version, source and cache state; dep why NAME explains one of them. Both make no requests. dep outdated compares Chart.lock with what registries offer now, and --fail-if-outdated gates CI on it. See Usage → forge dep tree.
  • Manage the cache. cache ls lists cached charts with size and last use; cache gc --older-than 30d --max-size 2GiB evicts least recently used ones and is safe to run alongside other forge processes. See Usage → forge cache gc.

Release notes and downloads.

What's new in 2.0

  • Chart repositories and file:// dependencies. Besides OCI registries, forge now fetches from classic https://…/index.yaml repositories (including @name references from helm repo add) and packages local file:// charts.
  • -o json output. dep build and dep update can print one JSON report: per-dependency status, digest, size and a classified error code, plus request counts per host. See Usage → JSON output.
  • Distributed as a Helm plugin. Install with helm plugin install, run as helm forge. The Homebrew tap is discontinued.

Benchmark

A parent chart with 50 subcharts (2.4 MiB in total): forge dep build took 4.6 s, helm dependency update --skip-refresh took 30.4 s — about 6.6× faster. forge started with 14 of the 50 charts in its cache; helm was mostly waiting on the network (11 % CPU).

forge vs helm: 4.6 s vs 30.4 s for 50 subcharts

For a reproducible comparison (40 charts, +50 ms latency, cold and warm), run make bench; see Development → Benchmark.

Scope

Supported

  • apiVersion: v2 charts
  • dependencies with repository:
    • oci://… — OCI registries
    • https://… / http://… — classic chart repositories, whether or not they were added with helm repo add
    • @name / alias:name — repositories from Helm's repositories.yaml (credentials and TLS settings are used too)
    • file://… — local chart directories, packaged like Helm does
  • exact versions and semver ranges (same resolver rules as Helm)
  • aliases, conditions/tags, prerelease and build-metadata versions

Not supported (forge exits before any network call)

  • dependencies without a repository (unpacked in charts/) and other schemes (s3://, plugin getters)
  • apiVersion: v1 charts

Not implemented yet: push/pull, package, adaptive concurrency, HTTP/3.

Guides

Guide Read it when you want to…
Usage install forge, run it, set flags, cache it in CI, read its errors, parse its -o json output
Architecture understand how a run works and why it is fast and safe
Development build, test, regenerate goldens, run the compat gate and benchmark