Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mridang/semantic-release-helm

A plugin for semantic-release to simplify releasing Helm charts
https://github.com/mridang/semantic-release-helm

helm helm-charts helm-docs helm-release release-automation semantic-release semantic-release-plugin

Last synced: about 1 month ago
JSON representation

A plugin for semantic-release to simplify releasing Helm charts

Awesome Lists containing this project

README 

          
# Semantic Release - Helm



A [semantic-release](https://github.com/semantic-release/semantic-release)

plugin to automatically package and publish Helm charts to an

OCI-compliant registry or publish them to GitHub Pages.



This plugin automates the final step of a Helm chart release workflow.

It updates the `version` in your `Chart.yaml` file, validates and templates

your chart, regenerates the chart `README.md` via `helm-docs`, packages the

chart into a `.tgz`, and after `semantic-release` publishes a new Git tag,

it pushes the packaged chart either to your configured OCI registry or to

GitHub Pages. This eliminates the need for manual commands or scripts, ensuring

your Helm charts are always up-to-date and published consistently.



## Why?



Automating the release of a Helm chart involves more than just creating a Git tag.

For a new version to be consumable, it must be validated, packaged, and pushed

to a chart registry. This final synchronization step is a common point of friction

in an otherwise automated pipeline.



Without this plugin, developers typically face one of two issues:



- **Manual Helm Workflow:** The most common method is manually running

  `helm lint`, `helm package`, and `helm push`. This adds toil and

  creates opportunities for mistakes or skipped steps.

- **Incomplete Automation:** Other existing plugins may bump the version in

  `Chart.yaml`, but they often stop there. They do not handle linting,

  templating, regenerating docs, or pushing to OCI/GitHub Pages. This leaves

  a manual gap in the release process.

- **Missing Validation:** Many pipelines skip running `helm lint` and

  `helm template`, which can allow broken charts to be released. This

  results in consumers discovering issues after the release, rather than

  catching them during CI.



This plugin provides a lightweight and direct solution by running Helm and

helm-docs inside Docker. Instead of relying on ad-hoc scripts, it ensures

that after `semantic-release` successfully creates a new release, your Helm

chart is linted, templated, documented, packaged, and immediately published

to your target registry.



## Installation



Install using NPM with the following command:



```sh

npm install --save-dev @mridang/semantic-release-helm

```



## Usage



To use this plugin, add it to your semantic-release configuration file

(e.g., `.releaserc.js`, `release.config.js`, or in your `package.json`).



The plugin’s `prepare` step modifies your `Chart.yaml`, regenerates

the `README.md` file, and packages the chart. For these changes to be

included in the release commit, the plugin should be placed **before**

`@semantic-release/git` and `@semantic-release/github` in the `plugins` array.



> [!IMPORTANT]

> This plugin updates the `version` field in your `Chart.yaml` file during the

> `prepare` step. For this change to be included in your release commit,

> you **must** configure the `@semantic-release/git` plugin to add

> `Chart.yaml` (and optionally `README.md`) to its `assets` array.



### Example Configuration (`.releaserc.js`)



```javascript

module.exports = {

  branches: ['main', 'next'],

  plugins: [

    '@semantic-release/commit-analyzer',

    [

      '@mridang/semantic-release-helm',

      {

        chartPath: 'charts/app',

        ociRepo: 'oci://ghcr.io/my-org/charts',

        ociUsername: process.env.OCI_USERNAME,

        ociPassword: process.env.OCI_PASSWORD,

        ociInsecure: false,

        helmImage: 'alpine/helm:3.15.2',

        docsImage: 'jnorwood/helm-docs:v1.14.2',

        docsArgs: ['--template-files', 'README.md'],

        githubPages: true,

      },

    ],

    '@semantic-release/release-notes-generator',

    '@semantic-release/changelog',

    '@semantic-release/github',

    [

      '@semantic-release/git',

      {

        assets: [

          'charts/app/Chart.yaml',

          'charts/app/README.md',

          'CHANGELOG.md',

        ],

        message:

          'chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}',

      },

    ],

  ],

};

```



### Configuration Options



All options are case-sensitive and lowercased in the JSON configuration.



- **`chartPath` (string, required):**

  Path to the chart directory containing `Chart.yaml`.



- **`ociRepo` (string, optional):**

  The target OCI repository (e.g., `oci://ghcr.io/my-org/charts`).

  When configured, the packaged chart will be pushed to this repository.



- **`ociUsername` (string, optional):**

  Username for authenticating with the OCI registry. If not provided,

  anonymous push will be attempted (not recommended).



- **`ociPassword` (string, optional):**

  Password or token for authenticating with the OCI registry.



- **`ociInsecure` (boolean, optional):**

  If `true`, allows pushing to insecure HTTP registries. Default: `false`.



- **`helmImage` (string, optional):**

  Custom Docker image for running Helm commands. Default:

  `alpine/helm:3.15.2`.



- **`docsImage` (string, optional):**

  Custom Docker image for running helm-docs. Default:

  `jnorwood/helm-docs:v1.14.2`.



- **`docsArgs` (array of strings, optional):**

  Additional arguments for helm-docs. Default:

  `['--template-files', 'README.md']`.



- **`githubPages` (boolean, optional):**

  If `true`, the packaged chart will also be pushed to the `gh-pages` branch

  of the repository, making it available as a Helm chart repo over GitHub Pages.



## OCI Registry Publishing



When you provide `ociRepo`, the plugin will package your chart into a `.tgz`

and execute `helm push` to the specified OCI-compliant registry. Credentials

are taken from `ociUsername` and `ociPassword`. This enables direct integration

with container registries such as GitHub Container Registry (`ghcr.io`),

Amazon ECR, or Docker Hub (if they support OCI artifacts).



## GitHub Pages Publishing



If `githubPages` is enabled, the plugin will push the packaged chart to the

`gh-pages` branch of the repository. This is useful if you want to host

your Helm charts via GitHub Pages as a traditional Helm chart repository.

Consumers can then add your repo with:



```sh

helm repo add my-org https://my-org.github.io/my-repo/

```



## Known Issues



- None.



## Useful links



- **[Helm](https://helm.sh/):** The Kubernetes package manager.

- **[helm-docs](https://github.com/norwoodj/helm-docs):** Tool for automatically generating chart documentation.



## Contributing



If you have suggestions for how this plugin could be improved, or

want to report a bug, open an issue — we’d love all and any

contributions.



## License



Apache License 2.0 © 2024 Mridang Agarwalla