A build-time validation gate: catching content errors before deploy

Every content catalog accumulates rot, and the insidious thing about it is that none of it announces itself. An image gets renamed in a refactor and ten old posts now point at a path that returns nothing. A route changes and the internal links that used to reach it quietly dead-end. A post ships with an empty description, a malformed date, or a missing field that does not crash the page but does break the share preview or the structured data. None of these errors throws an exception or takes the site down; the pages still load. They simply degrade, silently, and the only reliable discoverer of that degradation is a reader hitting a broken image or a dead link — which is the worst possible person to find it.

The fix is to stop relying on anyone going looking, and instead make the build itself the thing that looks. A build-time validation gate is an automated set of checks that runs over the entire catalog on every change and refuses to let a deploy through if anything is wrong. It converts a whole class of silent, run-time, reader-discovered problems into loud, build-time, author-discovered ones — caught by the person who caused them, at the moment they caused them, before any of it reaches production. This article is about what such a gate checks, why build time is the right time, and how to keep it useful rather than annoying as the catalog grows.

A useful gate does not try to check everything; it checks the specific, recurring, high-cost errors that a content catalog actually produces. Four classes cover most of the value. Missing assets: every image, illustration, or file a post references should actually exist at the path given, because a broken hero image is both ugly and invisible to the author who has it cached. Broken internal links: every link to another page on the site should resolve to a real route, because internal links are the connective tissue of a content site and a dead one wastes the reader and leaks the SEO value the link was meant to pass.

The other two are about correctness of the data rather than its references. Malformed or missing metadata: every post should have the fields it needs — a title, a valid date, a description of sane length, the keywords and the social metadata — because these are exactly the things that are invisible in normal reading and so ship broken most easily. And structured-data gaps: if the site emits JSON-LD for articles and FAQs, the gate can confirm each post has what that schema requires, so the structured data is correct by construction rather than spot-checked by hand. Each of these is a check that is cheap to write once and pays every time it catches something.

You could check these things at run time — verify links as pages render, warn about missing images in the console — but that is fundamentally the wrong moment, because at run time the error has already shipped. The reader is already looking at the broken thing; the best a run-time check can do is notice the failure as it happens to a real person. Build time is before the error reaches anyone. A check that runs as part of producing the deployable site can refuse to produce it, which means a broken link or a missing image is not a degraded live page but a build that did not happen. The error and its discovery move from production to the author’s own machine or the continuous-integration run, which is exactly where you want them.

This is the same logic as a type checker, extended from code to content, and it depends on the content being checkable in the first place — which is why storing posts as typed code, as described in /product-blog/content-as-code-a-blog-without-a-cms, is what makes a strong gate possible. When the whole catalog is data the build can iterate over, validating all of it on every change is just code, and the gate can be as thorough as you are willing to make it. The deeper point is about timing: the cost of an error scales with how late it is caught, and build time is the earliest practical moment to catch a content error, which makes it the cheapest.

A validation gate is only as good as the failures it produces, and a gate that fails with a vague “validation error” is almost worse than none, because it blocks the deploy without telling anyone how to unblock it, and people quickly come to resent and route around it. The discipline is to make every failure specific: name the post, name the field or the link or the asset, say exactly what is wrong, and ideally say what was expected. “Post ‘code-splitting-a-large-web-app’ references image /blog/missing.svg which does not exist” is a failure someone can fix in thirty seconds. “Validation failed” is a failure someone has to investigate, and an investigation is exactly the friction the gate was supposed to remove.

Speed matters alongside specificity, because a gate that takes several minutes to run will be skipped under deadline pressure, and a skipped gate protects nothing. The checks should be fast enough to run on every change without anyone resenting the wait — and most content checks are inherently cheap, since they are reading data and confirming references rather than doing heavy computation. The combination of fast and specific is what makes a gate something people trust and lean on rather than fight: it tells them precisely what is wrong, immediately, so fixing it is a quick correction rather than a chore. A gate that is pleasant to satisfy gets satisfied; a gate that is painful gets disabled.

A gate needs to run in the right places to actually protect anything, and there are two that matter. The first is locally, as part of the normal build, so an author working on content sees a problem the moment they introduce it rather than later — the tightest possible feedback loop, where the person who broke something is told immediately while the change is still fresh in their mind. The second is in continuous integration, on every proposed change before it can merge, as the backstop: even if someone skips the local check or works in a way that bypasses it, the gate runs in CI and a change that fails cannot reach production. The two together mean a content error has to get past both the author and the automation to ship, which it essentially never does.

This placement is why the gate composes so well with everything else in a content-as-code setup. It runs through the same build that compiles the app, on the same changes reviewed in the same pull requests, with the same all-or-nothing deploy semantics. There is no separate content-validation service to run and keep in sync, because the validation is just part of producing the site. It also automates a meaningful chunk of the launch checks described in /product-blog/a-go-live-runbook-for-a-serverless-app — the “every page has metadata, every route is in the sitemap” class of check stops being something a human verifies on launch day and becomes something the gate enforces continuously, which is a far more reliable arrangement than a list worked from memory.

A validation gate is not a thing you build once and forget; it is a thing you grow as you learn what actually breaks. The right way to expand it is reactively and specifically: every time a content error does slip through to production — and some will, especially early — the fix is not only to correct that one error but to add the check that would have caught it, so that class of mistake can never ship again. Over time this ratchets the catalog toward reliability, because each real failure permanently closes the door behind it. The gate becomes a record of every kind of content mistake the team has ever made and resolved never to repeat, which is a genuinely powerful thing to accumulate.

The discipline is to keep the checks aligned with real failures rather than imagined ones, because a gate stuffed with speculative rules that have never caught anything is just friction that slows everyone down and tempts people to bypass it. Every check should earn its place by corresponding to a mistake that actually happens, which keeps the gate lean, fast, and trusted. Done this way, a build-time validation gate is one of the highest-leverage pieces of automation a content site can have: a small, growing set of cheap checks that quietly guarantees the whole catalog stays coherent, so that a few hundred posts — and then a few thousand — never quietly rot, because the build will not let them. The reader only ever sees the posts that passed.