Merge branch 'master' into terraform-cloudngfw

Author: migara

.github/workflows/codeql-analysis.yml

@@ -8,7 +8,7 @@ jobs:
   analyze:
     if: github.repository_owner	 == 'PaloAltoNetworks'
     name: Analyze
-    runs-on: pan-dev-runner
+    runs-on: ubuntu-latest
     permissions:
       contents: read
       security-events: write

.github/workflows/deploy-live.yml

@@ -44,8 +44,23 @@ jobs:
         - name: Install dependencies
           run: yarn --prefer-offline
 
+        # needed for fetching Hashicorp blog feed
+        - name: Install Playwright
+          run: |
+            npx playwright install chromium
+            npx playwright install-deps chromium
+
+        - name: Cache Playwright
+          uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+          with:
+            path: |
+              ~/.cache/ms-playwright
+            key: ${{ runner.os }}-playwright-${{ hashFiles('package.json') }}
+            restore-keys: |
+              ${{ runner.os }}-playwright-
+
         - name: Build site
-          run: REACT_APP_ERROR_REPORTER_APIKEY=${{ secrets.ERROR_REPORTER_APIKEY }} REACT_APP_FIREBASE_APIKEY=${{ secrets.FIREBASE_APIKEY }} REACT_APP_RECAPTCHA_APIKEY=${{ secrets.RECAPTCHA_APIKEY }} yarn build-github && zip -r build.zip build
+          run: REACT_APP_ERROR_REPORTER_APIKEY=${{ secrets.ERROR_REPORTER_APIKEY }} REACT_APP_FIREBASE_APIKEY=${{ secrets.FIREBASE_APIKEY }} REACT_APP_RECAPTCHA_APIKEY=${{ secrets.RECAPTCHA_APIKEY }} FEED_SOFT_FAIL=1 FEED_DEBUG=1 yarn build-github && zip -r build.zip build
 
         - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
           with:
@@ -56,6 +71,8 @@ jobs:
       name: Deploy
       needs: build
       runs-on: pan-dev-runner-lg
+      permissions:
+        id-token: write
 
       steps:
         - name: Checkout repository
@@ -74,12 +91,26 @@ jobs:
         - name: Unzip build artifact
           run: unzip build.zip
 
+        - name: Authenticate to Google Cloud
+          id: auth
+          uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5
+          with:
+            workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
+            service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}
+
+        - name: Export Google Cloud Credentials
+          run: echo "GCP_SA_KEY=$(cat ${{ steps.auth.outputs.credentials_file_path }})" >> $GITHUB_ENV
+
+        - uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4
+          with:
+            name: build
+
         - name: Deploy to Firebase
           id: deploy_live
-          uses: FirebaseExtended/action-hosting-deploy@120e124148ab7016bec2374e5050f15051255ba2 # v0.7.1
+          uses: FirebaseExtended/action-hosting-deploy@e2eda2e106cfa35cdbcf4ac9ddaf6c4756df2c8c # v0.10.0
           with:
             repoToken: '${{ secrets.GITHUB_TOKEN }}'
-            firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_PAN_DEV_F1B58 }}'
+            firebaseServiceAccount: "${{ env.GCP_SA_KEY }}"
             projectId: pan-dev-f1b58
             channelId: live
           env:

.github/workflows/deploy-preview.yml

@@ -6,30 +6,37 @@ on:
 
 jobs:
   precheck:
+    if: ${{ github.repository == 'PaloAltoNetworks/pan.dev' }}
     name: Precheck
     runs-on: ubuntu-latest
     permissions:
       contents: read
-      security-events: write
     outputs:
       is-org-member-result: ${{ steps.is-org-member.outputs.is-org-member-result }}
     steps:
       - name: Check if actor is org member
         id: is-org-member
         run: |
           if [[ "${{ github.actor }}" == "create-pr-on-fork-for-pan-dev[bot]" ]]; then
