SEO Validator: A Deploy Gate for SEO Regressions

Deploy-gate SEO validation runs an SEO audit inside the build pipeline, with a non-zero exit code blocking release and triggering rollback to the previous build. The pattern moves SEO from an overnight monitoring concern to a release-blocking check. This article describes the open-source SEO Validator that implements it, the nginx-config-driven audits that make it different from existing tools, and the build.sh wiring that turns it into a true deploy gate.

By William Murray, Founder of SpeyTech: deterministic computing for safety-critical systems. Inverness, Scottish Highlands.

A Failure Mode That Most SEO Tools Cannot Catch

Yesterday I renamed five SVG assets on speytech.com to match their article slugs. One example: cardiocore-litigation.svg became implantable-device-litigation.svg. The new file shipped. The nginx redirect from the old path to the new one shipped too. If I had missed a file-permission step on any of the new assets, the redirect target would have served a 404. The old URL would still have looked correct in any SEO tool that only checked URLs it was given. Googlebot would have found the broken target before I did.

Traditional SEO audit tools work by following links from a sitemap or seed URL. They check what the site exposes. They cannot check what the nginx config promises to serve, because they have no view into the config. If a redirect target is broken but no page links to it, the audit reports a clean site. The companion problem on the same site is documented in operational SEO observability: a 6.83-Googlebot-requests-per-day baseline that was invisible to Lighthouse, Search Console summaries, and synthetic monitors, but obvious in the nginx access log. The deploy gate prevents regressions before they ship; the log analyser surfaces what shipped behaviour actually looks like once it is live. Both belong in the same operational toolbox.

The SEO Validator described here closes that gap. It reads /etc/nginx/sites-available/<domain> directly, discovers every exact-match redirect rule, and verifies each one resolves to a live target. And it runs inside build.sh, not as an overnight job, so a regression fails the build before the change reaches production.

What Deploy-Gate SEO Validation Means

The distinction matters. Most SEO tools are inspection tools: Screaming Frog, Sitebulb, Ahrefs, Semrush. They run on a schedule, produce a report, and surface issues for a human to triage. By the time the human reads the report, the regression has been live for hours.

A deploy gate runs at the moment of release. It either passes, and the build goes live, or it fails, and the build does not go live. There is no window between “broken build deployed” and “human notices report tomorrow.” The window is closed by design.

This article is not arguing that deploy-gate validation replaces inspection tools. Inspection tools cover surface area a deploy gate cannot: historical trend analysis, competitor tracking, backlink graphs, content scoring. The two are complementary. For the specific class of regressions that occur at release time, a deploy gate is the right control.

The deploy gate eliminates the gap between regression introduction and detection.

What the Validator Audits

The validator runs 22 audit sections, grouped by concern. The grouping matters more than the individual section count, because each group represents a class of failure with its own detection strategy.

Document integrity (sections 2–8) covers status codes, title and description lengths, meta robots directives, Open Graph completeness, viewport tags, favicon presence, and heading hierarchy. These are the standard surface-level checks any SEO audit runs. Section 5 additionally verifies every og:image URL returns HTTP 200, which catches social-card breakage that pure-HTML audits miss.

Accessibility and canonicalisation (sections 9–11) covers image alt-text coverage, canonical tag correctness on a random page sample, and a full trailing-slash redirect audit. The trailing-slash audit catches Google Search Console “Alternate page with proper canonical tag” warnings before they appear in GSC, by verifying every URL-without-slash returns a 301 to the URL-with-slash on the same path.

Behavioural correctness (sections 12–17) covers redirect chain detection, duplicate title and description detection, mixed-content scanning, and soft-404 detection. Sections 16–17 (broken link and orphan page detection) are gated behind --thorough because they are crawl-intensive; the default mode skips them.

Infrastructure discoverability (sections 18–19) verifies that robots.txt, llms.txt, llms-full.txt, and the JSON-LD schema blocks resolve and parse. The llms.txt checks are AEO-specific; not every audit tool covers them.

Nginx-config-driven verification (sections 20–22) is the differentiator. Section 20 audits image-asset redirects discovered from the nginx config. Section 21 verifies the full redirect set, including 410 Gone rules. Section 22 audits for orphan image assets: SVG files that exist in the dist tree but no page references and no redirect points at.

The 22 sections produce structured terminal output with exit-code-driven success or failure. Every section that catches a regression flags it and contributes to a non-zero exit code.

How the Validator Plugs Into build.sh

The validator is wired into the speytech.com deploy pipeline as a post-swap gate. The relevant shape of build.sh:

#!/bin/bash
set -e
trap 'echo "Build interrupted"; exit 1' INT TERM

# 1. Content-level checks against markdown source
node scripts/aeo_lint.js || exit 1

