fix: overhaul release pipeline — 5 issues resolved

1. version input now optional — auto-increment from release_type works
2. replaced deprecated actions/create-release@v1 with gh release create
3. race condition fixed — release commit uses [skip ci], removed fragile
   github.actor guard from build-and-push.yaml
4. simplified gh-pages publishing — uses clean temp dir + shallow clone
   instead of convoluted git worktree fallback
5. version parsing strips pre-release suffixes (e.g., 2.0.0-dev → 2.0.0)

Generated with [Claude Code](https://claude.ai/code)
via [Happy](https://happy.engineering)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Happy <yesreply@happy.engineering>

.github/workflows/README.md

@@ -15,9 +15,8 @@ Use this for all version releases:
 - ✅ Updates chart version
 - ✅ Creates git tag
 - ✅ Builds Docker image with all proper tags
-- ✅ Publishes Helm chart to GHCR
+- ✅ Publishes Helm chart to GitHub Pages (`https://cpfarhood.github.io/devcontainer`)
 - ✅ Creates GitHub Release with changelog
-- ✅ No more `[skip ci]` blocking builds!
 
 ### 2️⃣ For Quick Fixes → **Quick Fix Build**
 Use this for emergency fixes without version changes:
@@ -30,8 +29,8 @@ Use this for emergency fixes without version changes:
 
 ### 3️⃣ Automatic CI → **Build and Push**
 Runs automatically on:
+- Pushes to `main` (builds and pushes; skipped for release commits via `[skip ci]`)
 - Pull requests (builds but doesn't push)
-- Tags starting with `v*` (builds and pushes)
 - Manual trigger available
 
 ## Workflow Files
@@ -90,5 +89,5 @@ gh run watch
 ### After (Simple! 🎉)
 - **3 total workflows** (down from 6+)
 - **1 button** for complete releases
-- **No more `[skip ci]`** blocking builds
+- Release builds its own Docker image — `[skip ci]` on the version commit prevents duplicate CI builds
 - **Clear separation** of concerns

.github/workflows/build-and-push.yaml

@@ -16,9 +16,6 @@ env:
 jobs:
   build-and-push:
     runs-on: ubuntu-latest
-    # Skip builds triggered by release-unified.yaml commits (github-actions[bot])
-    # to prevent racing with the release workflow's own Docker build
-    if: github.event_name == 'workflow_dispatch' || github.event_name == 'pull_request' || github.actor != 'github-actions[bot]'
     permissions:
       contents: read
       packages: write

.github/workflows/release-unified.yaml

@@ -4,11 +4,11 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: 'Version to release (e.g., 0.1.25)'
+        description: 'Explicit version (e.g., 1.2.3). Leave blank to auto-increment.'
-        required: true
+        required: false
         type: string
       release_type:
-        description: 'Release type'
+        description: 'Release type (used when version is blank)'
         required: true
         default: 'patch'
         type: choice
@@ -49,37 +49,34 @@ jobs:
       - name: Determine Version
         id: version
         run: |
-          if [ "${{ github.event.inputs.version }}" != "" ]; then
+          INPUT_VERSION="${{ github.event.inputs.version }}"
-            VERSION="${{ github.event.inputs.version }}"
+          if [ -n "$INPUT_VERSION" ]; then
+            VERSION="$INPUT_VERSION"
           else
-            # Auto-determine next version based on release type
+            # Auto-increment based on release_type
             CURRENT=$(grep '^version:' chart/Chart.yaml | awk '{print $2}')
-            MAJOR=$(echo $CURRENT | cut -d. -f1)
+            # Strip any pre-release suffix (e.g., 2.0.0-dev -> 2.0.0)
-            MINOR=$(echo $CURRENT | cut -d. -f2)
+            CURRENT=$(echo "$CURRENT" | sed 's/-.*//')
-            PATCH=$(echo $CURRENT | cut -d. -f3)
+            MAJOR=$(echo "$CURRENT" | cut -d. -f1)
+            MINOR=$(echo "$CURRENT" | cut -d. -f2)
+            PATCH=$(echo "$CURRENT" | cut -d. -f3)
 
             case "${{ github.event.inputs.release_type }}" in
-              major)
+              major) VERSION="$((MAJOR + 1)).0.0" ;;
-                VERSION="$((MAJOR + 1)).0.0"
+              minor) VERSION="${MAJOR}.$((MINOR + 1)).0" ;;
-                ;;
+              patch) VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))" ;;
-              minor)
-                VERSION="${MAJOR}.$((MINOR + 1)).0"
-                ;;
-              patch)
-                VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))"
-                ;;
             esac
           fi
 
           echo "version=${VERSION}" >> $GITHUB_OUTPUT
           echo "tag=v${VERSION}" >> $GITHUB_OUTPUT
