helm-git

The Helm downloader plugin that provides GIT protocol support.

It fits multiple use cases:

• Need to keep charts private
• Doesn't want to package charts before installing
• Charts in a sub-path, or with another ref than master
• Pull values files directly from (private) Git repository

Install

Use helm CLI to install this plugin:

helm plugin install https://github.com/aslafy-z/helm-git --version 1.5.2

To use the plugin, you only need git. If you want to build the plugin from source, or you want to contribute to the plugin, please see these instructions.

Uninstall

helm plugin remove helm-git

Usage

helm-git will package any chart that is not so you can directly reference paths to original charts.

Here's the Git urls format, followed by examples:

git+https://[username[:password]@]provider.com/[@path/to/charts][?[ref=git-ref][&sparse=1][&depupdate=0][&package=0]] git+ssh://[username@]provider.com/[@path/to/charts][?[ref=git-ref][&sparse=1][&depupdate=0][&package=0]] git+file://[@path/to/charts][?[ref=git-ref][&sparse=1][&depupdate=0][&package=0]]

git+https://github.com/jetstack/cert-manager@deploy/charts?ref=v0.6.2&sparse=0 git+ssh://git@github.com/jetstack/cert-manager@deploy/charts?ref=v0.6.2&sparse=1 git+ssh://git@github.com/jetstack/cert-manager@deploy/charts?ref=v0.6.2 git+https://github.com/istio/istio@install/kubernetes/helm?ref=1.5.4&sparse=0&depupdate=0 git+https://github.com/bitnami/charts@bitnami/wordpress?ref=master&sparse=0&depupdate=0&package=0 git+https://gitlab.com/one-touch-pipeline/weskit/helm-deployment?ref=ee259f65191cef10855438321ce99e37873918b6

Add your repository:

helm repo add cert-manager git+https://github.com/jetstack/cert-manager@deploy/charts?ref=v0.6.2

You can use it as any other Helm chart repository. Try:

$ helm search repo cert-manager NAME CHART VERSION APP VERSION DESCRIPTION cert-manager/cert-manager v0.6.6 v0.6.2 A Helm chart for cert-manager

$ helm install cert-manager/cert-manager --version 0.6.6

Fetching also works:

helm fetch cert-manager/cert-manager --version 0.6.6 helm fetch 'git+https://github.com/jetstack/cert-manager@deploy/charts/cert-manager-v0.6.6.tgz?ref=v0.6.2'

Showing chart information:

helm show chart cert-manager/cert-manager helm show values cert-manager/cert-manager helm show chart 'git+https://github.com/jetstack/cert-manager@deploy/charts/cert-manager-v0.6.6.tgz?ref=v0.6.2' helm show values 'git+https://github.com/jetstack/cert-manager@deploy/charts/cert-manager-v0.6.6.tgz?ref=v0.6.2'

Pulling value files:

helm install . -f git+https://github.com/aslafy-z/helm-git@tests/fixtures/example-chart/values.yaml

Environment variables

name|description|default --------|---------------|----------- HELMGITHELMBIN|Path to the helm binary. If not set, $HELMBIN will be used.|helm HELMGITDEBUG|Setting this value to 1 increases helm-git log level. |0 HELMGITTRACE|Setting this value to 1 increases helm-git log level to the maximum and keeps temporary dirs at shutdown. |0 HELMGITREPO_CACHE|Path to use as a Git repository cache to avoid fetching repos more than once. If empty, caching of Git repositories is disabled. The directory will be created automatically if it doesn't exist.|"" HELMGITCHART_CACHE|Path to use as a Helm chart cache to avoid re-packaging/re-indexing charts. If empty, caching of Helm charts is disabled. The directory will be created automatically if it doesn't exist.|"" HELMGITCHARTCACHESTRATEGY|Strategy to use when caching charts. If repo then all charts from the same repo will use the same cache. If chart, caching will only build single chart for each chart if package is 1. Any other values preserves the default behavior: each chart has its own cache and all packages are built every time if package is 1.|""

Arguments

name|description|default --------|---------------|----------- ref|Set git ref to a branch or tag. Also works for commits with sparse=0.|Discover from remote sparse|Set git strategy to sparse. Will try to fetch only the needed commits for the target path. If set to 0, default git strategy will be used.|1 depupdate|Run helm dependency update on the retrieved chart. If set to 0, this step is skipped.|1 package|Run helm package on the retrieved chart. If set to 0, this step is skipped.|1

Note on Git authentication

As this plugin uses git CLI to clone repos. You can configure private access in the same manner that with any git repo.

• using ssh: Start a ssh-agent daemon
• using https: Use a credentials helper
• using helm credentials: Use helm repo add --username user --password pass to provide credentials

Helm Credentials Support

Note: This feature requires Helm v3.14.0 or later.

This plugin supports Helm's built-in credential passing mechanism. When you use helm repo add with --username and --password flags, the plugin automatically configures git to use these credentials:

# Add a repository with credentials
helm repo add my-repo --username myuser --password mypass git+https://github.com/company/charts@charts?ref=main
The credentials are automatically used for git operations
helm fetch my-repo/my-chart

Note: When both Helm credentials and existing git authentication (SSH keys, credential helpers) are available, Helm credentials take precedence for the current operation.

Note on SSH relative paths

Helm parses the input URL before passing it down to the Helm downloader plugins (which is the type of this helm-git plugin). It does so by using the net/url.Parse Golang method, which does not support the full IETF specification. Specifically, it does not support : as the first path separator like in git+ssh://git@github.com:aslafy-z/helm-git as Git supports it. This means that you'll have to use an absolute path instead by using the / separator as in git+ssh://git@github.com/aslafy-z/helm-git. This should not be an issue in most case as major hosts supports the use of absolute paths instead of relative ones. If this becomes an issue for you, please open an issue and we may implement something to fill the gap until Golang or Helm does so.

Troubleshooting

You can enable debug output by setting HELMGITDEBUG environment variable to 1:

HELMGITDEBUG=1 helm repo add cert-manager git+https://github.com/jetstack/cert-manager@deploy/charts?ref=v0.6.2

In order to debug in a more efficient maneer, I advise you use helm fetch instead of helm repo add.

You can enable more advanced output by setting HELMGITTRACE environment variable to 1.

Contributing

Contributions are welcome! Please see these instructions that will help you to develop the plugin.

Alternatives

License

Apache License 2.0