CI: Add Docker image size testing and PR comment on large increases.

Add test-docker-image-sizes.bash to query compressed image sizes from
GHCR and compare them against a baseline. Supports single tutorial,
all tutorials, and history modes with text, markdown, and JSON output.

Add test-docker-image-sizes.yml workflow triggered after builds to
produce a job summary table, and pr-comment-docker-image-sizes.yml to
warn on PRs when any image changes by more than 5%.

Author: brycelelbach

.github/workflows/pr-comment-docker-image-sizes.yml

@@ -0,0 +1,142 @@
+name: PR Comment on Docker Image Sizes
+
+on:
+  workflow_dispatch:
+    inputs:
+      workflow_run_id:
+        description: "Run ID of the test workflow to download artifacts from"
+        required: true
+        type: string
+
+# Write permissions for commenting — this workflow never checks out or runs
+# untrusted PR code, keeping it separate from the test workflow that does.
+permissions:
+  pull-requests: write
+  actions: read
+
+jobs:
+  comment:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Download PR comment data
+        uses: actions/download-artifact@v4
+        with:
+          name: pr-comment-data
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          run-id: ${{ inputs.workflow_run_id }}
+
+      - name: Post comment on PR
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+
+            const prNumber = parseInt(fs.readFileSync('pr_number', 'utf8').trim());
+            if (!prNumber || isNaN(prNumber)) {
+              console.log('No valid PR number found, skipping comment.');
+              return;
+            }
+
+            const warningCount = parseInt(fs.readFileSync('warning_count', 'utf8').trim());
+            const threshold = parseInt(fs.readFileSync('threshold', 'utf8').trim());
+            const results = JSON.parse(fs.readFileSync('results.json', 'utf8'));
+            const runUrl = `${process.env.GITHUB_SERVER_URL}/${process.env.GITHUB_REPOSITORY}/actions/runs/${{ inputs.workflow_run_id }}`;
+
+            const COMMENT_MARKER = '<!-- docker-image-size-check -->';
+
+            // Find existing bot comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+            });
+            const existing = comments.find(c =>
+              c.user.type === 'Bot' && c.body.includes(COMMENT_MARKER)
+            );
+
+            if (warningCount === 0) {
+              // No warnings — resolve any existing comment
+              if (existing) {
+                const body = [
+                  COMMENT_MARKER,
+                  `## ✅ Docker Image Sizes OK`,
+                  ``,
+                  `All tutorial images are within the **${threshold}%** size threshold compared to \`main\`.`,
+                  ``,
+                  `[View full size report →](${runUrl})`,
+                ].join('\n');
+
+                await github.rest.issues.updateComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  comment_id: existing.id,
+                  body,
+                });
+                console.log(`Updated comment on PR #${prNumber} to resolved.`);
+              } else {
+                console.log('No size warnings and no existing comment. Nothing to do.');
+              }
+              return;
+            }
+
+            // Build warning table (only tutorials exceeding threshold)
+            const warnings = results.filter(r =>
+              !r.error && r.baseline_exists && (r.diff_pct > threshold || r.diff_pct < -threshold)
+            );
+
+            let warningRows = warnings.map(r =>
+              `| ${r.tutorial} | ${r.current_size_human} | ${r.baseline_size_human} | **${r.change_human}** |`
+            ).join('\n');
+
+            // Build full table (all tutorials)
+            let allRows = results.map(r => {
+              if (r.error)
+                return `| ${r.tutorial} | _(error)_ | — | — |`;
+              if (!r.baseline_exists)
+                return `| ${r.tutorial} | ${r.current_size_human} | _(not found)_ | — |`;
+              const bold = (r.diff_pct > threshold || r.diff_pct < -threshold) ? '**' : '';
+              return `| ${r.tutorial} | ${r.current_size_human} | ${r.baseline_size_human} | ${bold}${r.change_human}${bold} |`;
+            }).join('\n');
+
+            const body = [
+              COMMENT_MARKER,
+              `## ⚠️ Docker Image Size Warning`,
+              ``,
+              `**${warningCount}** tutorial image(s) changed by more than **${threshold}%** compared to \`main\`:`,
+              ``,
+              `| Tutorial | Current | Main | Change |`,
+              `|:---------|--------:|-----:|-------:|`,
+              warningRows,
+              ``,
+              `<details>`,
+              `<summary>📊 Full size report for all tutorials</summary>`,
+              ``,
+              `| Tutorial | Current | Main | Change |`,
+              `|:---------|--------:|-----:|-------:|`,
+              allRows,
+              ``,
+              `</details>`,
+              ``,
+              `> **Tip:** Review recent Dockerfile changes for unintended dependency additions.`,
+              ``,
+              `[View full size report →](${runUrl})`,
+            ].join('\n');
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+              console.log(`Updated existing comment on PR #${prNumber}`);
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: prNumber,
+                body,
+              });
+              console.log(`Created comment on PR #${prNumber}`);
+            }

.github/workflows/test-docker-image-sizes.yml