-            echo "is-org-member-result=null" >> "$GITHUB_OUTPUT"
+            echo "is-org-member-result=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          
+          status=$(curl -s -o /dev/null -w "%{http_code}" -H "Authorization: Bearer $GH_TOKEN" \
+            https://api.github.com/orgs/PaloAltoNetworks/members/${{ github.actor }})
+          if [ "$status" = "204" ]; then
+            echo "is-org-member-result=true" >> "$GITHUB_OUTPUT"
           else
-            echo "is-org-member-result=$(gh api -X GET orgs/PaloAltoNetworks/memberships/${{ github.actor }} | jq -r .message)" >> "$GITHUB_OUTPUT"
+            echo "is-org-member-result=false" >> "$GITHUB_OUTPUT"
           fi
-    env:
-      GH_TOKEN: ${{ secrets.READ_ORG_PAT }}
+        env:
+          GH_TOKEN: ${{ secrets.READ_ORG_PAT }}
 
   analyze:
-    if: github.repository_owner	== 'PaloAltoNetworks' && needs.precheck.outputs.is-org-member-result == 'null'
+    if: github.repository == 'PaloAltoNetworks/pan.dev' && needs.precheck.outputs.is-org-member-result == 'true'
     name: Analyze
     needs: precheck
-    runs-on: pan-dev-runner
+    runs-on: ubuntu-latest
     permissions:
       contents: read
       security-events: write
@@ -54,10 +61,10 @@ jobs:
       uses: github/codeql-action/analyze@1b549b9259bda1cb5ddde3b41741a82a2d15a841 # v3
 
   analyze_unsafe:
-    if: github.repository_owner	== 'PaloAltoNetworks' && needs.precheck.outputs.is-org-member-result != 'null'
+    if: github.repository == 'PaloAltoNetworks/pan.dev' && needs.precheck.outputs.is-org-member-result == 'false'
     name: Analyze Unsafe
     needs: precheck
-    runs-on: pan-dev-runner
+    runs-on: ubuntu-latest
     environment: default
     permissions:
       contents: read
@@ -86,7 +93,8 @@ jobs:
     name: Build
     needs: [analyze, analyze_unsafe]
     if: |
-      !failure() && !cancelled() && 
+      github.repository == 'PaloAltoNetworks/pan.dev' &&
+      !failure() && !cancelled() &&
       (success('analyze') || success('analyze_unsafe'))
     runs-on: pan-dev-runner-xl
     permissions:
@@ -108,22 +116,6 @@ jobs:
         id: yarn-cache
         run: echo "YARN_CACHE_DIR=$(yarn cache dir)" >> "${GITHUB_OUTPUT}"
 
-      # - name: Cache dependencies
-      #   uses: actions/cache@v4
-      #   with:
-      #     path: ${{ steps.yarn-cache.outputs.YARN_CACHE_DIR }}
-      #     key: ${{ runner.os }}-pandev-${{ hashFiles('**/yarn.lock') }}
-      #     restore-keys: |
-      #       ${{ runner.os }}-pandev-
-
-      # - name: Cache docusaurus build
-      #   uses: actions/cache@v4
-      #   with:
-      #     path: node_modules/.cache/webpack
-      #     key: ${{ runner.os }}-pandev-pr-${{ github.event.number }}-${{ hashFiles('**/yarn.lock') }}
-      #     restore-keys: |
-      #       ${{ runner.os }}-pandev-pr-${{ github.event.number }}-
-
       - name: Install dependencies
         run: yarn --prefer-offline
 
@@ -132,9 +124,9 @@ jobs:
         run: |
           echo "Including 'netsec' in build..."
           if [[ -n "$PRODUCTS_INCLUDE" ]]; then
-            echo "PRODUCTS_INCLUDE=$PRODUCTS_INCLUDE,cdss,threat-vault,dns-security,iot,expedition,cloudngfw,cdl,panos,terraform,ansible,splunk,aiops-ngfw-bpa,email-dlp,dlp,ai-runtime-security" >> $GITHUB_ENV
+            echo "PRODUCTS_INCLUDE=$PRODUCTS_INCLUDE,cdss,threat-vault,dns-security,iot,expedition,cloudngfw,cdl,panos,terraform,ansible,splunk,aiops-ngfw-bpa,email-dlp,dlp,prisma-airs" >> $GITHUB_ENV
           else
-            echo "PRODUCTS_INCLUDE=cdss,threat-vault,dns-security,iot,expedition,cloudngfw,cdl,panos,terraform,ansible,splunk,aiops-ngfw-bpa,email-dlp,dlp,ai-runtime-security" >> $GITHUB_ENV
+            echo "PRODUCTS_INCLUDE=cdss,threat-vault,dns-security,iot,expedition,cloudngfw,cdl,panos,terraform,ansible,splunk,aiops-ngfw-bpa,email-dlp,dlp,prisma-airs" >> $GITHUB_ENV
           fi
       
       - name: Include cloud
@@ -171,8 +163,23 @@ jobs:
         run: |
           echo "Building the following products: $PRODUCTS_INCLUDE"
 
+      # needed for fetching Hashicorp blog feed
+      - name: Install Playwright
+        run: |
+          npx playwright install chromium
+          npx playwright install-deps chromium
+
+      - name: Cache Playwright
+        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+        with:
+          path: |
+            ~/.cache/ms-playwright
+          key: ${{ runner.os }}-playwright-${{ hashFiles('package.json') }}
+          restore-keys: |
+            ${{ runner.os }}-playwright-
+
       - name: Build site
-        run: yarn build-github
+        run: FEED_SOFT_FAIL=1 FEED_DEBUG=1 yarn build-github
 
       - name: Zip build directory
         run: |
@@ -196,8 +203,13 @@ jobs:
   deploy:
     name: Deploy
     needs: build
-    if: ${{ !failure() && !cancelled() }}
+    if: ${{ github.repository == 'PaloAltoNetworks/pan.dev' && !failure() && !cancelled() }}
     runs-on: pan-dev-runner-lg
+    permissions:
+      contents: read
+      pull-requests: write
+      checks: write
+      id-token: write
 
     steps:
       - name: Checkout repository
@@ -227,12 +239,26 @@ jobs:
           echo "Deploy directory found at: $DEPLOY_DIR"
           echo "DEPLOY_DIR=$DEPLOY_DIR" >> $GITHUB_ENV
 
+      - name: Authenticate to Google Cloud
+        id: auth
+        uses: google-github-actions/auth@b7593ed2efd1c1617e1b0254da33b86225adb2a5
+        with:
+          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
+          service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }}
+
+      - name: Export Google Cloud Credentials
+        run: echo "GCP_SA_KEY=$(cat ${{ steps.auth.outputs.credentials_file_path }})" >> $GITHUB_ENV
+
+      - uses: actions/download-artifact@95815c38cf2ff2164869cbab79da8d1f422bc89e # v4
+        with:
+          name: build
+
       - name: Deploy to Firebase
         id: deploy_preview
-        uses: FirebaseExtended/action-hosting-deploy@120e124148ab7016bec2374e5050f15051255ba2 # v0.7.1
+        uses: FirebaseExtended/action-hosting-deploy@e2eda2e106cfa35cdbcf4ac9ddaf6c4756df2c8c # v0.10.0
         with:
           repoToken: '${{ secrets.GITHUB_TOKEN }}'
-          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT_PAN_DEV_F1B58 }}'
+          firebaseServiceAccount: "${{ env.GCP_SA_KEY }}"
           projectId: pan-dev-f1b58
           expires: 30d
           channelId: 'pr${{ github.event.number }}'

.gitignore

@@ -30,3 +30,7 @@ products/**/versions.json
 # downloaded feeds/blogs
 src/**/blogs.json
 src/**/feeds.json
+
+# playwright
+.playwright-storage.json
+.pw-user-data/

.gitlab-ci.yml

@@ -1,4 +1,4 @@
-image: docker.art.code.pan.run/build-tools--image-node:16.ep1
+image: docker.art.code.pan.run/build-tools--image-node:cee4eae3
 
 cache:
   paths:
@@ -14,7 +14,7 @@ pages:
     - echo "$GL_PAGES_URL"
     - echo "$GL_PAGES_BASE_URL"
     - yarn install
-    - yarn run build
+    - yarn run build-github
     - mv build public
   artifacts:
     paths:
@@ -33,7 +33,7 @@ pages:
   stage: 📦 publish
   script:
     - yarn install
-    - yarn run build
+    - yarn run build-github
     - mv build public
   artifacts:
     paths:

AGENTS.md

