name: 'Documentation (PR)'

on:
  pull_request:
    paths:
      - 'docs/**'
      - '.github/workflows/scripts/docs/build-docs.sh'
      - '.github/workflows/docs-preview-prepare.yml'

# If the workflow for a PR is triggered multiple times, previous existing runs will be canceled.
# eg: Applying multiple suggestions from a review directly via the Github UI.
# Instances of the 2nd phase of this workflow (via `workflow_run`) presently lack concurrency limits due to added complexity.
concurrency:
  group: deploypreview-pullrequest-${{ github.event.pull_request.number }}
  cancel-in-progress: true

# `pull_request` workflow is unreliable alone: Non-collaborator contributions lack access to secrets for security reasons.
# A separate workflow (docs-preview-deploy.yml) handles the deploy after the potentially untrusted code is first run in this workflow.
# See: https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
permissions:
  contents: read

jobs:
  prepare-preview:
    name: 'Build Preview'
    runs-on: ubuntu-22.04
    env:
      BUILD_DIR: docs/site
      NETLIFY_SITE_PREFIX: pullrequest-${{ github.event.pull_request.number }}
      NETLIFY_SITE_NAME: dms-doc-previews
    steps:
      - uses: actions/checkout@v4

      - name: 'Build with mkdocs-material via Docker'
        working-directory: docs
        env:
          PREVIEW_URL: 'https://${NETLIFY_SITE_PREFIX}--${NETLIFY_SITE_NAME}.netlify.app/'
          NETLIFY_BRANDING: '<a href="https://www.netlify.com/"><img alt="Deploys by Netlify" src="https://www.netlify.com/img/global/badges/netlify-color-accent.svg" style="float: right;"></a>'
        run: |
          # Adjust mkdocs.yml for preview build
          sed -i "s|^site_url:.*|site_url: '${PREVIEW_URL}'|" mkdocs.yml

          # Insert sponsor branding into page content (Provider OSS plan requirement):
          # Upstream does not provide a nicer maintainable way to do this..
          # Prepends HTML to copyright text and then aligns to the right side.
          sed -i "s|^copyright: '|copyright: '${NETLIFY_BRANDING}|" mkdocs.yml
          # Need to override a CSS media query for parent element to always be full width:
          echo '.md-footer-copyright { width: 100%; }' >> content/assets/css/customizations.css

          ../.github/workflows/scripts/docs/build-docs.sh

      # ============================== #
      # Volley over to secure workflow #
      # ============================== #

      # Minimize risk of upload failure by bundling files to a single compressed archive (tar + zstd).
      # Bundles build dir and env file into a compressed archive, nested file paths will be preserved.
      - name: 'Prepare artifact for transfer'
        env:
          # As a precaution, reference this value by an interpolated ENV var;
          # instead of interpolating user controllable input directly in the shell script..
          # https://github.com/docker-mailserver/docker-mailserver/issues/2332#issuecomment-998326798
          PR_TITLE: ${{ github.event.pull_request.title }}
        run: |
          # Save ENV for transfer
          {
            echo "PR_HEADSHA=${{ github.event.pull_request.head.sha }}"
            echo "PR_NUMBER=${{ github.event.pull_request.number }}"
            echo "PR_TITLE=${PR_TITLE}"
            echo "NETLIFY_SITE_PREFIX=${{ env.NETLIFY_SITE_PREFIX }}"
            echo "BUILD_DIR=${{ env.BUILD_DIR }}"
          } >> pr.env
          tar --zstd -cf artifact.tar.zst pr.env ${{ env.BUILD_DIR }}

      - name: 'Upload artifact for workflow transfer'
        uses: actions/upload-artifact@v4
        with:
          name: preview-build
          path: artifact.tar.zst
          retention-days: 1