name: 'Documentation (run)'

on:
  workflow_run:
    workflows: ['Documentation (PR)']
    types:
      - completed

# Note: If limiting concurrency is required for this workflow:
# 1. Add an additional job prior to `preview` to get the PR number make it an output.
# 2. Assign that new job as a `needs` dependency for the `preview` job.
# It is still required for `preview` job to download the artifact so that it can access the preview build files.

# This workflow runs off the primary branch and has access to secrets as expected.
jobs:
  preview:
    name: 'Deploy Preview'
    runs-on: ubuntu-22.04
    if: ${{ github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success' }}
    steps:

      # ======================== #
      # Restore workflow context #
      # ======================== #

      # Retrieve the artifact uploaded from `docs-preview-prepare.yml` workflow run that triggered this deployment
      - name: 'Download build artifact'
        uses: actions/download-artifact@v4
        with:
          name: preview-build
          github-token: ${{ secrets.GITHUB_TOKEN }}
          run-id: ${{ github.event.workflow_run.id }}

      - name: 'Extract build artifact'
        run: tar -xf artifact.tar.zst

      - name: 'Restore preserved ENV'
        run: cat pr.env >> "${GITHUB_ENV}"

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

      # Manage workflow deployment status. `enable-commit-status` from `nwtgck/actions-netlify` would handle this,
      # but presently does not work correctly via split workflow. It is useful in a split workflow as the 1st stage
      # no longer indicates if the entire workflow/deployment was successful.
      - name: 'Commit Status: Set Workflow Status as Pending'
        uses: myrotvorets/set-commit-status-action@v2.0.1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          status: pending
          # Should match `env.PR_HEADSHA` when triggered by `pull_request` event workflow,
          # Avoids failure of ENV being unavailable if job fails early:
          sha: ${{ github.event.workflow_run.head_sha }}
          context: 'Deploy Preview (pull_request => workflow_run)'

      - name: 'Send preview build to Netlify'
        uses: nwtgck/actions-netlify@v3.0
        id: preview
        timeout-minutes: 1
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          # Fail the job early if credentials are missing / invalid:
          fails-without-credentials: true
          # Sets/creates the Netlify deploy URL prefix.
          # Uses the PR number for uniqueness:
          alias: ${{ env.NETLIFY_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: '${{ env.PR_TITLE }} (PR #${{ env.PR_NUMBER }} @ commit: ${{ env.PR_HEADSHA }})'

          # Note: Split workflow incorrectly references latest primary branch commit for deployment.
          # Assign to non-default Deployment Environment for better management:
          github-deployment-environment: documentation-previews
          github-deployment-description: 'Preview deploy for documentation PRs'

          # Note - PR context used by this action is incorrect. These features are broken with split workflow:
          # https://github.com/nwtgck/actions-netlify/issues/545
          # Disable unwanted action defaults:
          # Disable adding deploy comment on pre-merge commit (Github creates this for PR diff):
          enable-commit-comment: false
          # Disable adding a "Netlify - Netlify deployment" check status:
          enable-commit-status: false
          # Disable. We provide a custom PR comment in the next action:
          enable-pull-request-comment: false

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

      - name: 'Comment on PR: Add/Update deployment status'
        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.outputs.deploy-url }}) is ready! :tada:

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

      - name: 'Commit Status: Update deployment status'
        uses: myrotvorets/set-commit-status-action@v2.0.1
        # Always run this step regardless of job failing early:
        if: ${{ always() }}
        env:
          DEPLOY_SUCCESS: Successfully deployed preview.
          DEPLOY_FAILURE: Failed to deploy preview.
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          status: ${{ job.status == 'success' && 'success' || 'failure' }}
          sha: ${{ github.event.workflow_run.head_sha }}
          context: 'Deploy Preview (pull_request => workflow_run)'
          description: ${{ job.status == 'success' && env.DEPLOY_SUCCESS || env.DEPLOY_FAILURE }}