Merge pull request #46 from dennisme/dennisme/revamp-release

chore: reduce complexity

Author: dennisme

.github/cr.yaml

@@ -0,0 +1,7 @@
+# Config for helm/chart-releaser-action (cr) in
+# .github/workflows/helm-release.yaml.
+#
+# Custom release name so the chart's GitHub Release is unmistakably
+# separate from the app's own `vX.Y.Z` release that goreleaser.yaml
+# creates on the same tag.
+release-name-template: "helm-{{ .Name }}-{{ .Version }}"

.github/workflows/docs.yml

@@ -27,6 +27,14 @@ on:
   # Refresh docs/releases/changelog.md after GoReleaser publishes notes.
   release:
     types: [published]
+  # helm-release.yaml (cr) publishes the chart's GitHub Release *before* it
+  # finishes pushing the updated index.yaml to gh-pages, so the `release`
+  # trigger above can fire while gh-pages is still stale. Wait for
+  # helm-release.yaml to fully complete instead, so the chart index we fetch
+  # below is current.
+  workflow_run:
+    workflows: ["helm-release"]
+    types: [completed]
   workflow_dispatch:
 
 permissions:
@@ -65,26 +73,37 @@ jobs:
       # Helm chart repository lives at /charts/ on the same GitHub Pages site
       # as the docs and demo. That keeps a single Pages deployment (one
       # concurrency group) and avoids a second repo or branch for charts.
+      # The actual chart .tgz files are published as GitHub Release assets
+      # by .github/workflows/helm-release.yaml (cr); this job only mirrors
+      # the resulting index.yaml from the gh-pages branch, it never
+      # packages the chart itself.
       - name: Set up Helm
         uses: azure/setup-helm@v4
         with:
           version: v3.16.2
-      - name: Package Helm chart into site/charts
+      - name: Fetch chart index from gh-pages
         run: |
           set -euo pipefail
           mkdir -p site/charts
-          helm package deploy/charts/grex --destination site/charts
-          helm repo index site/charts \
-            --url https://dennisme.github.io/grex/charts
+          if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then
+            git fetch --depth 1 origin gh-pages
+            git show origin/gh-pages:index.yaml > site/charts/index.yaml
+          else
+            echo "gh-pages branch not found yet (no chart release published); writing empty index"
+            helm repo index site/charts --url https://dennisme.github.io/grex/charts
+          fi
           # Keep a copy of the chart source README for humans browsing the path.
           cp deploy/charts/grex/README.md site/charts/README.md
       - name: Upload artifact
-        # Deploy from main pushes, published releases (refresh changelog), and manual runs.
+        # Deploy from main pushes, published releases (refresh changelog),
+        # a completed helm-release run (refresh chart index), and manual runs.
         if: >-
           github.event_name != 'pull_request' &&
           (github.ref == 'refs/heads/main' ||
            github.event_name == 'release' ||
-           github.event_name == 'workflow_dispatch')
+           github.event_name == 'workflow_dispatch' ||
+           (github.event_name == 'workflow_run' &&
+            github.event.workflow_run.conclusion == 'success'))
         uses: actions/upload-pages-artifact@v3
         with:
           path: site
@@ -94,7 +113,9 @@ jobs:
       github.event_name != 'pull_request' &&
       (github.ref == 'refs/heads/main' ||
        github.event_name == 'release' ||
-       github.event_name == 'workflow_dispatch')
+       github.event_name == 'workflow_dispatch' ||
+       (github.event_name == 'workflow_run' &&
+        github.event.workflow_run.conclusion == 'success'))
     needs: build
     runs-on: ubuntu-latest
     environment:

.github/workflows/goreleaser.yaml

@@ -42,7 +42,8 @@ jobs:
           password: ${{ secrets.GITHUB_TOKEN }}
 
       # Package outside dist/ so goreleaser --clean does not delete the chart.
-      # Chart.yaml version/appVersion are bumped by `just release-tag` before the tag.
+      # Only used for the OCI push below; Chart.yaml's version/appVersion
+      # are a 0.0.0 placeholder, this override is the only real version.
       - name: Package Helm chart
         run: |
           set -euo pipefail

.github/workflows/helm-release.yaml