# 2. Build into a staging directory + static search index
rm -rf dist.new .astro
npx astro build --outDir ./dist.new
npx pagefind --site dist.new

# 3. Fix ownership on the staged build
sudo chown -R www-data:www-data dist.new

# 4. Atomic swap: dist.new becomes the live tree in one rename(2) call
if [ -d dist ]; then
    sudo mv dist dist.old
fi
sudo mv dist.new dist

# 5. Deploy-gate SEO validation against the now-live site
if ! python3 scripts/seo_validator.py --domain speytech.com; then
    echo "Validation failed. Rolling back."
    if [ -d dist.old ]; then
        sudo mv dist dist.failed
        sudo mv dist.old dist
        exit 1
    fi
    exit 1
fi

# 6. Success path
sudo python3 scripts/notify_indexnow.py || true
sudo rm -rf dist.old &
git add -A
git commit -m "Build: $(date '+%Y-%m-%d %H:%M')" || echo "Nothing to commit"
git push

Three details in that flow matter.

First, the atomic swap is a single rename(2) syscall on the same filesystem. mv of a directory over another existing directory on the same filesystem translates to one rename(2) call: instantaneous, with no intermediate state visible to nginx. Requests in flight either complete against the old dist or land on the new one. There is no window where the live tree is missing, partial, or half-permitted. The earlier pattern of rm -rf dist && npm run build leaves dist empty for 30 seconds to two minutes, which is long enough for Googlebot to hit a 404 on robots.txt and back off crawling for days. The atomic swap closes that window.

Second, the validator is invoked as if ! python3 ..., which honours its exit code directly. Piping the output through tee or grep would break this: the pipe consumes the validator’s exit status and replaces it with the exit status of the last command in the pipeline. The standard fix is set -o pipefail and ${PIPESTATUS[0]}, but the simpler discipline is to avoid piping a deploy-gate command. To capture both the exit code and the log, write the output to a file and check $? separately, or use PIPESTATUS explicitly.

Third, the IndexNow ping is suffixed with || true. A failure to notify a search engine should not roll back a deploy that has already passed validation. The rollback path is reserved for things that genuinely make the site worse than the previous build; a missed ping is recoverable on the next deploy. Distinguishing recoverable side-effects from validation failures keeps the rollback path narrow and the gate trustworthy.

The default invocation runs in sampling mode (a 20-URL subset of trailing-slash and redirect-chain checks) so the gate stays fast on every deploy. Adding --full exhaustively checks every URL and is appropriate before a major release or as a nightly cron job rather than on every push.

The deploy gate runs after the atomic swap, against the live site, and rolls back on any non-zero exit.

What Section 20 Does: Image-Asset Redirect Verification

Section 20 reads the nginx config, extracts every location = /images/old.svg { return 301 /images/new.svg; } rule, fetches each old URL, and verifies the redirect target returns HTTP 200.

The rules are extracted with a single regex applied to the config file:

location\s*=\s*(\S+)\s*\{\s*return\s+(301|302|303|307|308)\s+(\S+?)\s*;\s*\}

The validator pulls source path, status code, and target path. For each rule where the source path has an image extension, it issues a request, follows the redirect, and checks the final response.

The output from a recent speytech.com run, after yesterday’s image-rename work:

=== 20. Image-Asset Redirect Audit ===
Discovered 5 image redirect rule(s) from /etc/nginx/sites-available/speytech.com. Verifying...
✓ /images/cardiocore-litigation.svg -> 301 -> /images/implantable-device-litigation.svg -> 200
✓ /images/hash-chain-diagram.svg -> 301 -> /images/cryptographic-proof-execution.svg -> 200
✓ /images/mycoeco-architecture.svg -> 301 -> /images/mycoeco-kernel.svg -> 200
✓ /images/nvidia-asil-comparison.svg -> 301 -> /images/nvidia-asil-determinism.svg -> 200
✓ /images/semantic-security-hero.svg -> 301 -> /images/semantic-security-monitoring.svg -> 200

Image-asset redirect summary: 0 issues found

Without section 20: five rename operations require five hand-tested URLs after deploy. Either the operator forgets one, or the test is shallow (HEAD only, no status check on the redirected target). The failure mode is silent: Googlebot finds the broken target before the operator does.

With section 20: every rule is verified empirically on every deploy. The discipline is automatic rather than manual.

What Section 21 Does: Full Redirect Set Verification

Section 21 generalises section 20 to every exact-match redirect in the nginx config, not just image redirects. Path consolidations, RSS feed redirects, sitemap aliases, and 410 Gone rules are all verified together.

The speytech.com run on 14 May 2026 reported:

=== 21. Redirect Set Verification ===
Discovered 17 exact-match redirect rule(s) from /etc/nginx/sites-available/speytech.com. Verifying...
✓ /contact-us/ -> 301 -> /contact/ -> 200
✓ /data-policy/ -> 301 -> /privacy/ -> 200
✓ /mdcp-vs-alternatives/ -> 301 -> /insights/mdcp-vs-conventional-rtos/ -> 200
✓ /sitemap.xml -> 301 -> /sitemap-index.xml -> 200
✓ /feed/ -> 301 -> /rss.xml -> 200
✓ /feed -> 301 -> /rss.xml -> 200
✓ /rss/ -> 301 -> /rss.xml -> 200
✓ /atom/ -> 301 -> /rss.xml -> 200
✓ /atom.xml -> 301 -> /rss.xml -> 200
✓ /index.xml -> 301 -> /rss.xml -> 200
✓ /home-temp/ -> 410
... (rules omitted for brevity)

Redirect set summary: 0 issues found

The /home-temp/ -> 410 line shows the validator handling 410 Gone correctly. A 410 response is a deliberate “this resource is permanently removed” signal, different from 404 which means “we have no idea.” Search engines treat the two differently for crawl-budget allocation. A misconfigured 410 rule that accidentally returns 404 (because the return 410; directive was removed during a config edit) would degrade indexing quietly. Section 21 catches that.

Section 21 verifies every exact-match redirect resolves correctly, including 410 Gone responses for deliberately deleted paths.

What Section 22 Does: Orphan Image Detection

Section 22 walks the dist tree under each configured image directory (default images/ and og/), collects every image file on disk, then builds a reference set from rendered HTML, og:image tags, favicon links, and redirect targets. Files on disk minus files referenced equals the orphan set.

=== 22. Orphan Image Audit ===
Walked dist/images/ (66 assets), dist/og/ (70 assets).
136 image asset(s) total, 136 referenced from rendered HTML, og:image tags, favicon links, or redirect targets.

Orphan image summary: 0 issues found

Orphan detection surfaces two different kinds of finding. The first is dead weight: assets generated for an article that was later removed, or experimental SVGs left behind during design iteration. These cost deploy time and bandwidth but do not cause user-visible failures.

The second is more valuable: assets created for an article whose markdown does not yet reference them. A hero SVG sitting orphaned in dist/images/ often means the matching article is missing its <img> tag, an operational signal that something was forgotten during writing.

On an earlier speytech.com run, section 22 surfaced six SVG files that no article referenced. Investigation showed they were intended-but-unwired hero images for articles still in draft. Adding the references was a small content improvement; without the audit, the omissions would have stayed invisible.

Section 22 turns “an asset exists on disk” into “an asset exists on disk and is reachable from somewhere a crawler will see.”

Why Pipe-Based Logging Breaks the Gate

The deploy-gate pattern depends on the validator’s exit code propagating into build.sh. A common mistake is to pipe the validator output to tee or grep:

# WRONG: exit code is replaced by tee's exit code
python3 scripts/seo_validator.py --domain x.com --full | tee validator.log
# WRONG: exit code is replaced by grep's exit code
python3 scripts/seo_validator.py --domain x.com --full | grep -v "^\\s*$"

Both forms appear to “work” because the output looks right. They silently break the gate. tee returns 0 on a successful write regardless of what its stdin produced; grep returns 0 if it matched at least one line. The validator’s non-zero exit on failure is discarded.

The correct shapes:

# Direct invocation: exit code propagates cleanly
if ! python3 scripts/seo_validator.py --domain x.com --full; then
    rollback
fi

# Log to file and check exit code separately
python3 scripts/seo_validator.py --domain x.com --full > validator.log 2>&1
status=$?
cat validator.log
if [ "$status" -ne 0 ]; then
    rollback
fi

# Pipe + PIPESTATUS (works but easy to forget)
set -o pipefail
python3 scripts/seo_validator.py --domain x.com --full | tee validator.log
if [ "${PIPESTATUS[0]}" -ne 0 ]; then
    rollback
fi

Test the failure path before trusting the gate. Move a redirect target out of the way temporarily, run a deploy, and confirm the build fails and dist.old is restored. A gate that has only ever seen the success path is not a gate.

How Deploy-Gate Validation Compares to Inspection Tools

The two tool categories solve different problems. Inspection tools answer “what is the current state of my SEO surface?”: a question that benefits from breadth, history, and external data sources. Deploy gates answer “did this specific change introduce a regression?”: a question that benefits from speed, narrowness, and exit-code propagation.

Suggesting the validator as a replacement for Ahrefs or Sitebulb misunderstands what it is for. It is a focused tool that closes a specific control gap in CI/CD pipelines, not a comprehensive SEO platform.