@@ -0,0 +1,142 @@
+name: Test Docker Image Sizes
+
+on:
+  workflow_run:
+    workflows: ["Build and Push Brev Tutorial Docker Images"]
+    types: [completed]
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: "Branch name (for tag construction)"
+        required: false
+        type: string
+      sha:
+        description: "Git SHA (for tag construction)"
+        required: false
+        type: string
+
+jobs:
+  test-image-sizes:
+    name: test-image-sizes
+    runs-on: ubuntu-latest
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      github.event.workflow_run.conclusion == 'success' ||
+      github.event.workflow_run.conclusion == 'failure'
+    permissions:
+      contents: read
+      packages: read
+      actions: write
+    defaults:
+      run:
+        working-directory: ${{ github.workspace }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.sha }}
+
+      - name: Set variables
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_run" ]; then
+            GIT_BRANCH_NAME="${{ github.event.workflow_run.head_branch }}"
+            GIT_SHA="${{ github.event.workflow_run.head_sha }}"
+          elif [ -n "${{ inputs.branch }}" ]; then
+            GIT_BRANCH_NAME="${{ inputs.branch }}"
+            GIT_SHA="${{ inputs.sha || github.sha }}"
+          else
+            GIT_BRANCH_NAME="${GITHUB_REF#refs/heads/}"
+            GIT_SHA="${{ github.sha }}"
+          fi
+
+          DOCKER_TAG_BRANCH=$(echo "${GIT_BRANCH_NAME}" | sed 's/[^a-zA-Z0-9._-]/-/g' | tr '[:upper:]' '[:lower:]')
+          GIT_SHORT_SHA=${GIT_SHA:0:7}
+
+          # Extract PR number from pull-request/* branches
+          PR_NUMBER=""
+          if [[ "$GIT_BRANCH_NAME" =~ ^pull-request/([0-9]+)$ ]]; then
+            PR_NUMBER="${BASH_REMATCH[1]}"
+          fi
+
+          echo "GIT_BRANCH_NAME=${GIT_BRANCH_NAME}" >> $GITHUB_ENV
+          echo "DOCKER_TAG_BRANCH=${DOCKER_TAG_BRANCH}" >> $GITHUB_ENV
+          echo "GIT_SHA=${GIT_SHA}" >> $GITHUB_ENV
+          echo "GIT_SHORT_SHA=${GIT_SHORT_SHA}" >> $GITHUB_ENV
+          echo "OWNER=${GITHUB_REPOSITORY_OWNER,,}" >> $GITHUB_ENV
+          echo "PR_NUMBER=${PR_NUMBER}" >> $GITHUB_ENV
+
+      - name: Collect image sizes
+        id: sizes
+        run: |
+          IMAGE_TAG="${DOCKER_TAG_BRANCH}-git-${GIT_SHORT_SHA}"
+          THRESHOLD=5
+
+          RESULTS=$(brev/test-docker-image-sizes.bash compare \
+            --owner "${OWNER}" \
+            --tutorial all \
+            --tag "${IMAGE_TAG}" \
+            --baseline "main-latest" \
+            --format json)
+
+          # Count tutorials exceeding the threshold
+          WARNING_COUNT=$(echo "$RESULTS" | jq --argjson t "$THRESHOLD" \
+            '[.[] | select(.diff_pct != null and ((.diff_pct > $t) or (.diff_pct < -$t)))] | length')
+          ERRORS=$(echo "$RESULTS" | jq '[.[] | select(.error == true)] | length')
+
+          # --- Build job summary ---
+          {
+            echo "## 📦 Docker Image Size Report"
+            echo ""
+            echo "**Branch:** \`${GIT_BRANCH_NAME}\` (\`${GIT_SHORT_SHA}\`)"
+            echo "**Baseline:** \`main-latest\`"
+            echo ""
+            echo "| Tutorial | Current | Baseline | Change | |"
+            echo "|:---------|--------:|---------:|-------:|:---:|"
+
+            echo "$RESULTS" | jq -r --argjson t "$THRESHOLD" '.[] |
+              if .error then
+                "| " + .tutorial + " | _(error)_ | — | — | ❌ |"
+              elif .baseline_exists == false then
+                "| " + .tutorial + " | " + .current_size_human + " | _(not found)_ | — | ➖ |"
+              else
+                (if ((.diff_pct > $t) or (.diff_pct < (-1 * $t))) then "⚠️" else "✅" end) as $icon |
+                "| " + .tutorial + " | " + .current_size_human + " | " + .baseline_size_human + " | " + .change_human + " | " + $icon + " |"
+              end'
+
+            echo ""
+            if [ "$WARNING_COUNT" -gt 0 ]; then
+              echo "> ⚠️ **${WARNING_COUNT} image(s) changed by more than ${THRESHOLD}%.** Large increases may indicate unnecessary dependencies."
+            elif [ "$ERRORS" -gt 0 ]; then
+              echo "> ❌ **${ERRORS} image(s) could not be checked.** This is expected if the build failed for those tutorials."
+            else
+              echo "> ✅ All images are within the ${THRESHOLD}% size threshold."
+            fi
+          } >> $GITHUB_STEP_SUMMARY
+
+          # --- Save PR comment data ---
+          mkdir -p pr-comment-data
+          echo "${PR_NUMBER}" > pr-comment-data/pr_number
+          echo "${WARNING_COUNT}" > pr-comment-data/warning_count
+          echo "${THRESHOLD}" > pr-comment-data/threshold
+          echo "$RESULTS" > pr-comment-data/results.json
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Upload PR comment data
+        if: env.PR_NUMBER != ''
+        uses: actions/upload-artifact@v4
+        with:
+          name: pr-comment-data
+          path: pr-comment-data/
+          retention-days: 1
+
+      - name: Trigger PR comment workflow
+        if: env.PR_NUMBER != ''
+        run: |
+          echo "Triggering PR comment workflow for PR #${PR_NUMBER}"
+          gh workflow run pr-comment-docker-image-sizes.yml \
+            --ref ${GIT_BRANCH_NAME} \
+            -f workflow_run_id=${{ github.run_id }}
+          echo "PR comment workflow triggered successfully"
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}