remote-docs-preview.yml

name: Deploy remote documentation preview

on:
  workflow_dispatch:
    inputs:
      remote_name:
        description: Source name registered in remotes.json
        required: true
        default: clickhouse-private
        type: string
      source_repository:
        description: Repository containing the pull request
        required: true
        default: ClickHouse/airgap-docs
        type: string
      pull_request_number:
        description: Open pull request to preview
        required: true
        type: string
  workflow_call:
    inputs:
      remote_name:
        description: Source name registered in remotes.json
        required: true
        type: string
      pull_request_number:
        description: Open pull request in the calling repository
        required: true
        type: number
      source_repository:
        description: Repository containing the pull request
        required: true
        type: string
    secrets:
      WORKFLOW_AUTH_PUBLIC_APP_ID:
        required: true
      WORKFLOW_AUTH_PUBLIC_PRIVATE_KEY:
        required: true
      VERCEL_TOKEN:
        required: true
      VERCEL_ORG_ID:
        required: true
      VERCEL_PROJECT_ID:
        required: true
    outputs:
      preview_url:
        description: URL of the completed Vercel preview
        value: ${{ jobs.preview.outputs.preview_url }}

permissions:
  contents: read
  pull-requests: write

concurrency:
  group: remote-docs-preview-${{ inputs.source_repository }}-${{ inputs.pull_request_number }}
  cancel-in-progress: true