A deploy gate and an inspection tool address different points on the regression-detection timeline.

What the Validator Deliberately Is Not

The validator’s restraint is part of the design. Several capabilities are intentionally absent.

Not a crawler. The validator uses the site’s sitemap as the source of truth for URL discovery, not link-following from a seed URL. This is faster and produces deterministic runs (every build audits the same URLs) but it will not catch pages that exist on the server but are not in the sitemap. If sitemap completeness is suspect, a crawl-based tool covers that gap.

Not a performance auditor. No Lighthouse score, no Core Web Vitals, no resource-size analysis, no JavaScript-execution profiling. Performance is a different tool category with different latency and infrastructure requirements; folding it into a deploy gate would slow every release without serving the gate’s purpose.

Not a content auditor. No readability scoring, no keyword density, no semantic analysis. On speytech.com, content concerns are handled by a separate AEO lint that runs earlier in build.sh against the markdown source files, not against rendered HTML. Separating content audits from rendered-site audits keeps each tool’s responsibility clear.

Not a SaaS. The validator runs locally as part of CI/build. No web UI, no API, no dashboards, no hosted service. Output is structured text suitable for both human reading and exit-code-driven automation. The decision to ship as a Python script under MIT rather than a SaaS product was deliberate: deploy gates belong inside the pipeline, not behind an API call to someone else’s infrastructure.

Frequently Asked Questions

What is deploy-gate SEO validation?

Deploy-gate SEO validation runs an SEO audit inside the build pipeline, with a non-zero exit code blocking release and triggering rollback to the previous build. The pattern moves SEO from an overnight monitoring concern to a release-blocking check. It complements rather than replaces inspection tools.

How do I integrate the validator into my build pipeline?

Run the validator after your atomic deploy step inside build.sh, using if ! python3 seo_validator.py ... to honour the exit code. On non-zero exit, restore the previous build by renaming dist.old back to dist. The validator needs the live site to be reachable at the domain you pass; run it after the swap, not before.

Why doesn’t a periodic SEO crawler catch the same regressions?

A periodic SEO crawler runs after deploy and reports tomorrow. By then, broken redirects have been live for hours, Googlebot has indexed the bad responses, and the operator is reacting to historical damage rather than preventing it. Deploy-gate validation closes the gap by checking at release time.

What does an nginx-config-driven audit catch that a sitemap crawl misses?

An nginx-config-driven audit catches broken redirect targets, missing 410 Gone responses, and orphan image assets: failures that exist outside the sitemap and link graph. A sitemap crawler only checks URLs the site exposes through its own pages; redirect rules and removed-resource declarations live in the nginx config, invisible to crawlers.

What are the limitations of using only a deploy gate for SEO?

A deploy gate covers regression prevention at release time but not historical trend analysis, competitor tracking, backlink graphs, or content scoring. Inspection tools like Screaming Frog or Sitebulb handle those concerns better. The two tool categories are complementary; treating the gate as a complete SEO programme would leave material surface uncovered.

How do I avoid silently breaking the gate?

Invoke the validator directly in an if statement rather than piping its output through tee or grep. Piping replaces the validator’s exit code with the pipe-terminator’s exit code, which is almost always zero on a successful write. The validator’s non-zero exit on failure is discarded, and the gate becomes a no-op that always passes.

Try It Yourself

The validator is open-source under MIT, the most permissive licence available: an explicit choice to make the tool widely adoptable inside private CI pipelines without licence friction.

Repository: github.com/SpeyTech/seo-validator

Dependencies: Python 3.8+, requests, beautifulsoup4, lxml

Quick start:

git clone https://github.com/SpeyTech/seo-validator
cd seo-validator
pip install -r requirements.txt
./seo_validator.py --domain example.com --full \
    --nginx-config /etc/nginx/sites-available/example.com \
    --dist-path /var/www/example.com/dist

The --nginx-config and --dist-path arguments are optional. Without them, sections 20–22 fall back to an inline redirect list and skip the dist walk. With them, the full deploy-gate behaviour activates.

Issues, feature suggestions, and pull requests are welcome through GitHub. Particular interest in: extending the nginx-config parser to handle additional rule shapes (regex-match locations, map-based redirects), and adding support for Caddy and Apache config formats.

Closing

Deploy-gate SEO validation closes the regression-detection window from hours-to-days down to zero, by failing the build instead of filing a report. The trade-off is that the gate covers a narrower surface than a full inspection tool. The gate answers “did this change break something?” rather than “what is the current state of my SEO surface?”, so the two tool categories should be run together, not interchangeably.

As with any architectural approach, suitability depends on system requirements, risk classification, and regulatory context.