Three post-deploy checks I run after every Cloudflare Pages build

Hardening Static Deployments: Automated Validation for Sitemaps, IndexNow, and Core Web Vitals on Cloudflare Pages

Current Situation Analysis

Static site generators (SSG) deployed to edge networks like Cloudflare Pages offer exceptional performance and reliability, but they introduce a specific class of "invisible" failure modes. Developers often operate under the assumption that a successful build pipeline equates to a successful deployment. This is a dangerous simplification. Edge networks introduce caching layers, automatic redirects, and propagation delays that can silently break SEO infrastructure while the site remains visually functional for human visitors.

The core pain point is the Browser Illusion. Modern browsers automatically follow HTTP 3xx redirects. If a misconfiguration rewrites a critical SEO path (like sitemap-index.xml) to a fallback or an error page, the browser renders the result and reports a 200 OK status. Search engine crawlers, however, may reject the redirect chain, interpret the response as a soft 404, or fail to parse the content type correctly. This discrepancy can lead to pages being dropped from search indices without any immediate alert.

Evidence from production environments shows that redirect misconfigurations can persist for days. In documented cases, a _redirects rule intended as a temporary workaround suppressed the primary sitemap index for over 120 hours. During this window, crawlers received broken responses, yet manual browser checks showed no errors. Furthermore, static sites often rely on build-time data pipelines (e.g., fetching content from a headless CMS or database). If the data pipeline fails silently, the sitemap may generate successfully with a 200 status but contain zero or stale URLs, effectively de-indexing the site.

WOW Moment: Key Findings

The critical insight is that validation strategies must diverge based on the consumer. A validation script designed to protect SEO must behave like a crawler, not a browser. The table below illustrates how different validation approaches perceive the same deployment state when a redirect misconfiguration exists.

Validation Method	Behavior on Redirect Misconfiguration	Result	SEO Impact
Browser Check	Follows 301/302 automatically; renders final content.	200 OK (False Positive)	High Risk: Developer assumes site is healthy.
Standard Curl	Follows redirects by default (-L); reports final code.	200 OK (False Positive)	High Risk: Masks the redirect chain issue.
Strict Validation	Uses redirect: 'manual' or --max-redirs 0; inspects headers.	301 Moved or 404	Safe: Immediately flags the configuration error.
Content Assertion	Parses XML payload; counts <url> nodes.	200 OK but count=0	Safe: Detects silent ETL/data pipeline failures.

This finding enables a shift from "visual verification" to "contract-based validation." By enforcing strict redirect policies and content assertions in post-deploy scripts, teams can catch SEO regressions before crawlers penalize the site.

Core Solution

The solution involves a three-layer validation pipeline tailored for Astro SSG sites on Cloudflare Pages. This pipeline addresses sitemap integrity, IndexNow propagation timing, and Core Web Vitals regression.

Layer 1: Sitemap Integrity with Strict Redirect Enforcement

The first layer verifies that the sitemap index is reachable without redirects and contains a valid payload. This script uses fetch with redirect: 'manual' to ensure any rewrite rule triggers an immediate failure. It also parses the XML to assert a minimum URL count, protecting against silent data pipeline failures.

Implementation: scripts/validate-sitemap.ts

import { parseStringPromise } from 'xml2js';

interface SitemapConfig {
  domain: string;
  minUrlCount: number;
}

const SITES: SitemapConfig[] = [
  { domain: 'aiappdex.com', minUrlCount: 1000 },
  { domain: 'findindiegame.com', minUrlCount: 100 },
  { domain: 'ossfind.com', minUrlCount: 50 },
];

async function checkSitemapIntegrity(config: SitemapConfig): Promise<void> {
  const sitemapUrl = `https://${config.domain}/sitemap-index.xml`;
  
  // CRITICAL: redirect: 'manual' prevents following 3xx responses.
  // This catches _redirects rules that masquerade as success.
  const response = await fetch(sitemapUrl, { redirect: 'manual' });

  if (response.status !== 200) {
    throw new Error(
      `Sitemap check failed for ${config.domain}. ` +
      `Expected 200, got ${response.status}. ` +
      `Redirect headers: ${JSON.stringify(Object.fromEntries(response.headers))}`
    );
  }

  const xmlContent = await response.text();
  const parsed = await parseStringPromise(xmlContent);
  
  // Count URLs in the index or sub-sitemaps
  const urlCount = parsed.sitemapindex?.sitemap?.length || 0;
  
  if (urlCount < config.minUrlCount) {
    throw new Error(
      `Sitemap content check failed for ${config.domain}. ` +
      `Expected >= ${config.minUrlCount} entries, found ${urlCount}. ` +
      `Possible ETL pipeline failure.`
    );
  }

  console.log(`✅ ${config.domain}: Sitemap valid (${urlCount} entries)`);
}

// Execution
(async () => {
  const results = await Promise.allSettled(
    SITES.map(checkSitemapIntegrity)
  );
  
  const failures = results.filter(r => r.status === 'rejected');
  if (failures.length > 0) {
    console.error('❌ Sitemap validation failed:', failures);
    process.exit(1);
  }
})();

