Manual Helm Chart Release

This guide explains how to manually trigger the build and publication of a Helm chart to the OCI registry (Docker Hub).

Overview

Helm charts are published to Docker Hub as OCI artifacts. The chart version follows the pattern:

<MAVEN_VERSION>-RELEASE

For example, if the project version in pom.xml is 1.2.4-SNAPSHOT, the Helm chart version will be 1.2.4-SNAPSHOT-RELEASE.

Triggering the Workflow

The Helm release is a manual GitHub Actions workflow (workflow_dispatch).

Via GitHub UI

  1. Navigate to the repository on GitHub

  2. Go to Actions tab

  3. Select Helm release workflow from the left sidebar

  4. Click Run workflow button

  5. Configure optional inputs:

    • Maven profiles: Profile to activate (default: dev)

    • JDK version: Java version to use (default: 17)

  6. Click Run workflow

Via GitHub CLI

gh workflow run "Helm release" --ref develop

With custom inputs:

gh workflow run "Helm release" --ref develop \
  -f maven-profiles=prod \
  -f jdk-version=21

Workflow Process

The workflow performs these steps:

  1. Checkout repository

  2. Setup JDK with Maven caching

  3. Initialize Helm via Maven: mvn helm:init

  4. Login to Docker Hub using Helm registry login

  5. Package and Push: mvn helm:package helm:push

Workflow Configuration

helm-release.yml
name: 'Helm release'

on:
  workflow_dispatch:
    inputs:
      maven-profiles:
        description: 'Profile to activate during packaging. Defaults to dev.'
        required: false
        type: string
        default: 'dev'
      jdk-version:
        description: 'JDK version to use. Defaults to 17.'
        required: false
        type: string
        default: '17'

jobs:
  helm-build:
    name: 'Package and Push'
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3

      - name: Set up JDK
        uses: actions/setup-java@v3
        with:
          java-version: ${{ inputs.jdk-version }}
          distribution: 'temurin'
          cache: maven

      - name: Initialize Helm
        run: mvn helm:init --batch-mode -P${{ inputs.maven-profiles }}

      - name: Login to Docker Hub Registry
        run: echo "${{ secrets.DOCKER_PAT }}" | helm registry login registry-1.docker.io -u christhonie --password-stdin

      - name: Package and Push Helm Chart
        run: mvn helm:package helm:push --batch-mode -P${{ inputs.maven-profiles }}

Required Secrets

The workflow requires these GitHub secrets:

Secret Purpose

DOCKER_PAT

Docker Hub Personal Access Token for pushing charts

EVENT_PACKAGE_REPO_TOKEN

GitHub token for accessing private Maven dependencies

Helm Chart Location

Charts are stored in Docker Hub under the christhonie namespace:

registry-1.docker.io/christhonie/<chart-name>:<version>

Examples:

  • registry-1.docker.io/christhonie/registration-portal:1.2.4-SNAPSHOT-RELEASE

  • registry-1.docker.io/christhonie/membership-ui:0.1.5-SNAPSHOT-RELEASE

  • registry-1.docker.io/christhonie/event-admin-ui:0.1.11-SNAPSHOT-RELEASE

Verifying the Published Chart

After the workflow completes:

# Pull chart info
helm show chart oci://registry-1.docker.io/christhonie/<chart-name> --version <version>

# Pull chart locally
helm pull oci://registry-1.docker.io/christhonie/<chart-name> --version <version>

Common Issues

Workflow Fails at helm:init

  • Ensure Maven dependencies are accessible

  • Check EVENT_PACKAGE_REPO_TOKEN secret is valid

  • Verify pom.xml has correct helm-maven-plugin configuration

Workflow Fails at helm:push

  • Verify DOCKER_PAT secret is valid and has write access

  • Check Docker Hub repository exists

  • Ensure no rate limiting from Docker Hub

Chart Version Already Exists

OCI registries typically don’t allow overwriting existing tags. If the version already exists:

  1. Increment the project version in pom.xml

  2. Or delete the existing tag from Docker Hub (not recommended for production)

Maven Helm Plugin Configuration

The helm-maven-plugin in pom.xml controls chart packaging:

<plugin>
    <groupId>io.kokuwa.maven</groupId>
    <artifactId>helm-maven-plugin</artifactId>
    <configuration>
        <chartDirectory>src/main/helm</chartDirectory>
        <chartVersion>${revision}-RELEASE</chartVersion>
        <appVersion>${revision}</appVersion>
        <uploadRepoStable>
            <name>dockerhub</name>
            <url>oci://registry-1.docker.io/christhonie</url>
            <type>OCI</type>
        </uploadRepoStable>
    </configuration>
</plugin>

Key configuration:

  • chartVersion: Appends -RELEASE to Maven revision

  • appVersion: Uses Maven revision (matches Docker image tag)

  • uploadRepoStable: OCI registry URL for Docker Hub