docs-refresh.yml

name: Refresh external docs

on:
  schedule:
    - cron: '17 * * * *'
  workflow_dispatch:
    inputs:
      dry_run:
        description: 'Compare fingerprints without posting to the Vercel deploy hook.'
        required: false
        default: true
        type: boolean
      force_deploy:
        description: 'Mark the run as changed even when the deployed fingerprint matches.'
        required: false
        default: false
        type: boolean

permissions:
  contents: read

concurrency:
  group: docs-refresh
  cancel-in-progress: false

jobs:
  check-docs:
    name: Check external docs fingerprint
    runs-on: ubuntu-latest

    steps:
      - name: Checkout docs repo
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm

      - name: Install dependencies
        run: npm ci

      - name: Generate current docs fingerprint
        run: npm run docs:fingerprint -- --output current-docs-fingerprint.json
        env:
          DOCS_SOURCE_TOKEN: ${{ secrets.DOCS_SOURCE_TOKEN }}
          GITHUB_TOKEN: ${{ github.token }}

      - name: Download deployed docs fingerprint
        env:
          DOCS_FINGERPRINT_URL: https://docs.hypercerts.org/docs-fingerprint.json
        run: |
          set +e
          http_code=$(curl -sS -L -w "%{http_code}" \
            -o deployed-docs-fingerprint.json \
            "$DOCS_FINGERPRINT_URL")
          curl_status=$?
          set -e

          if [ "$curl_status" -ne 0 ]; then
            echo "::error::Failed to download deployed docs fingerprint from $DOCS_FINGERPRINT_URL. Refusing to deploy on an unknown diff."
            exit 1
          fi

          case "$http_code" in
            200)
              ;;
            404)
              echo '{}' > deployed-docs-fingerprint.json
              ;;
            *)
              echo "::error::Unexpected HTTP $http_code while downloading $DOCS_FINGERPRINT_URL. Refusing to deploy on an unknown diff."
              exit 1
              ;;
          esac

      - name: Check if external docs changed
        id: diff
        env:
          FORCE_DEPLOY: ${{ github.event_name == 'workflow_dispatch' && inputs.force_deploy == true }}
        run: |
          node lib/compare-docs-fingerprint.js \
            current-docs-fingerprint.json \
            deployed-docs-fingerprint.json >> "$GITHUB_OUTPUT"

          if [ "$FORCE_DEPLOY" = "true" ]; then
            echo "changed=true" >> "$GITHUB_OUTPUT"
            echo "reason=forced by workflow_dispatch input" >> "$GITHUB_OUTPUT"
          fi

      - name: Trigger Vercel deployment
        if: steps.diff.outputs.changed == 'true'
        env:
          DRY_RUN: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}
          VERCEL_DEPLOY_HOOK_URL: ${{ secrets.VERCEL_DEPLOY_HOOK_URL }}
        run: |
          if [ "$DRY_RUN" = "true" ]; then
            echo "workflow_dispatch dry_run=true; skipping Vercel deploy hook."
            exit 0
          fi

          if [ -z "$VERCEL_DEPLOY_HOOK_URL" ]; then
            echo "::error::VERCEL_DEPLOY_HOOK_URL is required when external docs have changed. Create a Vercel Deploy Hook for the production branch and store its URL as a GitHub Actions secret."
            exit 1
          fi

          curl -fsS -X POST "$VERCEL_DEPLOY_HOOK_URL"

      - name: Write summary
        if: always()
        run: |
          {
            echo "### External docs refresh"
            echo ""
            echo "Changed: ${{ steps.diff.outputs.changed || 'unknown' }}"
            echo "Reason: ${{ steps.diff.outputs.reason || 'not computed' }}"
            echo "Dry run: ${{ github.event_name == 'workflow_dispatch' && inputs.dry_run == true }}"
            echo "Current: ${{ steps.diff.outputs.current_fingerprint || 'n/a' }}"
            echo "Deployed: ${{ steps.diff.outputs.deployed_fingerprint || 'n/a' }}"
          } >> "$GITHUB_STEP_SUMMARY"