-          echo "🚀 Releasing version ${VERSION}"
+          echo "Releasing version ${VERSION}"
 
       - name: Update Chart Version
         run: |
           sed -i "s/^version: .*/version: ${{ steps.version.outputs.version }}/" chart/Chart.yaml
           git add chart/Chart.yaml
-          git diff --quiet --staged || git commit -m "chore: release version ${{ steps.version.outputs.version }}"
+          git diff --quiet --staged || git commit -m "chore(release): ${{ steps.version.outputs.version }} [skip ci]"
 
       - name: Create and Push Tag
         run: |
@@ -107,27 +104,69 @@ jobs:
           cache-to: type=gha,mode=max
           platforms: linux/amd64
 
-      - name: Package Helm Chart
+      - name: Publish Helm Chart to GitHub Pages
         run: |
-          helm registry login ghcr.io \
-            --username ${{ github.actor }} \
-            --password ${{ secrets.GITHUB_TOKEN }}
           helm package chart/
-          helm push devcontainer-${{ steps.version.outputs.version }}.tgz oci://ghcr.io/cpfarhood/charts
+          CHART_TGZ="devcontainer-${{ steps.version.outputs.version }}.tgz"
 
-      - name: Generate Release Notes
+          # Set up gh-pages in a temporary directory
-        id: notes
+          PAGES_DIR=$(mktemp -d)
+          if git ls-remote --heads origin gh-pages | grep -q gh-pages; then
+            # gh-pages exists — shallow clone just that branch
+            git clone --single-branch --branch gh-pages \
+              "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git" \
+              "$PAGES_DIR"
+          else
+            # First time — initialize gh-pages
+            git init "$PAGES_DIR"
+            git -C "$PAGES_DIR" checkout --orphan gh-pages
+            git -C "$PAGES_DIR" remote add origin \
+              "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
+            cat > "$PAGES_DIR/index.html" <<'HTMLEOF'
+          <!DOCTYPE html>
+          <html>
+          <head><title>Dev Container Helm Chart Repository</title></head>
+          <body>
+          <h1>Dev Container Helm Chart Repository</h1>
+          <p>Add this repository to Helm:</p>
+          <pre>helm repo add devcontainer https://cpfarhood.github.io/devcontainer</pre>
+          <p>Install the chart:</p>
+          <pre>helm install mydev devcontainer/devcontainer --set name=mydev</pre>
+          </body>
+          </html>
+          HTMLEOF
+          fi
+
+          git -C "$PAGES_DIR" config user.name "github-actions[bot]"
+          git -C "$PAGES_DIR" config user.email "github-actions[bot]@users.noreply.github.com"
+
+          # Copy chart package and rebuild index
+          cp "$CHART_TGZ" "$PAGES_DIR/"
+          if [ -f "$PAGES_DIR/index.yaml" ]; then
+            helm repo index "$PAGES_DIR" --url https://cpfarhood.github.io/devcontainer --merge "$PAGES_DIR/index.yaml"
+          else
+            helm repo index "$PAGES_DIR" --url https://cpfarhood.github.io/devcontainer
+          fi
+
+          # Commit and push
+          git -C "$PAGES_DIR" add .
+          git -C "$PAGES_DIR" commit -m "Publish chart ${{ steps.version.outputs.version }}"
+          git -C "$PAGES_DIR" push origin gh-pages
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          # Get commits since last tag
+          # Build release notes
           PREV_TAG=$(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")
           if [ -z "$PREV_TAG" ]; then
             COMMITS=$(git log --pretty=format:"- %s (%h)" HEAD)
           else
-            COMMITS=$(git log --pretty=format:"- %s (%h)" ${PREV_TAG}..HEAD)
+            COMMITS=$(git log --pretty=format:"- %s (%h)" "${PREV_TAG}..HEAD")
           fi
 
-          cat << EOF > release-notes.md
+          cat > release-notes.md <<EOF
-          ## 🚀 Release ${{ steps.version.outputs.version }}
+          ## Release ${{ steps.version.outputs.version }}
 
           ### Changes
           ${COMMITS}
@@ -139,21 +178,12 @@ jobs:
 
           ### Helm Chart
           \`\`\`bash
-          helm install devcontainer oci://ghcr.io/cpfarhood/charts/devcontainer --version ${{ steps.version.outputs.version }}
+          helm repo add devcontainer https://cpfarhood.github.io/devcontainer
+          helm repo update
+          helm install mydev devcontainer/devcontainer --version ${{ steps.version.outputs.version }} --set name=mydev
           \`\`\`
           EOF
 
-          echo "notes<<EOF" >> $GITHUB_OUTPUT
+          gh release create "${{ steps.version.outputs.tag }}" \
-          cat release-notes.md >> $GITHUB_OUTPUT
+            --title "Release ${{ steps.version.outputs.tag }}" \
-          echo "EOF" >> $GITHUB_OUTPUT
+            --notes-file release-notes.md
-
-      - name: Create GitHub Release
-        uses: actions/create-release@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          tag_name: ${{ steps.version.outputs.tag }}
-          release_name: Release ${{ steps.version.outputs.tag }}
-          body: ${{ steps.notes.outputs.notes }}
-          draft: false
-          prerelease: false

CLAUDE.md

@@ -190,14 +190,16 @@ helm install my-devcontainer ./chart -f custom-values.yaml
 
 ### CI/CD
 
-- **`build-and-push.yaml`** — Builds and pushes to GHCR on every push to `main`, version tags (`v*`), and PRs. For version tags, also creates GitHub Release with Helm chart after Docker build completes. Tags: `latest` (main), semver, branch name, commit SHA.
+- **`build-and-push.yaml`** — Builds and pushes to GHCR on every push to `main`, version tags (`v*`), and PRs. Tags: `latest` (main), semver, branch name, commit SHA.
+- **`release-unified.yaml`** — Manual release workflow: bumps chart version, builds Docker image, publishes Helm chart to GitHub Pages (`https://cpfarhood.github.io/devcontainer`), and creates GitHub Release.
 - **`dependabot.yml`** — Weekly updates for GitHub Actions and Docker base image.
 
 Image registry: `ghcr.io/cpfarhood/devcontainer`
+Helm repo: `https://cpfarhood.github.io/devcontainer`
 
 ## Kubernetes Notes
 
-- Deployed via Helm chart (`chart/`), published as OCI artifact to GHCR, reconciled by Flux
+- Deployed via Helm chart (`chart/`), published to GitHub Pages Helm repo, reconciled by Flux
 - Storage class is `ceph-filesystem` by default — change via `storage.className` in values
 - Resource limits: 1–4 CPU, 2–8Gi memory
 - Health checks (liveness/readiness probes) on port 5800

README.md

@@ -14,23 +14,30 @@ A containerized cloud development environment with web-based GUI access, featuri
 
 ## Quick Start
 
-### Option A: Quickstart (Recommended)
+### Option A: Install from Helm Repo (Recommended)
-
-For 80% of users, use the simplified quickstart values:
 
 ```bash
-# Copy and customize the quickstart template
+# Add the Helm repository
+helm repo add devcontainer https://cpfarhood.github.io/devcontainer
+helm repo update
+
+# Deploy with one command
+helm install mydev devcontainer/devcontainer \
+  --set name=mydev \
+  --set githubRepo=https://github.com/youruser/yourrepo
+```
+
+### Option B: Install from Source
+
+```bash
+# Clone and customize the quickstart template
 cp chart/values-quickstart.yaml my-values.yaml
+# Edit my-values.yaml to set your name and repository
 
-# Edit my-values.yaml to set your name and repository:
-# name: mydev
-# githubRepo: https://github.com/youruser/yourrepo
-
-# Deploy with minimal configuration
 helm install mydev ./chart -f my-values.yaml
 ```
 
-### Option B: One-Command Deploy
+### Option C: One-Command from Source
 
 ```bash
 helm install mydev ./chart \