@@ -0,0 +1,56 @@
+name: helm-release
+
+# Publishes the Helm chart as its own GitHub Release + chart-repo index
+# entry on every app version tag. Runs independently of goreleaser.yaml
+# (which builds binaries/images/OCI chart push from the same tag) so a
+# failure in one doesn't block the other.
+#
+# Chart.yaml's version/appVersion are placeholders (0.0.0) — the real
+# version is always this explicit tag-derived override, never read from
+# the committed file. See docs/developer/releasing.md.
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  chart-release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Helm
+        uses: azure/setup-helm@v4
+        with:
+          version: v3.16.2
+
+      - name: Configure Git
+        run: |
+          git config user.name "$GITHUB_ACTOR"
+          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
+      # cr expects pre-packaged charts in .cr-release-packages when
+      # skip_packaging is set; package here with an explicit version
+      # override so Chart.yaml's committed placeholder is never read.
+      - name: Package chart
+        run: |
+          set -euo pipefail
+          VER="${GITHUB_REF_NAME#v}"
+          mkdir -p .cr-release-packages
+          helm package deploy/charts/grex \
+            --version "$VER" \
+            --app-version "$VER" \
+            --destination .cr-release-packages
+
+      - name: Run chart-releaser
+        uses: helm/chart-releaser-action@v1.6.0
+        with:
+          config: .github/cr.yaml
+          skip_packaging: true
+          pages_branch: gh-pages
+        env:
+          CR_TOKEN: "${{ secrets.GITHUB_TOKEN }}"

.goreleaser.yaml

@@ -62,9 +62,8 @@ changelog:
 
 release:
   name_template: "v{{ .Version }}"
