ci: skip production deploys for documentation-only changes

.github/workflows/deploy-keycloak-staging.yml

@@ -15,6 +15,20 @@ on:
   push:
     branches:
       - main
+    # Documentation changes must not redeploy production. Merging a README edit
+    # rebuilt the image and restarted Keycloak on 2026-09-08 -- harmless, but it
+    # is a needless restart of the auth server every product depends on, and it
+    # buries real deploys among cosmetic ones in the run history.
+    #
+    # Only paths that cannot affect the built image or the deployment are listed.
+    # Anything under src/, deploy/, .github/workflows/, package.json or the
+    # Dockerfile still deploys.
+    paths-ignore:
+      - '**.md'
+      - 'LICENSE'
+      - '.gitignore'
+      - 'docs/**'
+      - '.vscode/**'
   workflow_dispatch:
     inputs:
       ref:
@@ -152,15 +166,16 @@ jobs:
     # keycloak-production, not keycloak-staging: auth.civicdatalab.in serves
     # production auth for every CivicDataLab product.
     #
-    # GitHub cannot move secrets between environments, so this could only change
-    # once EC2_HOST, EC2_USERNAME and EC2_PRIVATE_KEY had been added to the new
-    # environment. They have been. keycloak-staging is deliberately left in place
-    # until a deploy has succeeded from here -- a missing secret surfaces as an
-    # opaque ssh auth failure, not as "secret not found", so the ability to flip
-    # back in one line is worth keeping for a release or two.
+    # DO NOT point this back at keycloak-staging. That environment still exists
+    # but its secrets are now placeholders -- it is being kept to be repurposed
+    # for a real staging server later. Switching to it would not fail loudly;
+    # appleboy/ssh-action reports a bad key as an opaque handshake error, not as
+    # "wrong credentials", so it would look like a broken box rather than a
+    # misrouted environment.
     #
-    # This environment is also where a required reviewer would be configured if
-    # production deploys should need approval.
+    # GitHub cannot move secrets between environments, so a future change here
+    # means adding EC2_HOST, EC2_USERNAME and EC2_PRIVATE_KEY to the target
+    # environment FIRST, then switching.
     environment: keycloak-production
     timeout-minutes: 15
     permissions: