Add Purge Fastly (all) workflow for on-demand full cache purge (#61734)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: heiskr

.github/workflows/purge-fastly-all.yml

@@ -0,0 +1,44 @@
+name: Purge Fastly (all)
+
+# **What it does**: Purges the ENTIRE Fastly cache for docs (every URL) on demand.
+# **Why we have it**: So docs engineering can clear a bad cache state without asking core engineering to run a purge-all in the Fastly UI.
+# **Who does it impact**: All readers. Origin sees a traffic spike while the cache refills, so only run this when a targeted purge will not do.
+
+on:
+  workflow_dispatch:
+    inputs:
+      confirm:
+        description: "Type 'purge everything' to confirm a full hard purge of the Fastly cache."
+        required: true
+
+permissions:
+  contents: read
+
+# Only one purge-all may run at a time. Do not cancel an in-flight purge:
+# a half-finished purge leaves the cache in an unknown state.
+concurrency:
+  group: purge-fastly-all
+  cancel-in-progress: false
+
+env:
+  FASTLY_TOKEN: ${{ secrets.FASTLY_TOKEN }}
+  FASTLY_SERVICE_ID: ${{ secrets.FASTLY_SERVICE_ID }}
+
+jobs:
+  purge-all:
+    if: github.repository == 'github/docs-internal'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Validate confirmation input
+        if: ${{ inputs.confirm != 'purge everything' }}
+        run: |
+          echo "::error::Confirmation text did not match. Re-run and type exactly: purge everything"
+          exit 1
+
+      - name: Check out repo
+        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
+
+      - uses: ./.github/actions/node-npm-setup
+
+      - name: Purge entire Fastly cache
+        run: npm run purge-fastly-all

package.json

@@ -80,6 +80,7 @@
     "prevent-pushes-to-main": "tsx src/workflows/prevent-pushes-to-main.ts",
     "purge-fastly-edge-cache": "tsx src/workflows/purge-fastly-edge-cache.ts",
     "purge-fastly-edge-cache-per-language": "tsx src/languages/scripts/purge-fastly-edge-cache-per-language.ts",
+    "purge-fastly-all": "tsx src/workflows/purge-fastly-all.ts",
     "readability-report": "tsx src/workflows/experimental/readability-report.ts",
     "ready-for-docs-review": "tsx src/workflows/ready-for-docs-review.ts",
     "release-banner": "tsx src/ghes-releases/scripts/release-banner.ts",

src/workflows/purge-fastly-all.ts

@@ -0,0 +1,59 @@
+import { fetchWithRetry } from '@/frame/lib/fetch-utils'
+
+// Purges the ENTIRE Fastly cache for the docs service via Fastly's purge_all
+// endpoint. This is the workflow equivalent of the "Purge all" button in the
+// Fastly UI. It is intentionally a separate, manually triggered entry point:
+// routine post-deploy purging is handled by
+// `purge-fastly-edge-cache-per-language.ts`, and a gentler "refresh everything"
+// can be done by running the Purge Fastly workflow with an empty languages
+// input (a soft surrogate-key purge of every language).
+//
+// NOTE: Fastly's purge_all is always a HARD purge. The `fastly-soft-purge`
+// header has no effect on this endpoint, so every object is evicted immediately
+// and origin sees a traffic spike while the cache refills. Only reach for this
+// when a targeted purge will not do.
+// https://www.fastly.com/documentation/reference/api/purging/
+
+async function purgeFastlyAll({ apiToken, serviceId }: { apiToken: string; serviceId: string }) {
+  const safeServiceId = encodeURIComponent(serviceId)
+  const requestPath = `https://api.fastly.com/service/${safeServiceId}/purge_all`
+  const response = await fetchWithRetry(
+    requestPath,
+    {
+      method: 'POST',
+      headers: {
+        'fastly-key': apiToken,
+        accept: 'application/json',
+        'Content-Type': 'application/json',
+      },
+    },
+    {
+      retries: 0,
+      timeout: 30_000,
+      throwHttpErrors: false,
+    },
+  )
+  if (!response.ok) {
+    // Fastly puts permission/feature-disabled details in the response body,
+    // which is often the only actionable signal, so surface it best-effort.
+    let body = ''
+    try {
+      body = await response.text()
+    } catch {
+      body = ''
+    }
+    throw new Error(
+      `Fastly purge_all failed: HTTP ${response.status} ${response.statusText}${body ? `: ${body}` : ''}`,
+    )
+  }
+  return response
+}
+
+const { FASTLY_TOKEN, FASTLY_SERVICE_ID } = process.env
+if (!FASTLY_TOKEN || !FASTLY_SERVICE_ID) {
+  throw new Error('Fastly env vars not detected; refusing to run purge_all')
+}
+
+console.log('Attempting Fastly purge_all (hard purge of the entire cache)...')
+const result = await purgeFastlyAll({ apiToken: FASTLY_TOKEN, serviceId: FASTLY_SERVICE_ID })
+console.log('Fastly purge_all result:', result.status)