deploy-website.yml

name: Deploy Website

permissions: {}

on:
  pull_request:
    types: [opened, synchronize]
  merge_group:
  push:
    branches:
      - main
    # These inputs can affect the rendered site, so a change here is worth *checking*.
    # Whether we actually deploy is decided by the content fingerprint below, not by the path.
    paths:
      - 'docs/**'
      - 'packages/rolldown/src/**'
      - 'packages/rolldown/package.json'
      - 'packages/rolldown/tsconfig*.json'
  workflow_dispatch:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: ${{ github.ref_name != 'main' }}

jobs:
  # Builds/validates the docs and, on main, decides whether the content needs deploying. Runs
  # untrusted PR code, so it has NO `environment` and NO `id-token` permission — it cannot mint
  # an OIDC token. The deploy is a separate main-only job below — we never deploy to Void from
  # a PR.
  docs-validation:
    name: Docs Validation
    runs-on: ubuntu-latest
    outputs:
      # Deploy when this content's fingerprint hasn't been deployed before, or on manual dispatch.
      deploy: ${{ steps.deployed.outputs.cache-hit != 'true' || github.event_name == 'workflow_dispatch' }}
      fingerprint: ${{ steps.fingerprint.outputs.hash }}
    steps:
      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2

      - uses: voidzero-dev/setup-vp@3754dd7dbdb32bd8f6d28b6043de13ad3a75f21f # v1.21.1
        with:
          version: '1.0.0'
          cache: true

      - name: Generate API reference
        run: vp run --filter rolldown-docs generate

      - name: Build Docs
        if: github.ref_name != 'main'
        run: vp run --filter rolldown-docs build

      # Deterministic fingerprint of the deployable content: git-tracked docs sources plus the
      # generated TypeDoc reference (docs/reference). It is used as a GitHub Actions cache key to
      # identify an already-deployed state — so a packages/rolldown/src change that doesn't alter
      # the public API (and therefore the reference) keeps the same fingerprint and is not
      # redeployed. The built site is never hashed (it isn't reproducible); TypeDoc output is.
      - name: Fingerprint docs content
        id: fingerprint
        if: github.ref_name == 'main'
        run: |
          set -euo pipefail
          hash="$(
            {
              git ls-files -z -- docs
              find docs/reference -type f -print0
            } | LC_ALL=C sort -zu | xargs -0 sha256sum | sha256sum
          )"
          echo "hash=${hash%% *}" >> "$GITHUB_OUTPUT"

      - name: Was this content already deployed?
        id: deployed
        if: github.ref_name == 'main'
        uses: actions/cache/restore@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: .docs-deploy-marker
          key: docs-deploy-${{ steps.fingerprint.outputs.hash }}
          lookup-only: true

  deploy-void:
    name: Deploy to Void
    needs: [docs-validation]
    if: github.ref_name == 'main' && needs.docs-validation.outputs.deploy == 'true'
    runs-on: ubuntu-latest
    environment: void
    # `void deploy` authenticates via GitHub OIDC: with id-token:write (and no VOID_TOKEN set)
    # it mints an OIDC token (audience `void`) and exchanges it for a short-lived,
    # project-scoped deploy token. No long-lived secret is stored in the repo.
    permissions:
      id-token: write
    env:
      VOID_API_URL: https://api.void.cloud
    steps:
      - uses: taiki-e/checkout-action@7d1e50e93dc4fb3bba58f85018fadf77898aee8b # v1.4.2

      - uses: voidzero-dev/setup-vp@3754dd7dbdb32bd8f6d28b6043de13ad3a75f21f # v1.21.1
        with:
          version: '1.0.0'
          cache: true

      - name: Connect to Void
        run: vp exec --filter rolldown-docs void connect "$VOID_API_URL" --no-login

      - name: Deploy to Void
        run: vp run docs:void
        env:
          VOID_PROJECT: rolldown
          ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }}
          ALGOLIA_API_KEY: ${{ secrets.ALGOLIA_API_KEY }}

      # Mark this fingerprint as deployed so the next identical-content run skips. The marker
      # file's contents are unused (the cache key is the fingerprint); an evicted marker only
      # causes a harmless redundant redeploy.
      - name: Mark fingerprint deployed
        run: touch .docs-deploy-marker

      - name: Save deploy marker
        uses: actions/cache/save@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
        with:
          path: .docs-deploy-marker
          key: docs-deploy-${{ needs.docs-validation.outputs.fingerprint }}