ci: Gate PR Preview Deploys from Outside Contributors

.github/workflows/pr-preview-cleanup.yml

@@ -0,0 +1,33 @@
+name: PR Preview Cleanup
+
+on:
+  pull_request_target:
+    types: [closed]
+    branches:
+      - develop
+
+permissions:
+  id-token: write
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
+        with:
+          role-to-assume: ${{ vars.AMPLIFY_PREVIEW_ROLE_ARN }}
+          aws-region: us-east-1
+      - name: Delete Amplify preview branch
+        env:
+          APP_ID: ${{ vars.AMPLIFY_APP_ID }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          set -euo pipefail
+          BRANCH="pr-${PR_NUMBER}"
+          if aws amplify get-branch --app-id "$APP_ID" --branch-name "$BRANCH" >/dev/null 2>&1; then
+            aws amplify delete-branch --app-id "$APP_ID" --branch-name "$BRANCH" >/dev/null
+            echo "Deleted $BRANCH"
+          else
+            echo "No preview branch $BRANCH to delete"
+          fi

.github/workflows/pr-preview.yml

@@ -0,0 +1,126 @@
+name: PR Preview
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened]
+    branches:
+      - develop
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  resolve:
+    runs-on: ubuntu-latest
+    permissions: {}
+    outputs:
+      pr_number: ${{ steps.route.outputs.pr_number }}
+      environment: ${{ steps.route.outputs.environment }}
+    steps:
+      - id: route
+        env:
+          ASSOCIATION: ${{ github.event.pull_request.author_association }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+        run: |
+          case "$ASSOCIATION" in
+            OWNER|MEMBER|COLLABORATOR) environment=pr-preview-auto ;;
+            *) environment=pr-preview-gated ;;
+          esac
+          echo "pr_number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+          echo "environment=$environment" >> "$GITHUB_OUTPUT"
+          echo "PR #$PR_NUMBER association $ASSOCIATION routes to $environment"
+
+  build:
+    needs: resolve
+    runs-on: ubuntu-latest
+    # Never attach secrets to pr-preview-auto or pr-preview-gated; this job runs untrusted fork code.
+    environment:
+      name: ${{ needs.resolve.outputs.environment }}
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: ${{ github.event.pull_request.head.repo.full_name }}
+          ref: ${{ github.event.pull_request.head.sha }}
+          persist-credentials: false
+      - uses: ./.github/actions/dependencies
+      - name: Build docs site
+        run: pnpm build
+      - name: Upload preview site
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: pr-preview-site
+          path: docs/dist
+          retention-days: 7
+
+  deploy:
+    needs: [resolve, build]
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      pull-requests: write
+      issues: write
+    steps:
+      - name: Download preview site
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: pr-preview-site
+          path: docs/dist
+      - name: Configure AWS credentials
+        uses: aws-actions/configure-aws-credentials@e6de054238d6b7531b4efff3b6587d9aade6a06c # v6.2.3
+        with:
+          role-to-assume: ${{ vars.AMPLIFY_PREVIEW_ROLE_ARN }}
+          aws-region: us-east-1
+      - name: Deploy to Amplify
+        env:
+          APP_ID: ${{ vars.AMPLIFY_APP_ID }}
+          PR_NUMBER: ${{ needs.resolve.outputs.pr_number }}
+        run: |
+          set -euo pipefail
+          BRANCH="pr-${PR_NUMBER}"
+          aws amplify get-branch --app-id "$APP_ID" --branch-name "$BRANCH" >/dev/null 2>&1 || aws amplify create-branch --app-id "$APP_ID" --branch-name "$BRANCH" >/dev/null
+          ( cd docs/dist && zip -r -q "$GITHUB_WORKSPACE/site.zip" . )
+          DEPLOYMENT="$(aws amplify create-deployment --app-id "$APP_ID" --branch-name "$BRANCH")"
+          JOB_ID="$(echo "$DEPLOYMENT" | jq -r '.jobId')"
+          ZIP_URL="$(echo "$DEPLOYMENT" | jq -r '.zipUploadUrl')"
+          curl -fsS -H "Content-Type: application/zip" --upload-file site.zip "$ZIP_URL"
+          aws amplify start-deployment --app-id "$APP_ID" --branch-name "$BRANCH" --job-id "$JOB_ID" >/dev/null
+      - name: Comment preview URL
+        uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
+        env:
+          PR_NUMBER: ${{ needs.resolve.outputs.pr_number }}
+          APP_ID: ${{ vars.AMPLIFY_APP_ID }}
+        with:
+          script: |
+            const prNumber = Number(process.env.PR_NUMBER);
+            const appId = process.env.APP_ID;
+            const marker = '<!-- pr-preview -->';
+            const url = `https://pr-${prNumber}.${appId}.amplifyapp.com`;
+            const body = `${marker}\nDocs preview: ${url}`;
+            const { owner, repo } = context.repo;
+            const { data: comments } = await github.rest.issues.listComments({
+              owner,
+              repo,
+              issue_number: prNumber
+            });
+            const existing = comments.find((c) => c.body?.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner,
+                repo,
+                comment_id: existing.id,
+                body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number: prNumber,
+                body
+              });
+            }

CONTRIBUTING.md

@@ -143,7 +143,7 @@ Cauldron does not have a dedicated quality assurance (QA) individual. Having a f
 
 Every Cauldron component needs to be compatible with server-side rendering (SSR). A component should be able to render in an SSR environment such as [Gatsby.js](https://www.gatsbyjs.com/) or [Next.js](https://nextjs.org/) while avoiding DOM globals like `document` or `window` that are not available in these environments.
 
-Cauldron uses [`eslint-plugin-ssr-friendly`](https://github.com/kopiro/eslint-plugin-ssr-friendly) to help prevent the accidental misuse of DOM globals. An additional [utility](./packages/react/src/utils/is-browser.ts) is available to help guard against using DOM globals:
+Cauldron uses [`eslint-plugin-ssr-friendly`](https://github.com/kopiro/eslint-plugin-ssr-friendly) to help prevent the accidental misuse of DOM globals. An additional [utility](./packages/react/src/utils/is-browser/index.ts) is available to help guard against using DOM globals:
 
 ```tsx
 import { isBrowser } from '../../utils/is-browser';
@@ -210,7 +210,13 @@ Once approved by a member of the Cauldron team, your pull request can be merged
 
 #### Previewing Changes
 
-Cauldron documentation is deployed automatically via [amplify web previews for pull requests](https://docs.aws.amazon.com/amplify/latest/userguide/pr-previews.html) with each commit to a PR. To view the preview of your changes, navigate to your PR and find the comment from the `aws-amplify` bot, which will include a link to the preview site for that PR. The preview site will only persist for as long as the PR remains opened and will be deleted when closed.
+Cauldron deploys a documentation preview for pull requests through a GitHub Actions workflow. A pull request opened by a Deque organization member builds and deploys a preview automatically.
+
+A pull request from an outside contributor waits for a Cauldron maintainer to approve the preview. Nothing builds or deploys until that approval, and every new push to the pull request waits for a fresh approval. Once a preview deploys, the workflow posts a comment with a link to the preview site. The preview is removed when the pull request is closed.
+
+A maintainer reviews the full pull request before approving the preview. That review includes reading the code and confirming the change is safe to build and to publish to a URL under Deque's Amplify app.
+
+Maintainers: never add a secret to the `pr-preview-auto` or `pr-preview-gated` GitHub Environments. The build job runs contributor code inside the routed environment, so a secret placed there could be read by that code. These environments hold only reviewer and branch rules.
 
 ### Testing Strategies