Rationale:

• redirect: 'manual': This is the non-negotiable setting. It ensures the script fails if Cloudflare applies any rewrite, which is the exact failure mode that breaks crawlers.
• Content Assertion: A 200 response with an empty sitemap is functionally identical to a 404 for SEO. Asserting minUrlCount catches build-time data fetch errors.
• Parallel Execution: Promise.allSettled allows checking all domains simultaneously, reducing validation latency.

Layer 2: IndexNow Batch Submission with Deploy Lag Awareness

IndexNow allows immediate notification of search engines when content changes. However, submitting URLs before the edge network has fully propagated results in crawlers hitting stale or missing content. Cloudflare Pages deployments typically require 2–3 minutes for global propagation.

Implementation: scripts/trigger-indexnow.ts

import { readFileSync } from 'fs';
import { parseStringPromise } from 'xml2js';

interface IndexNowPayload {
  host: string;
  key: string;
  keyLocation: string;
  urlList: string[];
}

async function submitToIndexNow(
  domain: string, 
  apiKey: string, 
  sitemapUrl: string
): Promise<void> {
  // Fetch live sitemap to ensure we submit only propagated URLs
  const response = await fetch(sitemapUrl);
  if (!response.ok) throw new Error(`Cannot read sitemap for ${domain}`);
  
  const xml = await response.text();
  const parsed = await parseStringPromise(xml);
  
  // Extract URLs from sitemapindex or urlset
  const urls = parsed.sitemapindex?.sitemap?.map(s => s.loc[0]) || 
               parsed.urlset?.url?.map(u => u.loc[0]) || [];

  const payload: IndexNowPayload = {
    host: domain,
    key: apiKey,
    keyLocation: `https://${domain}/.well-known/indexnow-key.txt`,
    urlList: urls,
  };

  const submitResponse = await fetch('https://api.indexnow.org/indexnow', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });

  if (!submitResponse.ok) {
    const body = await submitResponse.text();
    throw new Error(`IndexNow submission failed for ${domain}: ${submitResponse.status} - ${body}`);
  }

  console.log(`🚀 ${domain}: Submitted ${urls.length} URLs to IndexNow`);
}

// Usage requires separate workflow step to ensure deploy completion

Rationale:

• Separate Workflow Trigger: This script should not run inline with the build. It must be triggered via a workflow_dispatch or a post-deploy job that waits for the Cloudflare Pages deployment to reach a deployed state. This prevents race conditions where IndexNow notifies crawlers of URLs that are not yet live.
• Key Location Verification: The script assumes the key file is at /.well-known/indexnow-key.txt. If a _redirects rule blocks this path, IndexNow returns 403. The validation script should also check the key file accessibility.

Layer 3: Weekly Lighthouse Trend Monitoring

For static sites, Core Web Vitals should remain stable. Regression usually indicates a change in asset delivery, CSS layout shifts, or third-party script injection. Running Lighthouse on every deploy is resource-intensive and often yields false positives due to network variance. A weekly cron job provides a reliable trend signal.

Implementation: GitHub Actions Cron Workflow

name: Weekly Lighthouse Audit
on:
  schedule:
    - cron: '30 4 * * 1' # Monday 04:30 UTC
  workflow_dispatch:

jobs:
  audit:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        site:
          - domain: aiappdex.com
            paths: ['/', '/models/timm-vit-base-patch16-clip-224-openai/']
          - domain: findindiegame.com
            paths: ['/', '/games/dredge-1562430/']
          - domain: ossfind.com
            paths: ['/', '/alternatives/ghost/']
    
    steps:
      - name: Run Lighthouse CI
        uses: treosh/lighthouse-ci-action@v12
        with:
          uploadArtifacts: true
          temporaryPublicStorage: true
          config: |
            {
              "ci": {
                "collect": {
                  "url": ${{ toJson(matrix.site.paths) | map(p => "https://" + matrix.site.domain + p) }},
                  "numberOfRuns": 3
                },
                "assert": {
                  "preset": "lighthouse:no-pwa",
                  "performance": ["error", { "minScore": 0.80 }],
                  "layout-shifts": ["error", { "maxLength": 0.1 }]
                }
              }
            }

Rationale:

• Trend vs. Gate: For pre-revenue or low-traffic static sites, hard failures on Lighthouse scores can block legitimate deploys due to minor fluctuations. The configuration sets error thresholds but treats results as artifacts for diffing. The goal is to detect regressions (e.g., Performance dropping from 95 to 75) rather than enforce perfection.
• Deep Path Sampling: Checking only the homepage misses layout shifts in content-heavy pages. The matrix includes one deep entry per site to catch component-specific regressions (e.g., ad slots or dynamic cards).

Pitfall Guide

1. The Redirect Mirage

   • Explanation: Using standard HTTP clients that follow redirects by default. A misconfigured _redirects rule rewrites sitemap.xml to index.html. The client receives 200 OK, but the content is HTML, not XML. Crawlers reject this.
   • Fix: Always use redirect: 'manual' or --max-redirs 0 in validation scripts. Inspect the Content-Type header to ensure it matches application/xml.