jobs:
  preview:
    name: Build on Vercel
    runs-on: ubuntu-latest
    timeout-minutes: 60
    outputs:
      preview_url: ${{ steps.deploy.outputs.preview_url }}
    steps:
      - name: Require a trusted manual invocation
        env:
          CALLING_REPOSITORY: ${{ github.repository }}
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
          SOURCE_REPOSITORY: ${{ inputs.source_repository }}
        run: |
          if [[ "$GITHUB_REF_NAME" != "$DEFAULT_BRANCH" ]]; then
            echo "Run this workflow from the calling repository's default branch." >&2
            exit 1
          fi
          if [[ "$CALLING_REPOSITORY" != "ClickHouse/mintlify-docs-dev" && "$SOURCE_REPOSITORY" != "$CALLING_REPOSITORY" ]]; then
            echo "A remote caller may request a preview only for its own repository." >&2
            exit 1
          fi

      - name: Check out the trusted documentation site
        uses: actions/checkout@v6
        with:
          repository: ClickHouse/mintlify-docs-dev
          ref: main
          path: site
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Validate the registered source
        working-directory: site
        env:
          DOCS_LOCALE: en
          DOCS_REMOTE_NAME: ${{ inputs.remote_name }}
          DOCS_REMOTE_REPOSITORY: ${{ inputs.source_repository }}
          DOCS_REMOTE_REF: 0000000000000000000000000000000000000000
          DOCS_PREVIEW_ALIAS: manual-validation
        run: node bin/validate-deploy-request.ts

      - name: Resolve the trusted documentation site revision
        id: site
        working-directory: site
        run: |
          site_sha="$(git rev-parse HEAD)"
          if [[ ! "$site_sha" =~ ^[0-9a-f]{40}$ ]]; then
            echo "Git returned an invalid documentation site SHA." >&2
            exit 1
          fi
          echo "sha=$site_sha" >> "$GITHUB_OUTPUT"

      - name: Mint a source-repository token
        id: source-token
        uses: actions/create-github-app-token@v3
        with:
          app-id: ${{ secrets.WORKFLOW_AUTH_PUBLIC_APP_ID }}
          private-key: ${{ secrets.WORKFLOW_AUTH_PUBLIC_PRIVATE_KEY }}
          owner: ClickHouse
          repositories: ${{ inputs.source_repository }}
          permission-contents: read
          permission-pull-requests: read

      - name: Resolve the pull request head
        id: pull-request
        env:
          GH_TOKEN: ${{ steps.source-token.outputs.token }}
          PULL_REQUEST_NUMBER: ${{ inputs.pull_request_number }}
          SOURCE_REPOSITORY: ${{ inputs.source_repository }}
        run: |
          state="$(gh api "repos/$SOURCE_REPOSITORY/pulls/$PULL_REQUEST_NUMBER" --jq .state)"
          if [[ "$state" != "open" ]]; then
            echo "Pull request $PULL_REQUEST_NUMBER is not open." >&2
            exit 1
          fi

          head_sha="$(gh api "repos/$SOURCE_REPOSITORY/pulls/$PULL_REQUEST_NUMBER" --jq .head.sha)"
          head_repository="$(gh api "repos/$SOURCE_REPOSITORY/pulls/$PULL_REQUEST_NUMBER" --jq .head.repo.full_name)"
          if [[ ! "$head_sha" =~ ^[0-9a-f]{40}$ ]]; then
            echo "GitHub returned an invalid pull request head SHA." >&2
            exit 1
          fi
          if [[ ! "$head_repository" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
            echo "GitHub returned an invalid pull request head repository." >&2
            exit 1
          fi
          echo "head_sha=$head_sha" >> "$GITHUB_OUTPUT"
          echo "head_repository=$head_repository" >> "$GITHUB_OUTPUT"

      # Vercel fetches the trusted Nimbus main revision through the project's
      # Git connection. The deployment exchanges its own OIDC identity for a
      # short-lived, repository-scoped token through Vercel Connect; the
      # Actions token never enters the build.
      - name: Trigger and wait for the source preview
        id: deploy
        env:
          DOCS_REMOTE_NAME: ${{ inputs.remote_name }}
          DOCS_REMOTE_REF: ${{ steps.pull-request.outputs.head_sha }}
          DOCS_REMOTE_REPOSITORY: ${{ inputs.source_repository }}
          DOCS_REMOTE_SOURCE_REPOSITORY: ${{ steps.pull-request.outputs.head_repository }}
          DOCS_REMOTE_PULL_REQUEST_REF: refs/pull/${{ inputs.pull_request_number }}/head
          PULL_REQUEST_NUMBER: ${{ inputs.pull_request_number }}
          SITE_SHA: ${{ steps.site.outputs.sha }}
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
        run: |
          deployment_id=""
          deployment_finished=false

          cancel_vercel_deployment() {
            local deployment_id_to_cancel="$1"
            local deployment_label="$2"
            local cancel_response
            local cancel_exit_code
            local deployment_response
            local ready_state

            if cancel_response="$(
              curl --silent --show-error --fail-with-body \
                --request PATCH \
                --header "Authorization: Bearer $VERCEL_TOKEN" \
                "https://api.vercel.com/v12/deployments/$deployment_id_to_cancel/cancel?teamId=$VERCEL_ORG_ID"
            )"; then
              echo "Canceled $deployment_label Vercel deployment $deployment_id_to_cancel."
              return 0
            else
              cancel_exit_code=$?
            fi

            if deployment_response="$(
              curl --silent --show-error --fail-with-body \
                --header "Authorization: Bearer $VERCEL_TOKEN" \
                "https://api.vercel.com/v13/deployments/$deployment_id_to_cancel?teamId=$VERCEL_ORG_ID"
            )"; then
              ready_state="$(jq -er .readyState <<< "$deployment_response")"
              case "$ready_state" in
                READY|ERROR|CANCELED|DELETED|BLOCKED)
                  echo "$deployment_label Vercel deployment $deployment_id_to_cancel already reached $ready_state."
                  return 0
                  ;;
              esac
            fi

            printf '%s\n' "$cancel_response" >&2
            echo "Unable to cancel $deployment_label Vercel deployment $deployment_id_to_cancel." >&2
            return "$cancel_exit_code"
          }

          cancel_superseded_deployments() {
            local ready_state
            local until=""
            local list_response
            local next
            local superseded_id
            local -a request_args
            local -a deployment_ids

            for ready_state in QUEUED INITIALIZING BUILDING; do
              until=""
              while true; do
                request_args=(
                  --silent
                  --show-error
                  --fail-with-body
                  --get
                  --header "Authorization: Bearer $VERCEL_TOKEN"
                  --data-urlencode "projectId=$VERCEL_PROJECT_ID"
                  --data-urlencode "state=$ready_state"
                  --data-urlencode "limit=100"
                  --data-urlencode "teamId=$VERCEL_ORG_ID"
                )
                if [[ -n "$until" ]]; then
                  request_args+=(--data-urlencode "until=$until")
                fi

                if ! list_response="$(
                  curl "${request_args[@]}" "https://api.vercel.com/v7/deployments"
                )"; then
                  printf '%s\n' "$list_response" >&2
                  echo "Unable to list source-preview Vercel deployments." >&2
                  return 1
                fi

                mapfile -t deployment_ids < <(
                  jq -r \
                    --arg pull_request "$PULL_REQUEST_NUMBER" \
                    --arg source_repository "$DOCS_REMOTE_REPOSITORY" \
                    '.deployments[]
                      | select((.meta.buildScope? // "") == "source-preview")
                      | select((.meta.sourceRepository? // "") == $source_repository)
                      | select((.meta.pullRequest? // "") == $pull_request)
                      | (.uid // .id)' \
                    <<< "$list_response"
                )
                for superseded_id in "${deployment_ids[@]}"; do
                  cancel_vercel_deployment "$superseded_id" "superseded source-preview" || return 1
                done

                next="$(jq -er '.pagination.next // ""' <<< "$list_response")"
                if [[ -z "$next" ]]; then
                  break
                fi
                if [[ "$next" == "$until" ]]; then
                  echo "Vercel returned a repeated pagination cursor while listing source-preview deployments." >&2
                  return 1
                fi
                until="$next"
              done
            done
          }

          finalize_deployment() {
            local exit_code=$?
            trap - EXIT INT TERM
            if [[ "$deployment_finished" != true && -n "$deployment_id" ]]; then
              if ! cancel_vercel_deployment "$deployment_id" "source-preview"; then
                echo "::warning::Unable to cancel the interrupted source-preview deployment."
                if [[ "$exit_code" -eq 0 ]]; then
                  exit_code=1
                fi
              fi
            fi
            exit "$exit_code"
          }

          cancel_superseded_deployments

          trap finalize_deployment EXIT
          trap 'exit 130' INT
          trap 'exit 143' TERM

          if ! project_response="$(
            curl --silent --show-error --fail-with-body \
              --header "Authorization: Bearer $VERCEL_TOKEN" \
              "https://api.vercel.com/v9/projects/$VERCEL_PROJECT_ID?teamId=$VERCEL_ORG_ID"
          )"; then
            printf '%s\n' "$project_response" >&2
            exit 1
          fi
          project_name="$(jq -er .name <<< "$project_response")"

          payload="$(
            jq --null-input \
              --arg approved_sha "$DOCS_REMOTE_REF" \
              --arg project_id "$VERCEL_PROJECT_ID" \
              --arg project_name "$project_name" \
              --arg pull_request "$PULL_REQUEST_NUMBER" \
              --arg remote_name "$DOCS_REMOTE_NAME" \
              --arg remote_repository "$DOCS_REMOTE_REPOSITORY" \
              --arg source_repository "$DOCS_REMOTE_SOURCE_REPOSITORY" \
              --arg pull_request_ref "$DOCS_REMOTE_PULL_REQUEST_REF" \
              --arg site_sha "$SITE_SHA" \
              '{
                name: $project_name,
                project: $project_id,
                customEnvironmentSlugOrId: "connect-preview",
                gitSource: {
                  type: "github",
                  org: "ClickHouse",
                  repo: "mintlify-docs-dev",
                  ref: "main",
                  sha: $site_sha
                },
                build: {env: {
                  DOCS_DEPLOY_TARGET: "english",
                  DOCS_LOCALES: "none",
                  DOCS_AVAILABLE_LOCALES: "all",
                  DOCS_REMOTES: "all",
                  DOCS_REMOTE_NAME: $remote_name,
                  DOCS_REMOTE_REPOSITORY: $remote_repository,
                  DOCS_REMOTE_SOURCE_REPOSITORY: $source_repository,
                  DOCS_REMOTE_PULL_REQUEST_REF: $pull_request_ref,
                  DOCS_REMOTE_REF: $approved_sha
                }},
                meta: {
                  buildScope: "source-preview",
                  sourceRepository: $remote_repository,
                  sourceHeadRepository: $source_repository,
                  pullRequest: $pull_request,
                  approvedSha: $approved_sha,
                  siteSha: $site_sha
                }
              }'
          )"

          if ! deployment_response="$(
            curl --silent --show-error --fail-with-body \
              --request POST \
              --header "Authorization: Bearer $VERCEL_TOKEN" \
              --header "Content-Type: application/json" \
              --data "$payload" \
              "https://api.vercel.com/v13/deployments?forceNew=1&teamId=$VERCEL_ORG_ID"
          )"; then
            printf '%s\n' "$deployment_response" >&2
            exit 1
          fi

          deployment_id="$(jq -er .id <<< "$deployment_response")"
          deployment_url="$(jq -er .url <<< "$deployment_response")"
          preview_url="https://${deployment_url#https://}"
          echo "preview_url=$preview_url" >> "$GITHUB_OUTPUT"
          echo "Vercel deployment: $preview_url"

          for _ in {1..360}; do
            if ! deployment_response="$(
              curl --silent --show-error --fail-with-body \
                --header "Authorization: Bearer $VERCEL_TOKEN" \
                "https://api.vercel.com/v13/deployments/$deployment_id?teamId=$VERCEL_ORG_ID"
            )"; then
              printf '%s\n' "$deployment_response" >&2
              exit 1
            fi

            ready_state="$(jq -er .readyState <<< "$deployment_response")"
            case "$ready_state" in
              READY)
                break
                ;;
              ERROR|CANCELED|DELETED|BLOCKED)
                jq -r '(.errorCode // "deployment_failed") + ": " + (.errorMessage // "Vercel deployment did not complete")' \
                  <<< "$deployment_response" >&2
                exit 1
                ;;
              QUEUED|INITIALIZING|BUILDING)
                sleep 10
                ;;
              *)
                echo "Unexpected Vercel deployment state: $ready_state" >&2
                exit 1
                ;;
            esac
          done

          if [[ "$ready_state" != "READY" ]]; then
            echo "Timed out waiting for Vercel deployment $deployment_id." >&2
            exit 1
          fi
          if [[ ! "$preview_url" =~ ^https://[^[:space:]]+$ ]]; then
            echo "Vercel returned an invalid preview URL." >&2
            exit 1
          fi
          deployment_finished=true

      - name: Add the preview link to the pull request
        if: github.repository == inputs.source_repository
        env:
          GH_TOKEN: ${{ github.token }}
          GH_REPO: ${{ github.repository }}
          PREVIEW_URL: ${{ steps.deploy.outputs.preview_url }}
          PULL_REQUEST_NUMBER: ${{ inputs.pull_request_number }}
        run: |
          gh pr comment "$PULL_REQUEST_NUMBER" --body "Documentation preview: $PREVIEW_URL"

      - name: Show the directly requested preview
        if: github.repository != inputs.source_repository
        env:
          PREVIEW_URL: ${{ steps.deploy.outputs.preview_url }}
          PULL_REQUEST_NUMBER: ${{ inputs.pull_request_number }}
          SOURCE_REPOSITORY: ${{ inputs.source_repository }}
        run: |
          echo "### Documentation preview" >> "$GITHUB_STEP_SUMMARY"
          echo "" >> "$GITHUB_STEP_SUMMARY"
          echo "[$SOURCE_REPOSITORY PR #$PULL_REQUEST_NUMBER]($PREVIEW_URL)" >> "$GITHUB_STEP_SUMMARY"