feat(ci): skip build and deploy for unchanged apps

Add a changes job that diffs HEAD~1..HEAD and outputs which apps were
affected. Build and deploy jobs consume the output:

- build matrix is restricted to changed apps only — unchanged apps are
  never built or pushed
- deploy pulls only rebuilt images and restarts only those containers

Shared triggers (packages/, convex/, package-lock.json, turbo.json) mark
both apps as changed since they affect the full dependency tree.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.gitea/workflows/deploy-staging.yml

@@ -11,25 +11,80 @@ on:
 # (see: troubleshooting #8 — REGISTRY must include the owner segment)
 #
 # Required secrets (repo → Settings → Secrets and Variables → Actions):
-#   STAGING_REGISTRY                        — host:port/owner  (e.g. git.yourdomain.com:3000/myorg)
-#   STAGING_REGISTRY_USER                   — Gitea username
-#   STAGING_REGISTRY_TOKEN                  — Gitea personal access token (package:write scope)
-#   STAGING_SSH_HOST                        — use host.containers.internal, not the external IP
-#                                             (see: troubleshooting #13 — VPS firewall blocks ext IP)
-#   STAGING_SSH_USER                        — SSH user on the VPS
-#   STAGING_SSH_KEY                         — SSH private key (full PEM)
-#   STAGING_SSH_PORT                        — (optional) defaults to 22
-#   STAGING_NEXT_PUBLIC_CONVEX_URL                  — Convex deployment URL (shared)
-#   STAGING_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY        — storefront Clerk publishable key
-#   STAGING_ADMIN_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY  — admin Clerk publishable key
-#   STAGING_NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME        — admin Cloudinary cloud name
-#
-# The Dockerfiles are expected at:
-#   apps/storefront/Dockerfile
-#   apps/admin/Dockerfile
-# Both receive ./out as build context (turbo prune output).
+#   STAGING_REGISTRY                                    — host:port/owner
+#   STAGING_REGISTRY_USER                               — Gitea username
+#   STAGING_REGISTRY_TOKEN                              — Gitea PAT (package:write)
+#   STAGING_SSH_HOST                                    — host.containers.internal
+#   STAGING_SSH_USER                                    — SSH user on the VPS
+#   STAGING_SSH_KEY                                     — SSH private key (full PEM)
+#   STAGING_SSH_PORT                                    — (optional) defaults to 22
+#   STAGING_NEXT_PUBLIC_CONVEX_URL
+#   STAGING_STOREFRONT_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
+#   STAGING_ADMIN_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
+#   STAGING_NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME
+#   STAGING_NEXT_PUBLIC_CLOUDINARY_API_KEY
+#   STAGING_NEXT_PUBLIC_IMAGE_PROCESSING_API_URL
+#   STAGING_NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY
+#   STAGING_STOREFRONT_CLERK_SECRET_KEY
+#   STAGING_ADMIN_CLERK_SECRET_KEY
+#   STAGING_CLOUDINARY_API_SECRET
 
 jobs:
+  # ── 0. Detect changes ────────────────────────────────────────────────────────
+  # Determines which apps have changed so downstream jobs skip unchanged ones.
+  # Rules:
+  #   apps/storefront/**            → storefront
+  #   apps/admin/**                 → admin
+  #   packages/**, convex/**        → both (shared code)
+  #   package.json, package-lock.json, turbo.json → both (root config)
+
+  changes:
+    name: Detect changed apps
+    runs-on: ubuntu-latest
+    outputs:
+      matrix: ${{ steps.detect.outputs.matrix }}
+      storefront: ${{ steps.detect.outputs.storefront }}
+      admin: ${{ steps.detect.outputs.admin }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Determine affected apps
+        id: detect
+        run: |
+          # Fall back to diffing against an empty tree on the very first commit
+          BASE=$(git rev-parse HEAD~1 2>/dev/null || git hash-object -t tree /dev/null)
+          CHANGED=$(git diff --name-only "$BASE" HEAD)
+
+          STOREFRONT=false
+          ADMIN=false
+
+          # Shared paths affect both apps
+          if echo "$CHANGED" | grep -qE '^(package\.json|package-lock\.json|turbo\.json|packages/|convex/)'; then
+            STOREFRONT=true
+            ADMIN=true
+          fi
+
+          echo "$CHANGED" | grep -q '^apps/storefront/' && STOREFRONT=true
+          echo "$CHANGED" | grep -q '^apps/admin/'      && ADMIN=true
+
+          # Build JSON matrix for the build job
+          APPS=()
+          [ "$STOREFRONT" = "true" ] && APPS+=("storefront")
+          [ "$ADMIN"      = "true" ] && APPS+=("admin")
+
+          if [ ${#APPS[@]} -eq 0 ]; then
+            MATRIX="[]"
+          else
+            MATRIX=$(printf '"%s",' "${APPS[@]}" | sed 's/,$//')
+            MATRIX="[${MATRIX}]"
+          fi
+
+          echo "matrix=${MATRIX}"    >> "$GITHUB_OUTPUT"
+          echo "storefront=${STOREFRONT}" >> "$GITHUB_OUTPUT"
+          echo "admin=${ADMIN}"      >> "$GITHUB_OUTPUT"
+
   # ── 1. CI ───────────────────────────────────────────────────────────────────
 
   ci:
@@ -57,16 +112,17 @@ jobs:
         run: npm run test:once
 
   # ── 2. Build & push ─────────────────────────────────────────────────────────
-  # Runs storefront and admin in parallel via matrix.
-  # Each job prunes its own workspace so there is no out/ directory collision.
+  # Matrix is restricted to apps that actually changed — unchanged apps are
+  # skipped entirely so their build minutes are not wasted.
 
   build:
     name: Build & push — ${{ matrix.app }}
-    needs: ci
+    needs: [ci, changes]
+    if: needs.changes.outputs.matrix != '[]'
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        app: [storefront, admin]
+        app: ${{ fromJson(needs.changes.outputs.matrix) }}
 
     steps:
       - uses: actions/checkout@v4
@@ -83,22 +139,16 @@ jobs:
       - name: Prune workspace for ${{ matrix.app }}
         run: |
           npx turbo prune ${{ matrix.app }} --docker
-          # turbo prune only traces npm workspace packages. The root convex/ directory
-          # is not a workspace package, so it is excluded from out/full/ — causing
-          # "Module not found: convex/_generated/api" at build time.
-          # Copy it manually so the Dockerfile has the generated types it needs.
+          # convex/ is not an npm workspace so turbo prune excludes it — copy manually
           cp -r convex out/full/convex
-          # turbo prune cannot fully parse the npm 11 lockfile format, so it generates
-          # an incomplete out/package-lock.json that omits non-hoisted workspace entries
-          # (e.g. apps/storefront/node_modules/@heroui/react). Replace it with the full
-          # root lockfile so that npm ci in Docker installs every package correctly.
+          # turbo prune can't fully parse the npm 11 lockfile; replace with full lockfile
+          # so non-hoisted packages (e.g. apps/storefront/node_modules/@heroui/react)
+          # are present when npm ci runs inside the Docker build.
           cp package-lock.json out/package-lock.json
 
       - name: Authenticate with registry
-        # docker login sends HTTPS even for HTTP-only (insecure) registries, so it
-        # fails before the daemon can handle it. Pre-populating config.json bypasses
-        # login entirely — docker push goes through the Podman daemon which correctly
-        # uses HTTP. (see: troubleshooting #7)
+        # docker login fails for HTTP-only registries — pre-populate config.json instead
+        # (see: troubleshooting #7)
         run: |
           mkdir -p ~/.docker
           AUTH=$(echo -n "${{ secrets.STAGING_REGISTRY_USER }}:${{ secrets.STAGING_REGISTRY_TOKEN }}" | base64 -w 0)
@@ -106,17 +156,8 @@ jobs:
           echo "{\"auths\":{\"${REGISTRY_HOST}\":{\"auth\":\"${AUTH}\"}}}" > ~/.docker/config.json
 
       - name: Build & push ${{ matrix.app }}
-        # --push bypasses the Podman daemon and uses buildkit's internal HTTPS push,
-        # which fails for HTTP-only registries. Instead:
-        #   1. --load loads the image into the Podman daemon after build
-        #   2. docker push goes through the daemon, which has insecure=true in
-        #      registries.conf and correctly uses HTTP. (see: troubleshooting #7, #12)
-        #
-        # Each app has its own Clerk instance so the publishable key differs.
-        # NEXT_PUBLIC_* vars must be baked in at build time — Next.js prerender
-        # fails with "Missing publishableKey" if they are absent.
-        # Secrets use STAGING_/PROD_ prefix in Gitea; the prefix is stripped here
-        # so Dockerfiles receive the plain NEXT_PUBLIC_* names they expect.
+        # --push uses buildkit HTTPS internally, which fails for HTTP registries.
+        # --load + docker push goes through the Podman daemon (insecure=true). (#7, #12)
         env:
           STOREFRONT_CLERK_KEY: ${{ secrets.STAGING_STOREFRONT_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY }}
           ADMIN_CLERK_KEY: ${{ secrets.STAGING_ADMIN_NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY }}
@@ -130,10 +171,9 @@ jobs:
           IMAGE="${{ secrets.STAGING_REGISTRY }}/${{ matrix.app }}"
 
           if [ "${{ matrix.app }}" = "admin" ]; then
-            CLERK_KEY="$ADMIN_CLERK_KEY"
             docker build \
               -f apps/admin/Dockerfile \
-              --build-arg NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="$CLERK_KEY" \
+              --build-arg NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="$ADMIN_CLERK_KEY" \
               --build-arg NEXT_PUBLIC_CONVEX_URL="$NEXT_PUBLIC_CONVEX_URL" \
               --build-arg NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME="$NEXT_PUBLIC_CLOUDINARY_CLOUD_NAME" \
               --build-arg NEXT_PUBLIC_CLOUDINARY_API_KEY="$NEXT_PUBLIC_CLOUDINARY_API_KEY" \
@@ -142,10 +182,9 @@ jobs:
               -t "${IMAGE}:staging" \
               ./out
           else
-            CLERK_KEY="$STOREFRONT_CLERK_KEY"
             docker build \
               -f apps/storefront/Dockerfile \
-              --build-arg NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="$CLERK_KEY" \
+              --build-arg NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="$STOREFRONT_CLERK_KEY" \
               --build-arg NEXT_PUBLIC_CONVEX_URL="$NEXT_PUBLIC_CONVEX_URL" \
               --build-arg NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="$NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY" \
               --load \
@@ -158,10 +197,12 @@ jobs:
           docker push "${IMAGE}:sha-${SHORT_SHA}"
 
   # ── 3. Deploy ───────────────────────────────────────────────────────────────
+  # Only pulls and restarts the containers whose images were just rebuilt.
 
   deploy:
     name: Deploy to staging VPS
-    needs: build
+    needs: [build, changes]
+    if: needs.changes.outputs.matrix != '[]'
     runs-on: ubuntu-latest
 
     steps:
@@ -184,48 +225,41 @@ jobs:
           CLERK_SECRET_KEY: ${{ secrets.STAGING_STOREFRONT_CLERK_SECRET_KEY }}
           ADMIN_CLERK_SECRET_KEY: ${{ secrets.STAGING_ADMIN_CLERK_SECRET_KEY }}
           CLOUDINARY_API_SECRET: ${{ secrets.STAGING_CLOUDINARY_API_SECRET }}
+          STOREFRONT_CHANGED: ${{ needs.changes.outputs.storefront }}
+          ADMIN_CHANGED: ${{ needs.changes.outputs.admin }}
         run: |
           REGISTRY_HOST=$(echo "$REGISTRY" | cut -d'/' -f1)
-
-          # Substitute the actual registry value and base64-encode the compose file.
-          # Passing it as a base64 string through the SSH heredoc avoids the need for
-          # an inner heredoc, which breaks YAML parsing when compose content has lines
-          # at column 0 (YAML sees them as new top-level nodes, invalidating the file).
           COMPOSE_B64=$(sed "s|\${REGISTRY}|${REGISTRY}|g" deploy/staging/compose.yml | base64 -w 0)
 
-          # StrictHostKeyChecking=accept-new trusts on first connect but rejects
-          # changed keys on subsequent runs — safer than no-verify
           ssh -i ~/.ssh/staging \
               -p "${SSH_PORT:-22}" \
               -o StrictHostKeyChecking=accept-new \
               "${SSH_USER}@${SSH_HOST}" bash -s << EOF
           set -euo pipefail
 
-          # Registry uses HTTP — --tls-verify=false required for podman login & pull
-          # (see: troubleshooting #12)
           echo "${REGISTRY_TOKEN}" \
             | podman login "${REGISTRY_HOST}" \
                 -u "${REGISTRY_USER}" --password-stdin --tls-verify=false
 
-          podman pull --tls-verify=false "${REGISTRY}/storefront:staging"
-          podman pull --tls-verify=false "${REGISTRY}/admin:staging"
+          # Pull only the images that were just rebuilt
+          [ "${STOREFRONT_CHANGED}" = "true" ] && podman pull --tls-verify=false "${REGISTRY}/storefront:staging"
+          [ "${ADMIN_CHANGED}"      = "true" ] && podman pull --tls-verify=false "${REGISTRY}/admin:staging"
 
           mkdir -p /opt/staging
-
-          # Decode the compose file that was base64-encoded on the runner.
           echo "${COMPOSE_B64}" | base64 -d > /opt/staging/compose.yml
 
-          # Write runtime secrets to .env — variables expand on the runner before
-          # being sent over SSH, so secrets never appear in VPS shell history.
-          # printf keeps every line indented (no column-0 content) so YAML stays valid.
           printf 'CLERK_SECRET_KEY=%s\nADMIN_CLERK_SECRET_KEY=%s\nCLOUDINARY_API_SECRET=%s\n' \
             "${CLERK_SECRET_KEY}" "${ADMIN_CLERK_SECRET_KEY}" "${CLOUDINARY_API_SECRET}" \
             > /opt/staging/.env
           chmod 600 /opt/staging/.env
 
-          cd /opt/staging
-          podman compose up -d --force-recreate --remove-orphans
+          # Restart only the containers whose images changed
+          SERVICES=""
+          [ "${STOREFRONT_CHANGED}" = "true" ] && SERVICES="\${SERVICES} storefront"
+          [ "${ADMIN_CHANGED}"      = "true" ] && SERVICES="\${SERVICES} admin"
+
+          cd /opt/staging
+          podman compose up -d --force-recreate --remove-orphans \${SERVICES}
 
-          # Remove dangling images from previous deploys
           podman image prune -f
           EOF