2. IndexNow Race Conditions

   • Explanation: Running IndexNow submission immediately after the build step. Cloudflare Pages may still be propagating assets to edge nodes. Crawlers notified by IndexNow may fetch stale content or 404s, damaging trust.
   • Fix: Decouple IndexNow from the build. Use a post-deploy workflow that triggers only after the deployment status is confirmed as live.

3. Silent ETL Failures

   • Explanation: The sitemap generates successfully, but the data source (e.g., Turso, API) returned empty results during the build. The sitemap has 200 OK but zero URLs.
   • Fix: Implement minimum URL count assertions in the sitemap validation script. If the count drops below a historical baseline, fail the check.

4. Verification File Exposure

   • Explanation: IndexNow requires a key file at a specific path. If a catch-all _redirects rule rewrites /* to /index.html, the key file becomes inaccessible, causing IndexNow to return 403.
   • Fix: Ensure verification paths are explicitly excluded from rewrite rules. Add a dedicated check in the validation script to fetch the key file and assert 200 OK.

5. Lighthouse Gatekeeping on Static Sites

   • Explanation: Blocking deploys when Lighthouse scores dip slightly (e.g., 94 to 88). Static sites can have score variance due to third-party resources or network jitter.
   • Fix: Treat Lighthouse as a monitoring tool, not a CI gate. Use trend analysis and alerting for significant regressions rather than hard thresholds.

6. Runtime Checks for SSG Architectures

   • Explanation: Adding uptime or API health checks to the post-deploy workflow for a static site. Since the site is pre-rendered HTML, runtime API availability does not affect the deployed assets.
   • Fix: Focus validation on asset integrity, CDN configuration, and SEO metadata. Remove runtime checks unless the site uses edge functions or dynamic rendering.

7. Key Rotation Neglect

   • Explanation: IndexNow keys may need rotation or regeneration. If the script uses a hardcoded key or an outdated secret, submissions fail silently or are rejected.
   • Fix: Store keys in CI/CD secrets. Validate the keyLocation URL returns the correct key content before submitting URLs.

Production Bundle

Action Checklist

• Add Sitemap Validation Script: Implement validate-sitemap.ts with redirect: 'manual' and URL count assertions.
• Configure IndexNow Secrets: Store API keys in repository secrets; ensure key files are deployed to /.well-known/.
• Decouple IndexNow Workflow: Create a separate GitHub Action for IndexNow that triggers post-deploy, not inline.
• Set Up Lighthouse Cron: Configure a weekly scheduled workflow with deep-path sampling and artifact storage.
• Review _redirects Rules: Audit all redirect rules to ensure they do not block sitemap or verification paths.
• Define Thresholds: Establish minimum URL counts per domain based on historical data.
• Test Failure Modes: Intentionally break a redirect rule in a staging environment to verify the validation script catches it.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-Volume SEO Site	Strict Sitemap Validation + Immediate IndexNow	SEO revenue depends on rapid indexing and crawlability. Failures must be caught instantly.	Low (Script execution)
Low-Traffic Static Blog	Weekly Lighthouse + Manual IndexNow	Automated IndexNow may be overkill; weekly checks suffice for trend monitoring.	Minimal
Dynamic/Edge Rendered Site	Add Runtime Health Checks	Unlike SSG, dynamic sites require API and function availability checks.	Moderate (API calls)
Pre-Production Staging	Full Validation Suite	Catch redirect and configuration errors before they reach production.	Low

Configuration Template

GitHub Actions: Post-Deploy Validation

name: Post-Deploy Validation
on:
  workflow_run:
    workflows: ["Deploy to Cloudflare Pages"]
    types:
      - completed

jobs:
  validate-sitemap:
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Run Sitemap Checks
        run: npx tsx scripts/validate-sitemap.ts

  trigger-indexnow:
    needs: validate-sitemap
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Submit to IndexNow
        env:
          INDEXNOW_KEY_A: ${{ secrets.INDEXNOW_KEY_AIAPPDEX }}
          INDEXNOW_KEY_B: ${{ secrets.INDEXNOW_KEY_FINDINDIEGAME }}
        run: npx tsx scripts/trigger-indexnow.ts

Quick Start Guide

1. Initialize Scripts: Create scripts/validate-sitemap.ts and scripts/trigger-indexnow.ts using the code examples above. Install xml2js for XML parsing.
2. Add Secrets: In your repository settings, add INDEXNOW_KEY_<DOMAIN> for each site. Ensure the corresponding key files are included in your static assets.
3. Configure Workflow: Add the Post-Deploy Validation workflow to .github/workflows/. Adjust the workflow_run trigger to match your deployment workflow name.
4. Set Thresholds: Update minUrlCount in validate-sitemap.ts based on your site's expected URL volume.
5. Test: Push a change that triggers a deploy. Verify the validation jobs run and pass. Intentionally introduce a redirect error to confirm the script fails as expected.