From ee0d969c1d4d48f7ea431d9f8839f6dd9f0591cd Mon Sep 17 00:00:00 2001
From: Wonjun Choi <99017069+wonjun-lab@users.noreply.github.com>
Date: Thu, 5 Nov 2026 11:57:31 +0900
Subject: [PATCH] ci: validate documentation changes with isolated read-only PR
 builds

---
 .github/workflows/docs.yml | 50 ++++++++++++++++++++++++++------------
 1 file changed, 35 insertions(+), 15 deletions(-)

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 9c23eb9..01f5e3e 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -6,58 +6,78 @@ on:
       - main
     paths:
       - 'docs/**'
+      - 'validate_bibtex.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'validate_bibtex.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
       - '.github/workflows/docs.yml'
   workflow_dispatch:  # 수동 실행 가능
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: "pages"
-  cancel-in-progress: false
+  # Cancel superseded PR validation while preserving every main build.
+  group: ${{ github.event_name == 'pull_request' && format('{0}-pr-{1}', github.workflow, github.event.pull_request.number) || format('{0}-run-{1}', github.workflow, github.run_id) }}
+  cancel-in-progress: true
 
 jobs:
   build:
-    runs-on: [self-hosted, ml-main]
+    # Untrusted PR code runs on an isolated hosted runner.
+    runs-on: ${{ fromJSON(github.event_name == 'pull_request' && '["ubuntu-24.04"]' || '["self-hosted", "ml-main"]') }}
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
 
       - name: Setup Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
         with:
           python-version: '3.11'
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v4
+        uses: astral-sh/setup-uv@38f3f104447c67c051c4a08e39b64a148898af3a # v4
 
       - name: Install dependencies
         run: |
-          uv sync --group dev
+          uv sync --group dev --locked
 
       - name: Build Sphinx documentation
         run: |
           cd docs
-          uv run sphinx-build -b html source build/html
-
-      - name: Setup Pages
-        uses: actions/configure-pages@v4
+          uv run --locked sphinx-build -b html source build/html
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
         with:
           path: docs/build/html
 
   deploy:
+    if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    permissions:
+      pages: write
+      id-token: write
+    # Keep the existing serialized Pages publication policy.
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: [self-hosted, ml-main]
     needs: build
     steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@1f0c5cde4bc74cd7e1254d0cb4de8d49e9068c7d # v4
+
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4