Better Chart Release Flow for ToolHive CRD's and ToolHive Operator

[ChrisJBurns]

Currently the ToolHive Operator and ProxyRunner are tagged and released together. Renovate then raises a PR for the bumping of the latest versions in the Operator Helm chart, the problem is, this normally gets forgotten about and its almost always the case whereby the CI builds for the bump PR because there are some docs that need updating as well as the Chart needing a bump too.

To make matters more complicated, if there are CRDs changed at the same time, the CRDs chart has to be released either before or at the same time as the Operator bump in the Operator Chart.

We should really figure out the best way of automating this in one go. This would include, when we do a release, we also have automation that perform the necessary bumps in the Helm chart and manifests updates as well as the releasing of the Chart itself. The Chart should not be released if the underlying Operator or ProxyRunner images have failed to build, only when they pass.

[ChrisJBurns]

@claude Based on the description, would you be able to think of a release workflow/process that allows us to satisfy all of our needs

[claude]

Claude finished @ChrisJBurns's task —— View job

---

ToolHive Release Flow Automation Proposal

Based on my analysis of your current setup, here's a comprehensive automated release workflow design that addresses all the pain points you've identified.

Current State Analysis

Components:

• Main Release (releaser.yml): Builds binaries + images (operator, proxyrunner, egress-proxy)
• Chart Release (releaser-helm-charts.yml): Publishes Helm charts independently
• CRD Chart: Version 0.0.21 (independent versioning)
• Operator Chart: Version 0.2.11, appVersion 0.2.17 (references both operator + proxyrunner images)

Key Problems:

1. Manual chart bumps after image releases
2. CRD/operator chart sync issues
3. Chart releases aren't gated on successful image builds
4. Documentation updates forgotten
5. Renovate only handles operator chart, not CRDs

Proposed Solution: Unified Release Orchestration

Phase 1: Enhanced Release Workflow

Replace the current manual process with an orchestrated workflow that runs on tag creation:

# .github/workflows/unified-release.yml
name: Unified Release
on:
  push:
    tags: ['v*']

jobs:
  # 1. Build binaries (existing)
  build-binaries:
    # ... existing releaser.yml logic
    
  # 2. Build and push images (gated on binary success)
  build-images:
    needs: [build-binaries]
    # ... existing image-build-and-publish.yml logic
    
  # 3. Update chart versions and app versions
  update-chart-versions:
    needs: [build-images]
    runs-on: ubuntu-latest
    outputs:
      crd-version-changed: ${{ steps.update-charts.outputs.crd-version-changed }}
      operator-version-changed: ${{ steps.update-charts.outputs.operator-version-changed }}
    steps:
      - name: Update Chart Versions
        id: update-charts
        run: |
          # Auto-bump chart versions based on image changes
          # Update appVersion to match release tag
          # Commit changes to release branch
          
  # 4. Release CRDs chart (if changed)
  release-crd-chart:
    needs: [update-chart-versions]
    if: needs.update-chart-versions.outputs.crd-version-changed == 'true'
    # ... chart-releaser for CRDs
    
  # 5. Release Operator chart (after CRDs)
  release-operator-chart:
    needs: [update-chart-versions, release-crd-chart]
    if: always() && needs.update-chart-versions.outputs.operator-version-changed == 'true'
    # ... chart-releaser for operator
    
  # 6. Update documentation
  update-documentation:
    needs: [release-crd-chart, release-operator-chart]
    # ... trigger docs update

Phase 2: Smart Chart Version Management

Automatic Version Bump Logic:

• CRD Chart: Bump when CRD definitions change (detect via git diff on api/v1alpha1/)
• Operator Chart: Bump when operator image version changes OR when CRDs change
• AppVersion: Always update to match the release tag

Implementation:

# Chart version update script
detect_crd_changes() {
  git diff --name-only $PREVIOUS_TAG..$CURRENT_TAG | grep -q "^api/v1alpha1/"
}

update_chart_versions() {
  RELEASE_TAG=${GITHUB_REF#refs/tags/}
  
  # Always update appVersions to match release
  yq eval '.appVersion = "'$RELEASE_TAG'"' -i deploy/charts/operator/Chart.yaml
  
  # Bump chart versions based on changes
  if detect_crd_changes; then
    bump_chart_version deploy/charts/operator-crds/Chart.yaml
    bump_chart_version deploy/charts/operator/Chart.yaml  # CRD changes affect operator
  else
    bump_chart_version deploy/charts/operator/Chart.yaml  # Just image updates
  fi
}

Phase 3: Enhanced Renovate Configuration

Update renovate.json to handle both charts:

{
  "packageRules": [
    {
      "groupName": "toolhive images",
      "matchDatasources": ["docker"],
      "matchPackageNames": [
        "ghcr.io/stacklok/toolhive/proxyrunner",
        "ghcr.io/stacklok/toolhive/operator"
      ],
      "matchFileNames": ["deploy/charts/**"],
      "automerge": false,
      "labels": ["charts", "dependencies"],
      "reviewers": ["ChrisJBurns"]
    }
  ]
}

Release Flow Decision Tree

Tag Created (v1.2.3)
├── Build Binaries ✓
├── Build Images (operator, proxyrunner, egress-proxy) ✓
├── Detect Changes:
│   ├── CRD Changes? → Bump CRD Chart + Operator Chart
│   ├── Only Code Changes? → Bump Operator Chart only
│   └── Update appVersion = v1.2.3 (always)
├── Release Charts:
│   ├── CRDs Chart (if changed) → Wait for success
│   └── Operator Chart → Wait for CRDs completion
└── Update Documentation ✓

Benefits

1. Zero Manual Intervention: Everything happens automatically on tag push
2. Failure Safety: Charts only release if images build successfully
3. Smart Versioning: Only bump charts when actually needed
4. Dependency Ordering: CRDs always release before operator chart
5. Audit Trail: All changes committed to git with clear history
6. Rollback Friendly: Failed releases don't publish partial artifacts

Implementation Plan

1. Week 1: Create unified release workflow
2. Week 2: Implement smart chart versioning logic
3. Week 3: Update Renovate configuration
4. Week 4: Test with pre-release tags, then roll out

This approach eliminates all manual steps while ensuring charts are only released when underlying images are successfully built and tested.

---