002 helm chart release

.github/workflows/release-helm.yaml

@@ -0,0 +1,67 @@
+name: Release Helm Chart
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'  # Only semantic version tags (v1.2.3)
+
+permissions:
+  contents: write  # Required for pushing to gh-pages branch
+
+concurrency:
+  group: helm-release
+  cancel-in-progress: false  # Queue releases, don't cancel
+
+jobs:
+  release-chart:
+    name: Package and Release Helm Chart
+    runs-on: ubuntu-latest
+
+    steps:
+      # T007: Add checkout step with full git history
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for version extraction
+
+      # T008: Add version extraction step
+      - name: Extract Version from Tag
+        id: extract_version
+        run: |
+          GIT_TAG=${GITHUB_REF##*/}
+          VERSION=${GIT_TAG##v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+          echo "Extracted version: $VERSION from tag: $GIT_TAG"
+
+      # T009: Update Chart.yaml with extracted version
+      - name: Update Chart Version
+        run: |
+          sed -i "s/^version:.*/version: ${{ steps.extract_version.outputs.version }}/" helm/supabase-operator/Chart.yaml
+          sed -i "s/^appVersion:.*/appVersion: \"${{ steps.extract_version.outputs.version }}\"/" helm/supabase-operator/Chart.yaml
+          echo "Updated Chart.yaml with version ${{ steps.extract_version.outputs.version }}"
+
+      # T010: Add helm lint validation step
+      - name: Lint Helm Chart
+        run: |
+          helm lint helm/supabase-operator
+          if [ $? -ne 0 ]; then
+            echo "Helm chart validation failed"
+            exit 1
+          fi
+          echo "Helm chart validation passed"
+
+      # T011 & T013: Configure stefanprodan/helm-gh-pages action with git user
+      - name: Publish Helm Chart
+        uses: stefanprodan/helm-gh-pages@master
+        with:
+          token: ${{ secrets.HELM_TOKEN }}
+          charts_dir: helm
+          charts_url: https://helm.strrl.dev
+          owner: STRRL
+          repository: helm.strrl.dev
+          branch: gh-pages
+          app_version: ${{ steps.extract_version.outputs.version }}
+          chart_version: ${{ steps.extract_version.outputs.version }}
+          linting: on
+          commit_username: github-actions[bot]
+          commit_email: github-actions[bot]@users.noreply.github.com

CLAUDE.md

@@ -30,10 +30,9 @@ Building a Kubernetes operator for deploying and managing self-hosted Supabase i
 - Follow Kubernetes API conventions
 
 ## Recent Changes
+- 002-helm-chart-release: Added Go 1.22+ (operator code), YAML (Helm charts/workflows) + GitHub Actions, helm-gh-pages action, Helm 3.x
 - Initialized Kubebuilder project with domain strrl.dev
 - Created SupabaseProject API scaffold
-- Defined comprehensive data model with status design
-- Planned reconciliation strategy based on Rook patterns
 
 ## Testing Requirements
 - Unit tests for reconciliation logic
@@ -42,4 +41,8 @@ Building a Kubernetes operator for deploying and managing self-hosted Supabase i
 - E2E tests for deployment scenarios
 
 ## Current Focus
-Implementing the SupabaseProject controller with granular status management and component deployment logic.
+Implementing the SupabaseProject controller with granular status management and component deployment logic.
+
+## Active Technologies
+- Go 1.22+ (operator code), YAML (Helm charts/workflows) + GitHub Actions, helm-gh-pages action, Helm 3.x (002-helm-chart-release)
+- GitHub Pages repository for chart hosting (002-helm-chart-release)

specs/002-helm-chart-release/checklists/requirements.md

@@ -0,0 +1,37 @@
+# Specification Quality Checklist: Automated Helm Chart Release
+
+**Purpose**: Validate specification completeness and quality before proceeding to planning
+**Created**: 2025-11-23
+**Feature**: [spec.md](../spec.md)
+
+## Content Quality
+
+- [x] No implementation details (languages, frameworks, APIs)
+- [x] Focused on user value and business needs
+- [x] Written for non-technical stakeholders
+- [x] All mandatory sections completed
+
+## Requirement Completeness
+
+- [x] No [NEEDS CLARIFICATION] markers remain
+- [x] Requirements are testable and unambiguous
+- [x] Success criteria are measurable
+- [x] Success criteria are technology-agnostic (no implementation details)
+- [x] All acceptance scenarios are defined
+- [x] Edge cases are identified
+- [x] Scope is clearly bounded
+- [x] Dependencies and assumptions identified
+
+## Feature Readiness
+
+- [x] All functional requirements have clear acceptance criteria
+- [x] User scenarios cover primary flows
+- [x] Feature meets measurable outcomes defined in Success Criteria
+- [x] No implementation details leak into specification
+
+## Notes
+
+- All checklist items pass validation
+- The specification is complete and ready for planning phase
+- No clarifications needed from the user
+- The feature scope is well-defined with clear boundaries

specs/002-helm-chart-release/contracts/chart-metadata.yaml

@@ -0,0 +1,86 @@
+# Helm Chart Metadata Contract
+# This defines the required structure for Chart.yaml
+# Location: charts/supabase-operator/Chart.yaml
+
+# Required Fields
+apiVersion: v2  # Required: Helm chart API version (v2 for Helm 3)
+name: supabase-operator  # Required: Chart name (must be lowercase alphanumeric, - or .)
+version: 0.1.0  # Required: SemVer 2 version of the chart
+
+# Recommended Fields
+appVersion: "0.1.0"  # Version of the application (quoted to ensure string type)
+description: Kubernetes operator for deploying self-hosted Supabase instances  # Max 140 characters
+type: application  # application or library (default: application)
+
+# Optional Metadata
+home: https://github.com/STRRL/supabase-operator  # Project home page
+sources:  # Source code URLs
+  - https://github.com/STRRL/supabase-operator
+
+# Maintainers
+maintainers:
+  - name: STRRL  # Required if maintainers section exists
+    email: contact@example.com  # Optional
+    url: https://github.com/STRRL  # Optional
+
+# Search Keywords
+keywords:
+  - supabase
+  - operator
+  - kubernetes
+  - database
+  - realtime
+  - authentication
+
+# Chart Icon
+icon: https://raw.githubusercontent.com/STRRL/supabase-operator/main/logo.png  # Optional
+
+# Deprecation Flag
+deprecated: false  # Optional, default is false
+
+# Dependencies (Optional)
+dependencies:  # List of charts this chart depends on
+  - name: postgresql  # Required: Dependency chart name
+    version: "12.x.x"  # Required: Version constraint
+    repository: https://charts.bitnami.com/bitnami  # Required: Repository URL
+    condition: postgresql.enabled  # Optional: Condition for including
+    tags:  # Optional: Tags for grouping
+      - database
+    import-values:  # Optional: Import values from dependency
+      - child: postgresql.auth
+        parent: auth
+
+# Annotations (Optional)
+annotations:
+  # ArtifactHub Annotations
+  artifacthub.io/changes: |  # Changelog for this version
+    - kind: added
+      description: Initial release
+  artifacthub.io/containsSecurityUpdates: "false"
+  artifacthub.io/prerelease: "false"
+  artifacthub.io/signKey: |  # GPG key for verification
+    fingerprint: ABCD1234567890
+    url: https://raw.githubusercontent.com/STRRL/supabase-operator/main/pgp-key.asc
+
+  # Custom Annotations
+  example.com/team: platform
+  example.com/tier: production
+
+# Validation Rules:
+# 1. apiVersion must be "v2" for Helm 3
+# 2. name must match directory name and be valid DNS name
+# 3. version must be valid SemVer (without 'v' prefix)
+# 4. version must be unique across all releases
+# 5. appVersion should be quoted to preserve string format
+# 6. description should be concise (recommended < 140 chars)
+# 7. URLs in sources, home, icon must be valid and accessible
+# 8. dependencies versions must use valid constraints
+
+# Version Update Contract:
+# When releasing new version:
+# 1. version field MUST be updated to match git tag (without 'v')
+# 2. appVersion SHOULD be updated to match application version
+# 3. annotations.artifacthub.io/changes SHOULD be updated with changelog
+
+# File Encoding: UTF-8
+# Line Endings: LF (Unix-style)

specs/002-helm-chart-release/contracts/github-workflow.yaml

@@ -0,0 +1,110 @@
+# GitHub Actions Workflow Contract
+# This defines the interface for the Helm release workflow
+
+name: Release Helm Chart
+
+# Trigger Contract
+on:
+  push:
+    tags:
+      # Pattern: Semantic version tags only
+      # Format: v{MAJOR}.{MINOR}.{PATCH}
+      # Examples: v1.0.0, v2.3.1, v0.1.0
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+# Permission Contract
+permissions:
+  contents: write  # Required for pushing to gh-pages branch
+
+# Concurrency Contract
+concurrency:
+  group: helm-release
+  cancel-in-progress: false  # Queue releases, don't cancel
+
+# Environment Contract
+env:
+  CHARTS_DIR: charts
+  CHART_NAME: supabase-operator
+  TARGET_REPO: STRRL/helm.strrl.dev
+  TARGET_BRANCH: gh-pages
+
+# Job Contract
+jobs:
+  release:
+    name: Package and Release Helm Chart
+    runs-on: ubuntu-latest
+
+    # Output Contract
+    outputs:
+      chart_version: ${{ steps.version.outputs.version }}
+      chart_url: ${{ steps.release.outputs.chart_url }}
+
+    steps:
+      # Step 1: Checkout Contract
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for version extraction
+
+      # Step 2: Version Extraction Contract
+      - name: Extract Version from Tag
+        id: version
+        # Input: GITHUB_REF (refs/tags/v1.2.3)
+        # Output: version (1.2.3)
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/v}
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
+      # Step 3: Chart Update Contract
+      - name: Update Chart Version
+        # Input: Chart.yaml at $CHARTS_DIR/$CHART_NAME/Chart.yaml
+        # Operation: Update version and appVersion fields
+        # Output: Modified Chart.yaml
+        run: |
+          sed -i "s/^version:.*/version: ${{ steps.version.outputs.version }}/" \
+            ${{ env.CHARTS_DIR }}/${{ env.CHART_NAME }}/Chart.yaml
+          sed -i "s/^appVersion:.*/appVersion: \"${{ steps.version.outputs.version }}\"/" \
+            ${{ env.CHARTS_DIR }}/${{ env.CHART_NAME }}/Chart.yaml
+
+      # Step 4: Validation Contract
+      - name: Lint Helm Chart
+        # Input: Chart at $CHARTS_DIR/$CHART_NAME
+        # Output: Success/Failure status
+        # Failure: Stops workflow execution
+        run: |
+          helm lint ${{ env.CHARTS_DIR }}/${{ env.CHART_NAME }}
+
+      # Step 5: Release Contract
+      - name: Package and Publish Chart
+        id: release
+        uses: stefanprodan/helm-gh-pages@master
+        with:
+          # Authentication
+          token: ${{ secrets.HELM_REPO_TOKEN }}
+
+          # Source Configuration
+          charts_dir: ${{ env.CHARTS_DIR }}
+
+          # Target Configuration
+          owner: STRRL
+          repository: helm.strrl.dev
+          branch: ${{ env.TARGET_BRANCH }}
+          charts_url: https://helm.strrl.dev
+
+          # Version Configuration
+          chart_version: ${{ steps.version.outputs.version }}
+          app_version: ${{ steps.version.outputs.version }}
+
+          # Validation
+          linting: on
+
+          # Git Configuration
+          commit_username: github-actions[bot]
+          commit_email: github-actions[bot]@users.noreply.github.com
+
+# Failure Contract
+# On any step failure:
+# - Workflow stops immediately
+# - No partial release
+# - No notification sent (per spec)
+# - Failure visible in GitHub Actions UI