fix(ci): stop superseded Docs Deployment runs from showing as cancelled

Bursty pushes to master can trigger several overlapping Docs Deployment
attempts. The docs-deploy-asf-site concurrency group correctly serializes
the actual builds (needed to avoid racing on the final push to
superset-site), but every superseded attempt gets force-killed with a
`cancelled` conclusion, which reads as a red/failing check on that commit
even though nothing is actually broken.

Add a check-freshness job that runs outside the concurrency group and
compares its own commit against master's live tip. Superseded runs now
skip cleanly instead of entering (and being cancelled out of) the
serialized build-deploy job, so only genuine push races still rely on
cancel-in-progress as a backstop.

.github/workflows/superset-docs-deploy.yml

@@ -18,16 +18,6 @@ on:
 
   workflow_dispatch: {}
 
-# Serialize deploys: the action pushes to apache/superset-site without
-# rebasing, so concurrent runs race on the final push and the loser fails
-# with `! [rejected] asf-site -> asf-site (fetch first)`. Cancel any
-# in-progress run as soon as a newer one starts — the destination repo
-# isn't touched until the final push step, so canceling mid-build is safe,
-# and the freshest content always wins.
-concurrency:
-  group: docs-deploy-asf-site
-  cancel-in-progress: true
-
 permissions:
   contents: read
 
@@ -47,17 +37,59 @@ jobs:
 
         env:
           SUPERSET_SITE_BUILD: ${{ (secrets.SUPERSET_SITE_BUILD != '' && secrets.SUPERSET_SITE_BUILD != '') || '' }}
+
+  # Master gets frequent, sometimes bursty pushes, and each one can trigger a
+  # deploy attempt. Rather than let every superseded attempt get force-killed
+  # by the build-deploy concurrency group below (which shows up as a
+  # `cancelled` — i.e. red/failing-looking — check on that commit), have each
+  # run check up front whether it's still building master's current tip and,
+  # if not, skip cleanly. Deliberately outside the docs-deploy-asf-site
+  # concurrency group so it runs immediately for every trigger without
+  # blocking or being blocked by anything.
+  check-freshness:
+    runs-on: ubuntu-26.04
+    outputs:
+      is-current: ${{ steps.check.outputs.is-current }}
+    steps:
+      - name: "Check whether this is still master's current commit"
+        id: check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BUILD_SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
+        run: |
+          latest_sha="$(gh api "repos/${{ github.repository }}/commits/master" --jq .sha)"
+          if [ "${latest_sha}" = "${BUILD_SHA}" ]; then
+            echo "is-current=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is-current=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::master has moved on to ${latest_sha} since ${BUILD_SHA} was triggered — a newer run will deploy it, so skipping this one."
+          fi
+
   build-deploy:
-    needs: config
+    needs: [config, check-freshness]
+    # Only the run for master's current tip proceeds; anything superseded
+    # already skipped at check-freshness above instead of landing here.
     # For workflow_run triggers, only deploy when the triggering run originated
     # from this repository (not a fork), ensuring the checked-out code and any
     # local actions executed with deploy credentials are trusted.
     if: >-
       needs.config.outputs.has-secrets &&
+      needs.check-freshness.outputs.is-current == 'true' &&
       (github.event_name != 'workflow_run' ||
        github.event.workflow_run.head_repository.full_name == github.repository)
     name: Build & Deploy
     runs-on: ubuntu-26.04
+    # Serialize deploys: the action pushes to apache/superset-site without
+    # rebasing, so concurrent runs race on the final push and the loser fails
+    # with `! [rejected] asf-site -> asf-site (fetch first)`. Cancel any
+    # in-progress run as soon as a newer one starts — the destination repo
+    # isn't touched until the final push step, so canceling mid-build is safe,
+    # and the freshest content always wins. The check-freshness gate above
+    # means it should be rare for more than one run to reach this point, but
+    # this stays as a backstop against the actual push race.
+    concurrency:
+      group: docs-deploy-asf-site
+      cancel-in-progress: true
     steps:
       - name: "Checkout ${{ github.event.workflow_run.head_sha || github.sha }}"
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1