@@ -0,0 +1,103 @@
+# AGENTS.md
+
+> **Audience** – Automated coding assistants (OpenAI Codex, Sourcegraph AMP, Windsurf, etc.). Humans are welcome to read it too!
+
+---
+
+## 🚀 Quick Facts
+
+| Key                  | Value                                                                                           |
+| -------------------- | ----------------------------------------------------------------------------------------------- |
+| **Site**             | **pan.dev** – public developer documentation for Palo Alto Networks                             |
+| **Generator**        | Docusaurus **3.8.1** (static site)                                                              |
+| **Tooling**          | Node 20 LTS (see `.nvmrc`)                                                                      |
+| **Selective builds** | `PRODUCTS_INCLUDE` env‑var lets you build one or more products instead of the whole site (≈1 h) |
+
+---
+
+## 🗺️ Repository Map (top‑level)
+
+| Path             | Purpose                                                                 |
+| ---------------- | ----------------------------------------------------------------------- |
+| `products/`      | One folder per product → MDX docs, MD docs, `sidebars.{js,ts}`          |
+| `src/pages/`     | Homepage & other global landing pages – **agents SHOULD improve these** |
+| `src/`           | Shared React + TS components, theme overrides, utilities                |
+| `static/`        | Assets copied verbatim to the final build                               |
+| `plugin-*`       | Custom Docusaurus plugins (`plugin-sitemap-coveo`, GTM, etc.)           |
+| `scripts/`       | Automation helpers (e.g., `openapi-to-mdx.ts`)                          |
+| `openapi-specs/` | Raw OpenAPI JSON/YAML files fed into docusaurus-plugin-openapi-docs     |
+| `.github/`       | Workflows (self‑hosted runners, preview deploys)                        |
+
+> **Gotcha** – Some products share a sidebar. If you omit one of those products from `PRODUCTS_INCLUDE`, the build will throw an “Unknown sidebar” error. When unsure, include the whole family (e.g., `sase,access,sdwan,scm`) or base the build command on the package.json scripts.
+
+---
+
+## 🛠️ Local Dev Cheat‑Sheet
+
+```bash
+# Install deps (Node 20 LTS)
+yarn
+
+# Full dev (slow)
+yarn start
+
+# Fast dev – only selected products
+PRODUCTS_INCLUDE=contributing yarn start
+
+# Format
+yarn format
+
+# Production build (for testing and development)
+PRODUCTS_INCLUDE=contributing,prisma-airs yarn build-github
+```
+
+---
+
+## ✍️ Writing & Coding Guidelines
+
+| ✅ **DO**                                                             | ❌ **AVOID**                             |
+| -------------------------------------------------------------------- | --------------------------------------- |
+| Use plain English; define acronyms on first use                      | Security‑jargon overload                |
+| Add front‑matter: `id`, `title`, `sidebar_label`, `sidebar_position` | Missing or duplicate `id`s              |
+| Keep headings hierarchical (H2 → H3 → H4)                            | Skipping heading levels                 |
+| Provide runnable examples (`curl`, `python`, `golang`)               | Proprietary/internal endpoints          |
+| Run `yarn format` (Prettier) before every commit                     | Inconsistent spacing or 100+‑char lines |
+| Add **alt text** for images (a11y)                                   | Decorative images without alt text      |
+
+### Front‑end Conventions
+
+* React functional components in **TypeScript strict mode** (see `tsconfig.json`).
+* Style with CSS Modules.
+* Theme import paths use the `@theme/` alias.
+* Site import paths use the `@site/` alias.
+
+---
+
+## 🤖 Common Agent Tasks
+
+1. **Generate product documentation based on input from human.** - update/add MDX or MD files, update sidebars, test with selective build, etc.
+2. **Improve landing pages** – edit/update and improve pages under `src/pages`.
+3. **Fix issues** - open a PR with proposed fix(es) after thoroughly reviewing a Github issue. 
+
+> Always open a PR —even for small fixes. GitHub Actions deploys a preview to Firebase for human review.
+
+---
+
+## 🔒 Safety & Compliance
+
+* **NO SECRETS** – never commit API keys, internal hostnames, or proprietary code.
+* Repo is public; content must stay customer‑friendly & vendor‑neutral.
+* Aim for WCAG AA accessibility (semantic HTML, good contrast, alt text).
+
+---
+
+## 📚 Further Reading
+
+* [`README.md`](./README.md) – project overview
+* [`CONTRIBUTING.md`](./CONTRIBUTING.md) – full contribution guide
+* Docusaurus docs → [https://docusaurus.io/docs](https://docusaurus.io/docs)
+* Docusaurus OpenAPI Docs plugin → [https://docusaurus-openapi.tryingpan.dev](https://docusaurus-openapi.tryingpan.dev)
+
+---
+
+*Last updated: **2025‑07‑23***