-  # Packaged by the goreleaser workflow (outside dist/ so --clean is safe).
-  extra_files:
-    - glob: ./.chart-release/*.tgz
+  # The chart .tgz is not attached here: it ships on its own GitHub Release
+  # (helm-grex-VERSION), published by .github/workflows/helm-release.yaml (cr).
   # Appended after the generated changelog on the GitHub Release.
   footer: |
     ---

deploy/charts/grex/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: grex
 description: OpAMP control plane for OpenTelemetry Collector fleets
 type: application
-version: 0.2.0
-appVersion: "0.2.0"
+version: 0.0.0
+appVersion: "0.0.0"
 
 keywords:
   - opamp

deploy/charts/grex/README.md

@@ -24,9 +24,10 @@ helm install grex oci://ghcr.io/dennisme/charts/grex --version 0.1.0 \
   --namespace grex --create-namespace
 ```
 
-Chart `version` / `appVersion` are bumped with grex releases
-(`just release-tag`). Empty `image.tag` defaults to `appVersion`, which
-matches the published `ghcr.io/dennisme/grex` image tag.
+Chart `version` / `appVersion` in the packaged/published chart match each
+grex release tag (set via an explicit override at package time in CI, not
+stored in this file's `Chart.yaml`). Empty `image.tag` defaults to
+`appVersion`, which matches the published `ghcr.io/dennisme/grex` image tag.
 
 ## Install from a local checkout
 

docs/admin/helm.md

@@ -30,7 +30,7 @@ collide:
 |------|---------|
 | `/` | MkDocs documentation |
 | `/demo/` | Static fleet UI demo |
-| `/charts/` | Helm repository (`index.yaml` + `.tgz`) |
+| `/charts/` | Helm repository index (`index.yaml`; each `.tgz` downloads from its own GitHub Release asset) |
 
 ```sh
 helm repo add grex https://dennisme.github.io/grex/charts/

docs/developer/releasing.md

@@ -63,45 +63,51 @@ svu next      # what the next release tag would be
 
    - Fetches remote tags so `svu` sees the latest release
    - Runs `svu next` (for example `v0.2.0`)
-   - Bumps `deploy/charts/grex/Chart.yaml` `version` and `appVersion` to the
-     SemVer **without** the leading `v` (for example `0.2.0`), and commits
-     `chore(release): bump helm chart to …` when they change
-   - Creates the git tag on that commit
-   - Pushes the commit and the tag to `origin`
+   - Creates the git tag on the current commit
+   - Pushes the tag to `origin`
+
+   It does **not** touch `deploy/charts/grex/Chart.yaml`. That file's
+   `version`/`appVersion` are a fixed `0.0.0` placeholder; every workflow that
+   packages the chart overrides both with an explicit `--version`/
+   `--app-version` flag derived from the tag, so the committed file is never
+   read for a real release. See [Helm chart versioning](#helm-chart-versioning).
 
 4. Watch CI:
 
-   - **GoReleaser** (tag) — binaries, container image, chart `.tgz` on the
-     GitHub Release, chart OCI push to GHCR
-   - **docs** (push to `main`, path-filtered) — rebuilds Pages, including
-     packaging the chart into `https://dennisme.github.io/grex/charts/`
+   - **goreleaser** (tag) — binaries, container image, chart OCI push to GHCR
+   - **helm-release** (tag) — packages the chart, publishes it as its own
+     GitHub Release (`helm-grex-VERSION`), pushes the updated repo index to
+     the `gh-pages` branch
+   - **docs** (runs after **helm-release** completes, plus push-to-`main` and
+     `release: published`) — rebuilds Pages, mirroring the `gh-pages` index
+     into `https://dennisme.github.io/grex/charts/`
 
 Do **not** create release tags by hand unless you are fixing a one-off mistake;
-`just release-tag` keeps app, image, and chart versions aligned.
+`just release-tag` is just a thin wrapper around `svu next` + `git tag` +
+`git push`, but it also checks for a clean tree and refuses to retag.
 
 ### Manual equivalent
 
 ```sh
 git fetch --tags
 TAG=$(svu next)
-VER=${TAG#v}
-# bump deploy/charts/grex/Chart.yaml version + appVersion to $VER and commit
 git tag "$TAG"
-git push origin HEAD "$TAG"
+git push origin "$TAG"
 ```
 
 ## What the release pipeline publishes
 
-Configuration lives in `.goreleaser.yaml` at the repository root. On a
-version tag, GoReleaser (plus the workflow’s Helm steps) publishes:
+Configuration lives in `.goreleaser.yaml` at the repository root, plus
+`.github/workflows/helm-release.yaml` for the chart. On a version tag, these
+publish:
 
 | Artifact | Destination |
 |----------|-------------|
 | Cross-compiled binaries (linux / darwin / windows × amd64 / arm64) | GitHub Release assets (archives + `checksums.txt`) |
 | Container images | GHCR (`ghcr.io/dennisme/grex`) multi-arch (amd64 + arm64) |
-| Helm chart package (`.tgz`) | GitHub Release asset |
+| Helm chart package (`.tgz`) | Its own GitHub Release (`helm-grex-VERSION`), published by `helm-release.yaml` (`cr`) |
 | Helm chart (OCI) | `oci://ghcr.io/dennisme/charts/grex` |
-| Helm chart (Pages index) | `https://dennisme.github.io/grex/charts/` via the **docs** workflow after the chart bump lands on `main` |
+| Helm chart (Pages index) | `https://dennisme.github.io/grex/charts/`, `cr` pushes `index.yaml` to `gh-pages`, the **docs** workflow mirrors it in on the next run |
 | Release notes (changelog) | GitHub Release body |
 
 Image tags include `{{ .Version }}` (no `v`, matches chart `appVersion`),
@@ -118,18 +124,21 @@ local source builds and compose/Helm smoke tests.
 
 | Field | Source | Meaning |
 |-------|--------|---------|
-| Chart `version` | bumped by `just release-tag` | Helm package / repo version |
-| Chart `appVersion` | same SemVer string | Default container image tag |
-| Git tag | `svu next` (with `v` prefix) | Triggers GoReleaser |
+| Chart `version` (in `Chart.yaml`) | fixed `0.0.0` placeholder, never edited | Not read for a real release |
+| Chart `version` (as packaged/published) | explicit `--version "$VER"` at package time, in `goreleaser.yaml` and `helm-release.yaml` | Helm package / repo version |
+| Chart `appVersion` (as packaged/published) | explicit `--app-version "$VER"`, same string | Default container image tag |
+| Git tag | `svu next` (with `v` prefix) | Triggers both `goreleaser.yaml` and `helm-release.yaml` |
 
 For grex 1.0, **chart version and app version stay equal** to the grex release.
 Chart-only fixes still ship as a normal grex patch release (no separate chart
-version stream yet).
+version stream yet). Both workflows derive `$VER` the same way
+(`${GITHUB_REF_NAME#v}`), so they can't drift from each other even though
+they run independently.
 
 **Install after a release:**
 
 ```sh
-# Chart repository on GitHub Pages (updated when main deploys docs)
+# Chart repository on GitHub Pages (index refreshed once helm-release + docs finish)
 helm repo add grex https://dennisme.github.io/grex/charts/
 helm repo update
 helm upgrade --install grex grex/grex --version 0.2.0 -n grex --create-namespace
@@ -139,8 +148,10 @@ helm upgrade --install grex oci://ghcr.io/dennisme/charts/grex --version 0.2.0 \
   -n grex --create-namespace
 ```
 
-Pages always packages the chart version currently on `main`. Historical
-`.tgz` files are kept on each GitHub Release and on GHCR (OCI).
+The Pages index reflects whatever `helm-release.yaml` last pushed to
+`gh-pages`, not whatever's on `main` (there's nothing chart-related to
+package from `main` anymore). Historical `.tgz` files are kept on each
+chart's own GitHub Release and on GHCR (OCI).
 
 ### Pretty release notes (changelog)
 
@@ -185,13 +196,16 @@ gh api repos/dennisme/grex/releases/generate-notes \
 ## After the release
 
 - Confirm the [GitHub Releases](https://github.com/dennisme/grex/releases) page
-  lists the new tag, binary archives, and `grex-<version>.tgz`
+  lists the new app tag with its binary archives
+- Confirm a second GitHub Release `helm-grex-<version>` exists with the
+  chart `.tgz` asset (published by `helm-release.yaml`)
 - Confirm the GHCR image `ghcr.io/dennisme/grex:<version>` exists
 - Confirm the OCI chart `oci://ghcr.io/dennisme/charts/grex` is pullable at
   that version
-- Confirm the docs workflow on `main` finished so
-  [the chart repo](https://dennisme.github.io/grex/charts/) indexes the new
-  chart (path-filtered; needs the chart bump commit on `main`)
+- Confirm `helm-release.yaml` finished (it pushes the updated index to
+  `gh-pages`), then confirm the **docs** workflow's `workflow_run` trigger
+  fired after it so [the chart repo](https://dennisme.github.io/grex/charts/)
+  indexes the new chart
 - Confirm the docs workflow also ran on the **release published** event so
   [Releases → Changelog](../releases/changelog.md) includes the new notes
 
@@ -214,6 +228,14 @@ Confirm the tag was pushed to the repo that owns
 `.github/workflows/goreleaser.yaml`, and that the workflow triggers on that
 tag pattern.
 
+**Chart repo on Pages shows the old version**  
+`cr` (in `helm-release.yaml`) publishes the chart's GitHub Release *before*
+it finishes pushing the updated `index.yaml` to `gh-pages`. The docs
+workflow's `workflow_run` trigger waits for `helm-release.yaml` to fully
+complete before mirroring the index, so this should self-correct once that
+run finishes. If `helm-release.yaml` failed outright, re-run it (or push a
+no-op tag fix) rather than editing `gh-pages` by hand.
+
 ## Related
 
 - [Contributing](contributing.md) — conventional commits and PR CI

docs/releases/index.md

@@ -63,17 +63,19 @@ Full operator install paths (Compose, from source, TLS, etc.):
 |----------|--------------|--------|
 | Cross-compiled binaries + checksums | GoReleaser → GitHub Release | linux / darwin / windows × amd64 / arm64 |
 | Multi-arch container image | GoReleaser → GHCR | Tags: `VERSION`, `vVERSION`, major/minor aliases, `latest` |
-| Helm chart `.tgz` | GoReleaser → GitHub Release asset | Same SemVer as `Chart.yaml` |
+| Helm chart `.tgz` | helm-release workflow (`cr`) → its own GitHub Release (`helm-grex-VERSION`) | Version comes from an explicit `--version` override at package time, not from `Chart.yaml` |
 | Helm chart OCI | GoReleaser workflow → GHCR | `oci://ghcr.io/dennisme/charts/grex` |
-| Helm chart on Pages | docs workflow on `main` | Repo index at `/charts/` |
+| Helm chart on Pages | helm-release workflow pushes `index.yaml` to `gh-pages`; docs workflow mirrors it into `/charts/` | Repo index only; the `.tgz` itself downloads from the chart's GitHub Release asset |
 | Release notes body | GoReleaser changelog | Grouped by commit type; PR links from `(#N)` squash subjects |
 
 ## Versioning
 
 - **Git tags:** `vMAJOR.MINOR.PATCH` (via [`svu`](https://github.com/caarlos0/svu)
   / `just release-tag`)
 - **Helm `version` / `appVersion` and default image tag:** `MAJOR.MINOR.PATCH`
-  (no `v`)
+  (no `v`), set via an explicit `--version`/`--app-version` override at
+  package time in CI. `deploy/charts/grex/Chart.yaml` itself stays a fixed
+  `0.0.0` placeholder and is never edited as part of a release.
 - **Breaking changes:** conventional `BREAKING CHANGE` / `type!:` → major bump
 
 See the [Changelog](changelog.md) for notes per tag, or the