Helm Workflows

Reusable GitHub Actions workflows for Helm chart repositories.

Workflows

Chart Repository Workflows

For individual chart repositories (e.g., chart-keycloak, chart-grafana):

Workflow	Purpose
sync-upstream.yml	Sync from upstream submodules
release-please.yml	Automate releases with semantic versioning + 🤖 AI-enhanced changelogs
publish-chart.yml	Publish to OCI and trigger registry update
validate-licenses.yml	📋 License validation with AI compatibility analysis
scan-images.yml	Security scan with Trivy
replicate-images.yml	Mirror images to private registry
update-images.yml	Check for new container versions with Renovate + 🤖 AI-enhanced analysis
cleanup-releases.yml	Prune old releases and tags

Registry Repository Workflows

For the central registry repository (e.g., helm-charts):

Workflow	Purpose
update-registry.yml	Pull charts from OCI, update index, deploy Pages

Requirements

GitHub App (Recommended):

• Organization variable: APP_ID
• Organization secret: APP_PRIVATE_KEY
• Permissions: Contents (RW), Packages (RW), Metadata (R)
• See ./docs/GITHUB_APP_SETUP.md

Repository Permissions:

• Settings → Actions → General → "Read and write permissions"
• ✓ "Allow GitHub Actions to create and approve pull requests"

Chart Repository Setup

1. Sync Upstream

# .github/workflows/sync.yml
name: Sync
on:
  schedule:
    - cron: '0 0 * * 0'
  workflow_dispatch:

jobs:
  sync:
    uses: chronolite-technologies/helm-workflows/.github/workflows/sync-upstream.yml@main
    with:
      upstream-path: upstream/source
      chart-path: charts/chart-name

2. Automated Releases

Create .release-please-manifest.json:

{
  ".": "1.0.0"
}

Create release-please-config.json:

{
  "packages": {
    ".": {
      "release-type": "simple",
      "package-name": "chart-name",
      "extra-files": [{
        "type": "yaml",
        "path": "charts/chart-name/Chart.yaml",
        "jsonpath": "$.version"
      }]
    }
  }
}

Create .github/workflows/release-please.yml:

name: Release Please
on:
  push:
    branches: [main]

jobs:
  release:
    uses: chronolite-technologies/helm-workflows/.github/workflows/release-please.yml@main
    with:
      chart-path: charts/chart-name
      chart-name: chart-name
    secrets: inherit

Version bumps:

• fix: → patch (1.0.0 → 1.0.1)
• feat: → minor (1.0.0 → 1.1.0)
• feat!: → major (1.0.0 → 2.0.0)

3. Scan Images

Create .images.yaml:

registry:
  prefix: mirrors

images:
  keycloak:
    source: quay.io/keycloak/keycloak
    versions: ["26.0.0"]

Create .github/workflows/scan.yml:

name: Scan
on:
  schedule:
    - cron: '0 2 * * *'
  workflow_dispatch:

jobs:
  scan:
    uses: chronolite-technologies/helm-workflows/.github/workflows/scan-images.yml@main
    with:
      severity: CRITICAL

4. Update Image Versions

Create .github/workflows/update-images.yml:

name: Update Images
on:
  schedule:
    - cron: '0 1 * * 1'  # Weekly
  workflow_dispatch:

jobs:
  update:
    uses: chronolite-technologies/helm-workflows/.github/workflows/update-images.yml@main
    secrets: inherit

Optional - custom Renovate config (.github/renovate.json):

{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:base"],
  "packageRules": [
    {
      "matchDatasources": ["docker"],
      "matchUpdateTypes": ["patch"],
      "automerge": true
    }
  ]
}

How it works:

• Renovate scans .images.yaml for version updates
• Queries container registries for new versions
• Creates PRs with updated versions
• Skips floating tags (latest, nightly)

5. Replicate Images

Create .github/workflows/replicate.yml:

name: Replicate
on:
  schedule:
    - cron: '0 3 * * *'
  workflow_dispatch:

jobs:
  replicate:
    uses: chronolite-technologies/helm-workflows/.github/workflows/replicate-images.yml@main
    secrets: inherit

6. Cleanup Releases

Create .github/workflows/cleanup.yml:

name: Cleanup
on:
  schedule:
    - cron: '0 4 * * 0'
  workflow_dispatch:

jobs:
  cleanup:
    uses: chronolite-technologies/helm-workflows/.github/workflows/cleanup-releases.yml@main
    with:
      keep-count: 10

Registry Repository Setup

