Document docker and helm tags

.github/workflows/docker.yml

@@ -12,6 +12,10 @@ concurrency:
   group: docker-${{ github.ref }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   build:
     runs-on: ubuntu-latest
@@ -146,3 +150,56 @@ jobs:
           push: ${{ steps.registry.outputs.publish == 'true' }}
           cache-from: ${{ steps.registry.outputs.publish == 'true' && join(fromJson(steps.cache.outputs.from-json), '\n') || '' }}
           cache-to: ${{ steps.registry.outputs.publish == 'true' && join(fromJson(steps.cache.outputs.to-json), '\n') || '' }}
+
+  comment:
+    needs: build
+    # Comments require a write token, which fork PRs don't get, so skip them there.
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+
+      - name: Compute workflow metadata
+        id: workflow-metadata
+        uses: ./.github/actions/workflow-metadata
+
+      - name: Build comment
+        id: comment
+        shell: bash
+        env:
+          APP_JSON: ${{ steps.workflow-metadata.outputs.app-version-json }}
+        run: |
+          STABLE_TAG=$(echo "${APP_JSON}" | jq --raw-output '."stable-tag"')
+          TAG_LIST=$(echo "${APP_JSON}" | jq --raw-output \
+            --arg pr "pr.${{ github.event.number }}" \
+            '(.tags + [$pr]) | map("`" + . + "`") | join(", ")')
+
+          BACKEND=quay.io/nebari/nebari-chat-backend
+          FRONTEND=quay.io/nebari/nebari-chat-frontend
+
+          {
+            echo "## Docker images"
+            echo
+            echo "Built from ${{ github.event.pull_request.head.sha }}."
+            echo
+            echo "| Image | Tags |"
+            echo "| --- | --- |"
+            echo "| \`${BACKEND}\` | ${TAG_LIST} |"
+            echo "| \`${FRONTEND}\` | ${TAG_LIST} |"
+            echo
+            echo '```sh'
+            echo "docker pull ${BACKEND}:${STABLE_TAG}"
+            echo "docker pull ${FRONTEND}:${STABLE_TAG}"
+            echo '```'
+          } > comment.md
+
+      - name: Post comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: docker-tags
+          path: comment.md

.github/workflows/helm.yml

@@ -12,6 +12,10 @@ concurrency:
   group: helm-${{ github.ref }}
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   metadata:
     runs-on: ubuntu-latest
@@ -98,3 +102,51 @@ jobs:
       - name: Push helm chart
         if: steps.registry.outputs.publish == 'true'
         run: helm push nebari-chat-*.tgz oci://quay.io/nebari/charts
+
+  comment:
+    needs: helm
+    # Comments require a write token, which fork PRs don't get, so skip them there.
+    if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+          fetch-depth: 0
+
+      - name: Compute workflow metadata
+        id: workflow-metadata
+        uses: ./.github/actions/workflow-metadata
+
+      - name: Build comment
+        id: comment
+        shell: bash
+        env:
+          CHART_JSON: ${{ steps.workflow-metadata.outputs.chart-version-json }}
+        run: |
+          STABLE_TAG=$(echo "${CHART_JSON}" | jq --raw-output '."stable-tag"')
+          TAG_LIST=$(echo "${CHART_JSON}" | jq --raw-output '.tags | map("`" + . + "`") | join(", ")')
+
+          CHART=oci://quay.io/nebari/charts/nebari-chat
+
+          {
+            echo "## Helm chart"
+            echo
+            echo "Built from ${{ github.event.pull_request.head.sha }}."
+            echo
+            echo "| Chart | Versions |"
+            echo "| --- | --- |"
+            echo "| \`${CHART}\` | ${TAG_LIST} |"
+            echo
+            echo '```sh'
+            echo "helm install chat ${CHART} --version ${STABLE_TAG}"
+            echo '```'
+          } > comment.md
+
+      - name: Post comment
+        uses: marocchino/sticky-pull-request-comment@v2
+        with:
+          header: helm-tags
+          path: comment.md

README.md

@@ -54,6 +54,26 @@ Docker images for the frontend and backend are published by pushing a `v$SEMVER`
 > [!IMPORTANT]
 > Do not push the app and chart tags at the same time. Each tag triggers the release workflow independently, and if the chart tag arrives first, the chart may reference the previous app version instead of the newly tagged one.
 
+## Available tags
+
+Every build publishes a set of tags that depends on what triggered it. `<base>` is the next version computed from the most recent tag (e.g. `v1.2.4`); `<semver>` is the version of the release tag (e.g. `v1.2.3`); `<pr>` is the PR number; `<commit>` is the short commit SHA.
+
+Docker images (`quay.io/nebari/nebari-chat-backend` and `quay.io/nebari/nebari-chat-frontend`):
+
+| Trigger | Tags |
+| --- | --- |
+| Release (`v$SEMVER`) | `<semver>`, `latest` |
+| Push to `main` | `<base>-main`, `main` |
+| Pull request | `<base>-pr.<pr>.<commit>`, `<base>-pr.<pr>`, `pr.<pr>` |
+
+Helm chart (`oci://quay.io/nebari/charts/nebari-chat`):
+
+| Trigger | Tags |
+| --- | --- |
+| Release (`chart/v$SEMVER`) | `<semver>` |
+| Push to `main` | `<base>-main` |
+| Pull request | `<base>-pr.<pr>.<commit>`, `<base>-pr.<pr>` |
+
 ## License
 
 Apache 2.0 — see [LICENSE](LICENSE).