name: 'Docs Preview (Deploy)'

on:
  workflow_call:
    inputs:
      preview-context:
        description: 'Preview Metadata (JSON)'
        required: true
        type: string
    secrets:
      NETLIFY_AUTH_TOKEN:
        required: true
      NETLIFY_SITE_ID:
        required: true

env:
  BUILD_DIR:  ${{ fromJSON( inputs.preview-context ).build_dir }}
  # PR head SHA (latest commit):
  PR_HEADSHA: ${{ fromJSON( inputs.preview-context ).pull_request.head_sha }}
  PR_NUMBER:  ${{ fromJSON( inputs.preview-context ).pull_request.number }}
  # Deploy URL preview prefix (the site name for the prefix is managed at Netlify):
  PREVIEW_SITE_PREFIX: ${{ fromJSON( inputs.preview-context ).netlify.deploy_prefix }}

permissions:
  # Required by `marocchino/sticky-pull-request-comment`:
  pull-requests: write

jobs:
  deploy-preview:
    name: 'Deploy Preview'
    runs-on: ubuntu-24.04
    steps:
      - name: 'Retrieve and extract the built docs preview'
        uses: actions/download-artifact@v4
        with:
          name: preview-build
          path: ${{ env.BUILD_DIR }}

      # ==================== #
      # Deploy preview build #
      # ==================== #

      - name: 'Send preview build to Netlify'
        uses: nwtgck/actions-netlify@v3.0
        id: preview-netlify
        timeout-minutes: 1
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID:    ${{ secrets.NETLIFY_SITE_ID    }}
        with:
          # Fail the job when the required Netlify credentials are missing from ENV:
          fails-without-credentials: true
          # Set/create the Netlify deploy URL prefix:
          alias: ${{ env.PREVIEW_SITE_PREFIX }}
          # Only publish the contents of the build output:
          publish-dir: ${{ env.BUILD_DIR }}
          # Custom message for the deploy log on Netlify:
          deploy-message: 'Preview Build (PR #${{ env.PR_NUMBER }} @ commit: ${{ env.PR_HEADSHA }}'

          # Disable unwanted action defaults:
          # This input does not fallback to the GITHUB_TOKEN taken from context, nor log that it will skip extra features of the action when this input is not set:
          # https://github.com/nwtgck/actions-netlify/issues/1219
          # github-token: ${{ secrets.GITHUB_TOKEN }}
          # NOTE: These features won't work correctly when the triggered workflow is not run from the PR branch due to assumed `pull_request` context:
          # https://github.com/nwtgck/actions-netlify/issues/545
          # Disable adding a comment to the commit belonging to context `github.sha` about the successful deployment (redundant and often wrong commit):
          enable-commit-comment: false
          # Disable adding a "Netlify - Netlify deployment" PR check status (workflow job status is sufficient):
          enable-commit-status: false
          # Disable adding a comment about successful deployment status to the PR.
          # Prefer `marocchino/sticky-pull-request-comment` instead (more flexible and allows custom message):
          enable-pull-request-comment: false
          # Opt-out of deployment feature:
          # NOTE:
          # - When affected by `nwtgck/actions-netlify/issues/545`, the deployments published reference the wrong commit and thus information.
          # - While the feature creates or assigns a deployment to associate the build with, it is unrelated to the related environments feature (secrets/vars):
          #   https://github.com/nwtgck/actions-netlify/issues/538#issuecomment-833983970
          #   https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/viewing-deployment-history
          #   https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment
          enable-github-deployment: false
          # Assign to non-default Deployment Environment for better management:
          # github-deployment-environment: documentation-previews
          # github-deployment-description: 'Preview deploy for documentation PRs'

          # If a `netlify.toml` config is ever needed, enable this:
          # netlify-config-path: ./docs/netlify.toml
          # If ever switching from Github Pages, enable this only when not deploying a preview build (false by default):
          # production-deploy: false

      - name: 'Comment on PR with preview link'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          number: ${{ env.PR_NUMBER }}
          header: preview-comment
          recreate: true
          message: |
            [Documentation preview for this PR](${{ steps.preview-netlify.outputs.deploy-url }}) is ready! :tada:

            Built with commit: ${{ env.PR_HEADSHA }}