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:
- 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.
- 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.
- 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
- How to fix 'Page with redirect' in Google Search Console (and when you shouldn't)
- Should a broken external link fail your build? Comparing four CI policies, and the one I'd pick
- Should a broken link fail your CI build? Block internal links, warn on external ones
- How to check every URL in your sitemap.xml for 404s, redirect chains and timeouts (a Python script for CI)
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?
