deploy-docs.yml

name: deploy docs

# The site is versioned (docs/adr/0005-version-the-documentation-site.md) and
# every deployment rebuilds all of it -- the preview from website/docs/, each
# stable line from its committed snapshot under website/versioned_docs/ -- since
# a GitHub Pages deployment replaces the whole site.
#
# Called only, never dispatched: the label of /docs/preview/ has to name the
# version on nuget.org that describes the commit being built, and only the
# callers know it. preview.yml calls this on every run that decided what to
# publish, so the preview documentation always describes a package someone can
# install; dispatching preview.yml is how the site is redeployed by hand.
# release.yml calls it after a stable release, with the tag whose commit carries
# the new snapshot (the core's v<version>, or another train's <train>-v<version>)
# and the core's version, which labels the preview.
on:
  workflow_call:
    inputs:
      ref:
        description: >-
          What to build: the full SHA of the commit the caller's run was started on or of one of its
          ancestors, or the tag of a stable release that descends from that commit: the core's
          v<preview-version>, or another train's <train>-v<version>, with a stable preview-version.
        type: string
        required: true
      preview-version:
        description: 'Label of /docs/preview/: the version on nuget.org that describes that commit.'
        type: string
        required: true

permissions:
  contents: read

jobs:
  build:
    name: build
    runs-on: ubuntu-latest
    timeout-minutes: 30
    outputs:
      commit: ${{ steps.version.outputs.commit }}
    defaults:
      run:
        working-directory: website
    steps:
      # The commit the run was started on, not the caller's ref: the next step
      # decides whether that one may be built. A ref input passed to the
      # checkout is what CodeQL reports as cache poisoning
      # (actions/cache-poisoning/poisonable-step), whatever checks it first.
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          # MinVer runs when DocFX builds the projects under src/, and reads
          # the tag history, which a shallow clone does not have. The whole
          # history and the tags also hold every commit the next step accepts.
          fetch-depth: 0
          # Nothing here pushes, and the site's npm packages run in this job.
          persist-credentials: false

      # This job runs the code it checks out -- DocFX, npm, Docusaurus -- in the
      # context of main, so whatever it writes to the Actions cache lands in
      # main's scope, which every branch and workflow restores from. So it
      # builds only the commits its callers mean, and checks that itself rather
      # than trusting the ref it is given: the commit the run was started on or
      # one of its ancestors (preview.yml: HEAD, or the commit a repair
      # completes), or a stable release's tag descending from it (release.yml:
      # the release commit semantic-release pushed to main), the core's
      # v<preview-version> or another train's <train>-v<version>. Anything else,
      # a pull request's head or another branch, stops here, before a line of
      # it has run.
      - name: Switch to the commit to build
        working-directory: ${{ github.workspace }}
        env:
          REF: ${{ inputs.ref }}
          VERSION: ${{ inputs.preview-version }}
        run: |
          set -euo pipefail
          if [[ "$REF" =~ ^[0-9a-f]{40}$ ]] &&
            commit="$(git rev-parse --verify --quiet "$REF^{commit}")" &&
            git merge-base --is-ancestor "$commit" "$GITHUB_SHA"; then
            echo "Building $commit, which is $GITHUB_SHA or one of its ancestors."
          elif [[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] &&
            [[ "$REF" == "v$VERSION" || "$REF" =~ ^[a-z][a-z0-9-]*-v[0-9]+\.[0-9]+\.[0-9]+$ ]] &&
            commit="$(git rev-parse --verify --quiet "refs/tags/$REF^{commit}")" &&
            git merge-base --is-ancestor "$GITHUB_SHA" "$commit"; then
            echo "Building $REF ($commit), which descends from $GITHUB_SHA."
          else
            echo "::error::'$REF' is not $GITHUB_SHA, one of its ancestors, or a stable release's tag descending from it: v$VERSION, or another train's <train>-v<version>, with a stable version to label the preview." >&2
            exit 1
          fi
          git checkout --quiet --detach "$commit"

      # The preview is labelled with the version of the package it describes,
      # which the caller knows: preview.yml the version on nuget.org built from
      # the nearest commit with the same package inputs, release.yml the version
      # it released.
      - name: Preview version
        id: version
        working-directory: ${{ github.workspace }}
        env:
          PREVIEW_VERSION: ${{ inputs.preview-version }}
        run: |
          set -euo pipefail
          version="$PREVIEW_VERSION"
          if [[ ! "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]]; then
            echo "::error::'$version' is not a package version." >&2
            exit 1
          fi
          echo "Preview documentation describes $version."
          echo "preview=$version" >> "$GITHUB_OUTPUT"
          echo "commit=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"

      # The steps ci.yml also runs on a pull request reaching the site, with the label.
      - name: Build the site
        uses: ./.github/actions/build-site
        with:
          preview-version: ${{ steps.version.outputs.preview }}

      # Read back by the next deployment's freshness check.
      - name: Record the deployed commit
        run: >-
          printf '{"commit":"%s","preview":"%s"}\n'
          "${{ steps.version.outputs.commit }}" "${{ steps.version.outputs.preview }}"
          > build/deployment.json

      - uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
        with:
          path: website/build

  deploy:
    name: deploy
    needs: build
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
      pages: write
      id-token: write
    # Only publishing is serialised; builds run in parallel. `queue: max` keeps
    # every waiting deployment instead of the default, which cancels whichever
    # one was pending when another arrives -- regardless of commit -- so a newer
    # preview, or a release's deployment, could otherwise be dropped in favour
    # of an older commit that happened to be queued later. Deployments run in
    # arrival order, and the freshness check below stops an older one from
    # replacing a newer site.
    concurrency:
      group: pages
      cancel-in-progress: false
      queue: max
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
        id: pages

      # A release's deployment and a preview run's can finish out of order, so
      # the older one's arrives last. It would then replace a newer site with an
      # older one until the next run. So compare against what is live and stand
      # down when that is already a descendant of this commit. The same check
      # covers a stable release whose deployment runs after a newer preview: that
      # preview's tree already contains the release's snapshot. The live commit
      # itself is redeployed, which is what a preview.yml dispatched to repair the
      # site wants.
      - name: Skip if the site already shows a newer commit
        id: freshness
        env:
          GH_TOKEN: ${{ github.token }}
          SITE: ${{ steps.pages.outputs.base_url }}
          COMMIT: ${{ needs.build.outputs.commit }}
        run: |
          set -euo pipefail
          deployed="$(curl --fail --silent --location "$SITE/deployment.json" | jq -r '.commit // empty' || true)"
          status=""
          if [[ -n "$deployed" && "$deployed" != "$COMMIT" ]]; then
            status="$(gh api "repos/$GITHUB_REPOSITORY/compare/$COMMIT...$deployed" --jq .status || true)"
          fi
          if [[ "$status" == "ahead" ]]; then
            echo "The site already shows $deployed, a descendant of $COMMIT: nothing to deploy."
            echo "skip=true" >> "$GITHUB_OUTPUT"
          else
            echo "Deploying $COMMIT (live: ${deployed:-none}, comparison: ${status:-n/a})."
            echo "skip=false" >> "$GITHUB_OUTPUT"
          fi

      - uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1
        if: steps.freshness.outputs.skip != 'true'
        id: deployment