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

[rusackas]

SUMMARY

Master gets frequent, sometimes bursty pushes (dependency bumps, doc PRs, etc.), and each one that triggers Python-Integration also fires a Docs Deployment attempt. The docs-deploy-asf-site concurrency group correctly serializes the actual builds — this was added in #40030 because the deploy action pushes to apache/superset-site without rebasing, so concurrent runs race on the final push. But cancel-in-progress: true force-kills every superseded attempt with a cancelled conclusion, and GitHub's commit list renders that as a red/failing check on that commit — even though nothing is actually broken and a later run does go on to deploy successfully.

Under bursty conditions this can chain for an extended stretch: I observed one master commit rack up 12 cancelled Docs Deployment attempts in a row over about 80 minutes before one finally got through, painting a run of otherwise-green commits red the whole time.

This PR splits the workflow so the "am I still relevant?" check happens before anything enters the serialized group:

• New check-freshness job runs for every trigger, outside the concurrency group, and just compares its own commit against master's live tip via gh api.
• build-deploy now also requires needs.check-freshness.outputs.is-current == 'true'. Superseded runs skip cleanly here (a skipped conclusion, which doesn't redden the commit) instead of ever entering the concurrency group.
• The docs-deploy-asf-site concurrency group (with cancel-in-progress: true) moves onto build-deploy itself and stays as a backstop for the genuine push-race case, but should now rarely have more than one real contender to cancel.

No change to deploy behavior or destination — docs still deploy from whichever run is building master's current tip.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

N/A (CI workflow change, no UI)

TESTING INSTRUCTIONS

• pre-commit run --files .github/workflows/superset-docs-deploy.yml passes (including the zizmor GHA security audit).
• YAML validated with python3 -c "import yaml; yaml.safe_load(...)".
• Can't fully dry-run workflow_run/concurrency semantics locally; recommend watching the next few Docs Deployment runs on master after merge to confirm superseded attempts now show skipped instead of cancelled, and that a deploy still lands on apache/superset-site (asf-site branch).

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags:
• Changes UI
• Includes DB Migration (follow approval process in SIP-59)
  • Migration is atomic, supports rollback & is backwards-compatible
  • Confirm DB migration upgrade and downgrade tested
  • Runtime estimates and downtime expectations provided
• Introduces new feature or API
• Removes existing feature or API

[bito-code-review]

Bito Automatic Review Skipped - Files Excluded

Bito didn't auto-review this change because all changed files are in the exclusion list for automatic reviews. No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change the excluded files settings here, or contact your Bito workspace admin at evan@preset.io.

[sadpandajoe]

One question about manual dispatch semantics.

[bito-code-review]

The behavior change is intentional. The new check-freshness job explicitly compares the triggered commit (BUILD_SHA) against the current tip of master. Since workflow_dispatch uses the selected ref as github.sha, any manual run on a non-master branch or an older commit will fail the is-current == 'true' check and skip the build-deploy job. This is designed to ensure that only the most recent deployment for the master branch proceeds, preventing redundant or superseded deployments.

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

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

[netlify]

✅ Deploy Preview for superset-docs-preview ready!

Name	Link
🔨 Latest commit	570d29d
🔍 Latest deploy log	https://app.netlify.com/projects/superset-docs-preview/deploys/6a692cc17dbccf000869032a
😎 Deploy Preview	https://deploy-preview-42488--superset-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.