mattermost/.github/workflows/docs-preview-template.yml

name: docs-preview-template

on:
  workflow_call:
    inputs:
      PR_NUMBER:
        type: string
        required: true
      COMMIT_SHA:
        type: string
        required: true
      # Commit status context shown on the PR. Details (⋯) links to the preview
      # when status is success. Empty skips status updates.
      STATUS_CONTEXT:
        type: string
        required: false
        default: docs-preview
    secrets:
      AWS_DOCS_PR_PREVIEW_KEY_ID:
        required: true
      AWS_DOCS_PR_PREVIEW_SECRET_ACCESS_KEY:
        required: true

# Serialize runs per PR so an older, slower build can't overwrite a newer
# upload; different PRs still build concurrently.
concurrency:
  group: docs-preview-${{ inputs.PR_NUMBER }}
  cancel-in-progress: true

permissions:
  contents: read
  statuses: write

jobs:
  deploy:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
        with:
          ref: ${{ inputs.COMMIT_SHA }}
          submodules: true
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
        with:
          node-version-file: docs/site/.nvmrc
          cache: npm
          cache-dependency-path: docs/site/package-lock.json

      - name: Set up Go
        uses: actions/setup-go@4b73464bb391d4059bd26b0524d20df3927bd417 # v6.3.0
        with:
          go-version-file: api/server/go.mod

      - name: Install npm dependencies
        working-directory: docs/site
        run: npm ci

      - name: Typecheck
        working-directory: docs/site
        run: npm run typecheck

      - name: Build Docusaurus site (preview)
        working-directory: docs/site
        env:
          BASE_URL: /mattermost/pr-${{ inputs.PR_NUMBER }}/
        run: npm run build

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2
        with:
          aws-access-key-id: ${{ secrets.AWS_DOCS_PR_PREVIEW_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_DOCS_PR_PREVIEW_SECRET_ACCESS_KEY }}
          aws-region: us-east-1

      - name: Upload preview to S3
        # Repo-scoped prefix (mattermost/) — this bucket is shared
        # with mattermost/docs previews during the migration transition, and
        # PR numbers are per-repo, not global.
        #
        # No explicit --cache-control, matching mattermost/docs's existing
        # preview workflow (shallwefootball/s3-upload-action doesn't set one
        # either).
        env:
          PR_NUMBER: ${{ inputs.PR_NUMBER }}
          BUCKET_NAME: ${{ vars.DOCS_PREVIEW_BUCKET_NAME }}
        run: |
          if ! [[ "$PR_NUMBER" =~ ^[0-9]+$ ]]; then
            echo "PR_NUMBER must be a positive integer, got: $PR_NUMBER" >&2
            exit 1
          fi
          aws s3 sync docs/site/build/ \
            "s3://${BUCKET_NAME}/mattermost/pr-${PR_NUMBER}/" \
            --delete \
            --no-progress

      - name: Set preview URL
        id: preview
        env:
          BUCKET_NAME: ${{ vars.DOCS_PREVIEW_BUCKET_NAME }}
          PR_NUMBER: ${{ inputs.PR_NUMBER }}
        run: |
          echo "url=http://${BUCKET_NAME}.s3-website-us-east-1.amazonaws.com/mattermost/pr-${PR_NUMBER}/" >> "$GITHUB_OUTPUT"

      # Details (⋯) on this check links to the preview URL via target_url.
      - name: Set success commit status
        if: ${{ inputs.STATUS_CONTEXT != '' }}
        env:
          COMMIT_SHA: ${{ inputs.COMMIT_SHA }}
          CONTEXT_NAME: ${{ inputs.STATUS_CONTEXT }}
          PREVIEW_URL: ${{ steps.preview.outputs.url }}
          GH_TOKEN: ${{ github.token }}
          GITHUB_REPOSITORY: ${{ github.repository }}
        run: |
          gh api "repos/${GITHUB_REPOSITORY}/statuses/${COMMIT_SHA}" \
            -f state=success \
            -f context="${CONTEXT_NAME}" \
            -f description="Docs preview build for ${COMMIT_SHA} succeeded" \
            -f target_url="$PREVIEW_URL"

      - name: Set failure commit status
        if: ${{ always() && inputs.STATUS_CONTEXT != '' && (failure() || cancelled()) }}
        env:
          COMMIT_SHA: ${{ inputs.COMMIT_SHA }}
          CONTEXT_NAME: ${{ inputs.STATUS_CONTEXT }}
          GH_TOKEN: ${{ github.token }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          GITHUB_RUN_ID: ${{ github.run_id }}
        run: |
          gh api "repos/${GITHUB_REPOSITORY}/statuses/${COMMIT_SHA}" \
            -f state=failure \
            -f context="${CONTEXT_NAME}" \
            -f description="Docs preview build for ${COMMIT_SHA} failed" \
            -f target_url="https://github.com/${GITHUB_REPOSITORY}/actions/runs/${GITHUB_RUN_ID}"