DEV Community

linkbruno.com
linkbruno.com

Posted on

Should your link checker run against production or the preview deploy? Let's argue about it

Scheduled broken-link and redirect checks that tell you the moment a link breaks — linkbruno.com

Most teams that check links automatically end up choosing, often without realising it, between two places to run the checker:

  • The preview deploy (or the build output), on every pull request, before the change ships.
  • Production, on a schedule, after it ships.

Running both is the textbook answer. In practice a lot of teams pick one, usually whichever was easiest to set up, and the choice determines which kinds of broken links they'll ever find. So let's argue about which one deserves to be the default.

The case for the preview deploy

It stops broken links before anyone sees them. A checker that runs on the pull request blocks the merge, and the person who broke the link is the one who fixes it, while the change is fresh in their mind. That's the cheapest moment in a link's life to fix it.

It's attributable. When a PR check fails, you know exactly which change caused it. When a production check fails, someone has to work out which of the last forty deploys, CMS edits or upstream changes broke it.

It tests what you control. Most of the links a team can actually fix are internal: navigation, cross-references between docs pages, image paths, anchors. Those break because of code and content changes, which all go through pull requests.

It's quieter. On a PR you can check only the changed pages, which is fast and rarely flaky. A full production crawl hits every external site you've ever linked to, and some of them will be down, slow or rate limiting you on any given day.

The case for production

Production is what users see. A preview deploy is not production. It may have different environment variables, a different CDN configuration, no redirects file, different authentication, or a different base URL. Links that work on pr-123.preview.example.app can break on example.com, and vice versa.

Links rot without any change on your side. External pages move or disappear. Third-party docs reorganise. A partner's domain expires. None of this goes through your pull requests, so a PR-only checker will never see it. On an older site, this is most of the broken links.

Content often bypasses pull requests. Pages edited in a CMS, product data imported from another system, and user-generated content can all break links without a PR ever being opened.

Redirects and caching only exist in production. The redirect rules, CDN edge behaviour and cached old HTML that cause some of the most confusing broken links are often only fully configured on the production domain.

Where I've landed

If I could run only one, I'd pick production, on a schedule, for any site older than a few months. The share of broken links that come from rot and from non-PR changes grows every year a site exists, and a PR check can't see any of them.

But the honest answer is that they find different bugs, and the setup that works is a split:

  1. Preview or build output, on every PR: internal links only. Fast, strict, blocks the merge. Internal links, anchors and images. External links in changed files as warnings, not failures.
  2. Production, weekly or daily: everything. Full crawl, external links included, reported as an issue or a ticket rather than a red build. Nobody's PR should fail because a site they didn't touch went down.
  3. Production, right after each deploy: a short smoke list. The 20 to 50 URLs that matter most (pricing, sign-up, docs landing pages, top-traffic articles), checked within minutes of a release, so configuration differences between preview and production show up immediately.

The scheduled production crawl is the part people skip because it's not part of any pipeline. A hosted checker like linkbruno.com or a cron-triggered workflow both work; what matters is that someone gets the report.

Need both the preview check and a production safety net? linkbruno.com can watch the live site on a schedule, so a link that only breaks in production still gets caught.

What the split looks like in practice

For a typical docs site on GitHub Actions, the split is three small workflows. The pull request workflow builds the site and runs a link checker on the build output, internal links only, failing on any error. The post-deploy workflow runs on the deployment_status event, waits for the production URL to answer, and checks a short list of key URLs. The scheduled workflow runs every Monday, crawls production including external links, and opens or updates a single issue with the results instead of failing anything. Each one takes minutes to set up, and together they cover both the links you break and the links that break on their own.

The cases I'm unsure about

  • Docs sites with versioned content. Should the PR check also crawl older versions, which nobody changes but which link to pages that do?
  • Preview deploys behind authentication. If the preview needs a login, is it worth giving the checker credentials, or is checking the static build output close enough?
  • Strictness for external links on PRs. Warning only is quieter, but warnings get ignored. Failing the PR on a new external link that's broken (only new ones, not existing ones) seems like a reasonable middle ground. Has anyone run that for long?

A quick self-test

Take the last five broken links your team found. For each one, ask: would a PR check have caught it, or only a production check?

If they're mostly the first kind, you've got a PR check problem. If they're mostly the second kind, a PR-only setup is missing most of what breaks.

Related reading

So where does your link checker run: on preview deploys, on production, or both? And which one has actually found more of your broken links?

Top comments (0)