Update Index on Chart Publish

Create .github/workflows/update-index.yml:

name: Update Index

on:
  repository_dispatch:
    types: [chart-published]
  workflow_dispatch:

permissions:
  contents: write
  packages: read

jobs:
  update:
    uses: chronolite-technologies/helm-workflows/.github/workflows/update-registry.yml@main
    with:
      chart-name: ${{ github.event.client_payload.chart }}
      chart-version: ${{ github.event.client_payload.version }}
      oci-url: ${{ github.event.client_payload.oci_url }}
    secrets: inherit

How it works:

1. Chart repo creates release tag
2. publish-chart.yml publishes to GHCR
3. Sends repository_dispatch to registry repo
4. Registry pulls from OCI, updates index.yaml, deploys to Pages

Architecture

chart-keycloak (chart repo)
  └─ Release tag created
     └─ publish-chart.yml
        ├─ Push to OCI (ghcr.io)
        └─ Dispatch event
           └─ helm-charts (registry repo)
              └─ update-registry.yml
                 ├─ Pull from OCI
                 ├─ Update index.yaml
                 └─ Deploy to Pages

Parallel Automation:
  ├─ update-images.yml → Check for new versions (weekly)
  ├─ scan-images.yml → Security scans (daily)
  └─ replicate-images.yml → Mirror images (daily)

Documentation

• HELM-OPS-CONCEPT.md - Architecture overview
• ./docs/GITHUB_APP_SETUP.md - GitHub App configuration
• docs/ai-changelog.md - 🤖 AI-Enhanced Changelogs setup and usage
• docs/license-validation.md - 📋 License Validation with AI compatibility analysis
• docs/ai-image-updates.md - 🔄 AI-Enhanced Image Updates with Renovate
• docs/renovate-enhanced.md - Enhanced Renovate configuration guide

Features

🤖 AI-Enhanced Changelogs

The release-please workflow automatically generates user-friendly, comprehensive release notes using OpenAI GPT-4o:

• ✅ Transforms technical commits into user-friendly descriptions
• ✅ Categorizes changes (Features, Bug Fixes, Security, etc.)
• ✅ Explains impact and context
• ✅ Highlights breaking changes with migration steps
• ✅ Cost-effective (~$0.03 per release)
• ✅ Automatic fallback if AI unavailable

Setup: Add OPENAI_API_KEY to repository secrets. See docs/ai-changelog.md for details.

📋 License Validation

The validate-licenses workflow validates license files with modular JavaScript architecture and optional AI-powered compatibility analysis:

• ✅ Validates all declared licenses in .licenses.yaml
• ✅ Tracks upstream license changes (git history)
• ✅ AI compatibility analysis with OpenAI GPT-4o
• ✅ Automatic GitHub issue creation on failures
• ✅ Comprehensive summary reports
• ✅ Cost-effective (~$0.008 per validation)
• ✅ Works without AI (validation + tracking only)

Setup: Create .licenses.yaml in repository root. Add OPENAI_API_KEY for AI analysis (optional). See docs/license-validation.md for details.

🔄 AI-Enhanced Image Updates

The update-images workflow uses Renovate Bot with AI-powered analysis to intelligently manage container image updates:

• ✅ 50% fewer manual PR reviews - AI pre-screens updates for breaking changes
• ✅ Faster security updates - Patch updates auto-merge safely after stabilization period
• ✅ Better visibility - Clear risk levels (🟢 Low, 🟡 Medium, 🔴 High) and actionable recommendations
• ✅ Smart grouping - Separate PRs by risk (patch/minor/major)
• ✅ Intelligent auto-merge - Safe automatic merging for low-risk patches
• ✅ Cost-effective - $0.02 per image update ($2-5/month total)

How it works:

1. Renovate detects updates → Creates PR for image version changes
2. Fetches changelog data → Multiple sources (Docker Hub, GitHub Releases, CHANGELOG.md)
3. AI analysis → OpenAI GPT-4o analyzes breaking changes, security impacts, migration requirements
4. Enhances PR → Adds detailed analysis, risk labels, auto-merge recommendations
5. Auto-merge → Low-risk patches merge automatically after stabilization period

Setup:

• Add OPENAI_API_KEY to repository secrets (required for AI analysis)
• Optional: Create .github/renovate.json for custom rules (uses enhanced config by default)
• See docs/ai-image-updates.md and docs/renovate-enhanced.md for details.

---

License: Apache 2.0 • Maintainer: Chronolite Technologies