Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

ci: publish the Helm chart to GHCR as an OCI artifact (#707)

Rubén Gómez2666e53e1f45
diff --git a/.github/workflows/publish-chart.yml b/.github/workflows/publish-chart.yml
new file mode 100644
index 00000000..986a4e82
--- /dev/null
+++ b/.github/workflows/publish-chart.yml
@@ -0,0 +1,126 @@
+name: Publish chart
+
+# Packages charts/itsaplan and pushes it to GHCR as an OCI artifact, so the chart
+# installs without cloning the repository:
+#
+# helm install itsaplan oci://ghcr.io/croffasia/charts/itsaplan --version 1.9.0
+#
+# Called by release.yml once a release is tagged, next to publish-images, so the
+# published chart is always the one that deploys that release's images. The manual
+# trigger republishes an existing tag.
+
+on:
+ workflow_call:
+ inputs:
+ tag:
+ description: The release tag to publish, e.g. v1.9.0
+ required: true
+ type: string
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: The release tag to publish, e.g. v1.9.0
+ required: true
+ type: string
+
+env:
+ REGISTRY: ghcr.io
+ CHART_DIR: charts/itsaplan
+
+permissions:
+ contents: read
+
+jobs:
+ publish:
+ name: Package and push to OCI
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ # GITHUB_TOKEN may create the package even though the repository default is
+ # read-only, because this job asks for the permission explicitly.
+ packages: write
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ ref: ${{ inputs.tag }}
+
+ # helm ships with the ubuntu runner image; printing the version keeps a
+ # packaging difference traceable, and the documented floor is 3.10.
+ - name: Helm version
+ run: helm version --short
+
+ # The chart version has to be the release: release-please bumps both fields
+ # of Chart.yaml (each carries the x-release-please-version annotation), so a
+ # mismatch means a release PR carried only one of them. Failing here beats
+ # publishing 0.1.0 over every previous release forever.
+ - name: Check the chart version against the tag
+ id: chart
+ env:
+ TAG: ${{ inputs.tag }}
+ run: |
+ set -euo pipefail
+ chart_version=$(helm show chart "$CHART_DIR" | awk '/^version:/ {print $2}')
+ app_version=$(helm show chart "$CHART_DIR" | awk '/^appVersion:/ {print $2}')
+ echo "Chart.yaml ships version $chart_version (appVersion $app_version)."
+ if [ "v$chart_version" != "$TAG" ]; then
+ echo "::error file=$CHART_DIR/Chart.yaml::Chart.yaml is at $chart_version but the release is $TAG."
+ exit 1
+ fi
+ echo "version=$chart_version" >> "$GITHUB_OUTPUT"
+ echo "app_version=$app_version" >> "$GITHUB_OUTPUT"
+
+ - name: Lint
+ run: helm lint "$CHART_DIR"
+
+ - name: Package
+ run: helm package "$CHART_DIR" --destination dist
+
+ - name: Log in to the registry
+ run: |
+ echo "${{ secrets.GITHUB_TOKEN }}" \
+ | helm registry login "$REGISTRY" --username "${{ github.actor }}" --password-stdin
+
+ - name: Push
+ id: push
+ run: |
+ set -euo pipefail
+ helm push "dist/itsaplan-${{ steps.chart.outputs.version }}.tgz" \
+ "oci://$REGISTRY/${{ github.repository_owner }}/charts" | tee push.log
+ digest=$(awk '/^Digest:/ {print $2}' push.log)
+ echo "digest=$digest" >> "$GITHUB_OUTPUT"
+ echo "ref=oci://$REGISTRY/${{ github.repository_owner }}/charts/itsaplan:${{ steps.chart.outputs.version }}" >> "$GITHUB_OUTPUT"
+
+ # A push that reported a digest still proves nothing about what a consumer
+ # gets back: pull it and render it as helm would. helm rewrites Chart.yaml
+ # on package (key order, comment and quote normalisation), so the manifests
+ # are what to compare, not the file bytes.
+ - name: Read the artifact back
+ run: |
+ set -euo pipefail
+ ref="${{ steps.push.outputs.ref }}"
+ helm show chart "$ref"
+ pulled_version=$(helm show chart "$ref" | awk '/^version:/ {print $2}')
+ if [ "$pulled_version" != "${{ steps.chart.outputs.version }}" ]; then
+ echo "::error::Published $ref reports version $pulled_version."
+ exit 1
+ fi
+ helm pull "$ref" --untar --untardir /tmp/pulled
+ diff -r "$CHART_DIR/templates" /tmp/pulled/itsaplan/templates
+ helm template verify "$CHART_DIR" > /tmp/source.yaml
+ helm template verify "$ref" > /tmp/pulled.yaml
+ diff /tmp/source.yaml /tmp/pulled.yaml
+ resources=$(grep -c '^kind:' /tmp/pulled.yaml || true)
+ echo "The artifact renders the same $resources resources as the source chart."
+
+ - name: Summary
+ run: |
+ {
+ echo "### Chart published"
+ echo
+ echo '```'
+ echo "helm install itsaplan ${{ steps.push.outputs.ref }} --version ${{ steps.chart.outputs.version }}"
+ echo '```'
+ echo
+ echo "- digest: \`${{ steps.push.outputs.digest }}\`"
+ echo "- appVersion, the default image tag: \`${{ steps.chart.outputs.app_version }}\`"
+ } >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 324e7d6d..9225c427 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -82,3 +82,17 @@ jobs:
uses: ./.github/workflows/publish-images.yml
with:
tag: ${{ needs.move-release-branch.outputs.tag }}
+
+ # The chart as an OCI artifact for self-hosters: `helm install oci://…` instead
+ # of cloning the repository. Runs beside publish-images because the chart it
+ # publishes is the one that deploys those images.
+ publish-chart:
+ name: Publish chart
+ needs: move-release-branch
+ if: ${{ needs.move-release-branch.outputs.tag != '' }}
+ permissions:
+ contents: read
+ packages: write
+ uses: ./.github/workflows/publish-chart.yml
+ with:
+ tag: ${{ needs.move-release-branch.outputs.tag }}
diff --git a/charts/itsaplan/Chart.yaml b/charts/itsaplan/Chart.yaml
index a6e4cdff..36631a7c 100644
--- a/charts/itsaplan/Chart.yaml
+++ b/charts/itsaplan/Chart.yaml
@@ -1,6 +1,6 @@
apiVersion: v2
name: itsaplan
description: Self-hosted project management and issue tracking platform
-version: 0.1.0
+version: 0.1.0 # x-release-please-version
appVersion: "1.8.0" # x-release-please-version
type: application
\ No newline at end of file
diff --git a/docs/helm.md b/docs/helm.md
index 4b1d6d97..45c35cd0 100644
--- a/docs/helm.md
+++ b/docs/helm.md
@@ -33,6 +33,19 @@ Install the chart:
helm install itsaplan charts/itsaplan -f values.yaml
```
+### Install from the OCI registry
+
+Every release publishes the chart to GHCR, so a clone is optional. The chart version is the release
+version, and `appVersion` inside it is the image tag it deploys:
+
+```bash
+helm install itsaplan oci://ghcr.io/croffasia/charts/itsaplan --version 1.9.0 -f values.yaml
+```
+
+`helm show values oci://ghcr.io/croffasia/charts/itsaplan --version 1.9.0` prints the defaults to start a
+values file from. Only released versions are published, so pin `--version` where the deployment has to
+stay put: in the values file of a GitOps app spec, or in the install command.
+
For the Pro edition, pass `charts/itsaplan/values-pro.yaml` before it. Without a valid license
the Pro images run as the core does; the license key is entered in god mode, under **License**.