Linkbruno

Checking broken links in CI and on preview deploys

Updated 27 October 20269 min read

Check your site

Up to 25 pages and every link on them. No signup.

On this page
  1. What your build already checks
  2. Check the built HTML with lychee
  3. What should fail the pull request
  4. Check the deployed preview
  5. After the merge

To check broken links in CI, use two layers. First, turn on the link check your site generator already has, so a missing internal page fails the build. Second, run a link checker over the built HTML or the deployed preview, which catches anchors, redirects and content the generator never sees. Fail the pull request on internal breaks, report external ones without blocking, and keep a scheduled check of production, because outbound links rot without anyone opening a pull request.

What your build already checks

Docusaurus

Docusaurus checks internal links during a production build. As of version 3.10 (Docusaurus config docs):

Option Default What it covers
onBrokenLinks throw Links to routes that don't exist. Detection is "only available for a production build (docusaurus build)", so npm start won't show them
onBrokenAnchors warn Anchors declared with Docusaurus's Heading component
markdown.hooks.onBrokenMarkdownLinks warn Markdown links to files that don't exist. Replaces the top-level onBrokenMarkdownLinks, deprecated in 3.9 and due to be removed in v4
markdown.hooks.onBrokenMarkdownImages throw Markdown images that don't exist

Two of those only warn, and warnings scroll past in CI logs. Make them fail:

// docusaurus.config.js (only the relevant keys)
export default {
  // title, url, baseUrl, presets...
  onBrokenLinks: 'throw',
  onBrokenAnchors: 'throw',
  markdown: {
    hooks: {
      onBrokenMarkdownLinks: 'throw',
    },
  },
};

The check never looks at external URLs. Docusaurus only collects links that its Link component renders as internal routes; anything pointing at another site is rendered as a plain <a> and skipped (Link.tsx source).

Hugo

Hugo checks links written with the ref and relref shortcodes, such as [Install]({{% ref "/docs/install" %}}). When it can't resolve the page, it logs an error and the build fails, because refLinksErrorLevel defaults to ERROR. You can lower it to WARNING and set refLinksNotFoundURL as a stand-in address (Hugo configuration).

Plain Markdown links like [Install](/docs/install/) aren't checked. Hugo's docs now call the ref shortcode obsolete for Markdown and recommend the embedded link render hook, which "will not throw an error or warning if unable to resolve a destination" (Hugo ref docs, link render hooks). If you follow that advice, you lose the build-time check, so the next layer matters more.

What build checks miss

  • External links, every one of them.
  • Content the generator never sees: anything fetched at runtime from a headless CMS or API, embeds, and links added by client-side JavaScript.
  • Your server's behavior: redirect rules in vercel.json or _redirects, trailing-slash handling, rewrites. A link to /old-page that only works through a redirect looks broken to the build, and a redirect that points at a deleted page looks fine.

Check the built HTML with lychee

lychee reads the HTML your build produced and checks every link in it, including #anchors on your own pages. The workflow below runs on every pull request and once a week. It builds a Docusaurus site into build/; for Hugo, swap in your Hugo build steps and use public instead.

# .github/workflows/links.yml
name: Links

on:
  pull_request:
  schedule:
    - cron: "0 6 * * 1"
  workflow_dispatch:

jobs:
  links:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
      - run: npm ci
      - run: npm run build

      - name: Restore lychee cache
        id: restore-cache
        uses: actions/cache/restore@v6
        with:
          path: .lycheecache
          key: lychee-${{ github.run_id }}
          restore-keys: lychee-

      - name: All links, report only
        id: all-links
        uses: lycheeverse/lychee-action@v2.9.0
        with:
          args: >-
            --no-progress
            --cache
            --max-cache-age 1d
            --root-dir ${{ github.workspace }}/build
            --index-files index.html
            --fallback-extensions html
            'build/**/*.html'
          fail: false

      - name: Save lychee cache
        if: always()
        uses: actions/cache/save@v6
        with:
          path: .lycheecache
          key: ${{ steps.restore-cache.outputs.cache-primary-key }}

      - name: Open an issue on scheduled runs
        if: github.event_name == 'schedule' && steps.all-links.outputs.exit_code != 0
        uses: peter-evans/create-issue-from-file@v6
        with:
          title: Link Checker Report
          content-filepath: ./lychee/out.md
          labels: report, automated issue

      - name: Internal links and anchors, fails the job
        uses: lycheeverse/lychee-action@v2.9.0
        with:
          args: >-
            --no-progress
            --offline
            --include-fragments=anchor-only
            --root-dir ${{ github.workspace }}/build
            --index-files index.html
            --fallback-extensions html
            'build/**/*.html'
          output: lychee/internal.md

What each part does:

  • The first lychee step checks everything, external links included, with fail: false, so problems land in the job summary without blocking the merge. The action writes a job summary by default (action.yml).
  • The last step uses --offline, which limits lychee to local files, and --include-fragments=anchor-only, which checks #section links against the ids in your pages. The action's fail input defaults to true, so a missing page or anchor fails the job.
  • --root-dir maps absolute links like /docs/intro onto the build folder (it must be an absolute path). --index-files index.html resolves /docs/intro to docs/intro/index.html, and --fallback-extensions html covers sites that write intro.html instead (lychee options). If your site is served from a subpath, absolute links won't line up with the folder and you'll need lychee's remap option.
  • The cache is split into restore and save steps so it's saved even when the job fails, the approach the lychee-action README suggests. Keying on run_id stores a fresh cache every run, and restore-keys loads the most recent one. With --max-cache-age 1d, a link checked in the last day isn't requested again, which keeps repeated pushes to a pull request from hitting the same external sites every few minutes.
  • On the weekly run, failures open a "Link Checker Report" issue. create-issue-from-file opens a new issue each time; pass its issue-number input to update one issue instead.

Before you rely on it, break a link on purpose in a test branch and watch the job fail.

Settings for external sites

Put shared settings in lychee.toml at the repository root. lychee reads that file from its working directory by default:

# lychee.toml
max_retries = 3
retry_wait_time = 5
timeout = 20
host_concurrency = 2
cache_exclude_status = "429, 500.."
exclude = [
  '^https?://([a-z]+\.)?linkedin\.com/',
]

host_concurrency = 2 keeps lychee to two requests at a time per host, down from a default of 10. cache_exclude_status stops rate-limit and server errors from being cached, so they're retried on the next run instead of being reported again from the cache. The exclude line is for LinkedIn, which answers automated requests with a non-standard 999 status. Without it, every report fills with lines like [999] <https://www.linkedin.com/in/...> | Rejected status code: 999 Unknown status code, repeated once for every page that carries the link. The LinkedIn 999 guide explains why, and why link checkers report 403 and 429 covers the other hosts that block checkers.

Use exclude for hosts that always block you and accept for status codes you've decided are fine. If you set accept, include the normal range, because it replaces lychee's default of 100..=103,200..=299.

What should fail the pull request

What broke On a pull request On the weekly run
Link to a page that isn't in the build Fail Fail
Link to a missing #anchor on your site Fail Fail
External 404, 410 or DNS failure Report, don't block Open an issue
External 403, 429, 999 or timeout Report, don't block Check by hand

Internal links are the author's responsibility, they're cheap to fix in the same pull request, and the result doesn't depend on anyone else's server. External links break on someone else's schedule. If a pull request that fixes a typo fails because a site you cited in 2019 went down, people learn to re-run the job until it passes, and the gate stops meaning anything.

Check the deployed preview

The build output isn't quite the site your readers get. A preview deploy has your real redirects, rewrites, trailing-slash rules and headers. Checking it catches redirect rules that point at nothing, and it passes links that work only through a redirect, which a build check reports as broken. To test a few redirects by hand, paste the old URLs into the redirect checker.

Get the preview URL

  • Vercel: by default it reports deployments to GitHub as deployment_status events (Vercel for GitHub). Run on that event, keep only github.event.deployment_status.state == 'success', and read the URL from github.event.deployment_status.environment_url. Vercel also sends repository_dispatch events such as vercel.deployment.success, with the URL in github.event.client_payload.url, but those only trigger workflows that exist on the default branch.
  • Netlify: the preview for pull request 42 lives at https://deploy-preview-42--<site-name>.netlify.app, and it returns "Not Found" until the first deploy finishes (Netlify docs). You can poll it until it answers 200. On later pushes the same URL keeps serving the previous deploy until the new one is ready, so a simple poll can check stale content.

Get past deployment protection

If Vercel Deployment Protection covers your previews, a checker gets a login page instead of your site. Create a Protection Bypass for Automation secret in the project settings and send it in the x-vercel-protection-bypass header (Vercel docs).

Be careful where that header goes. lychee's docs say custom headers set with --header "are used for ALL requests", so a crawl that also checks external links would send your bypass secret to every site you link to. Limit the preview crawl to the preview's own host.

Crawl it

lychee checks the links on the pages you give it but doesn't follow them to discover more pages; its own feature table lists recursion as unsupported (lychee README). For a deployed preview you need a crawler. linkinator can do it with --recurse:

# .github/workflows/preview-links.yml
name: Preview links

on: deployment_status

jobs:
  preview-links:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/setup-node@v7
        with:
          node-version: 24
      - name: Crawl the preview
        env:
          PREVIEW_URL: ${{ github.event.deployment_status.environment_url }}
          BYPASS: ${{ secrets.VERCEL_AUTOMATION_BYPASS_SECRET }}
        run: |
          npx --yes linkinator@8 "$PREVIEW_URL" \
            --recurse \
            --skip "^(?!${PREVIEW_URL})" \
            --header "x-vercel-protection-bypass:${BYPASS}"

The --skip pattern skips every URL that doesn't start with the preview address, so the crawl stays on your preview and the bypass header never leaves it. External links are left to the scheduled lychee run. linkinator exits with an error when it finds broken links, which fails the job, and --redirects warn makes it list links that go through a redirect so you can point them at the final URL (linkinator README). Save the secret in GitHub as VERCEL_AUTOMATION_BYPASS_SECRET, or drop the --header line if your previews are public. The event also fires for production deploys, which just means production gets checked too.

If you make this job a required check, test what happens when a pull request doesn't deploy. Vercel users report that when a build is skipped by the Ignored Build Step, the workflow never runs and the required check waits indefinitely (Vercel Community).

Linkbruno's CI check takes the hosted route: an API token and a shell script that checks the preview URL, up to 2,000 pages, and fails the job when the preview has broken links, apart from any you've marked as intentional. Links on the preview to your live site by full address are checked on the preview, which lychee needs --remap for, so a page added in the same pull request doesn't fail before it's live. On GitHub Actions the script also annotates the run and writes the results to its job summary. Like lychee and linkinator, it reads the HTML as served and doesn't run JavaScript.

After the merge

CI only sees links when someone changes the site. Outbound links break on their own: Pew found that 38% of pages that existed in 2013 were gone a decade later (Pew Research, 2024). Keep a scheduled check of production running alongside the pull request gate, either the weekly job above or a monitoring service that crawls the live site and alerts when something changes. If an AI coding agent works in the repository, the MCP server hands it that list so it can fix the links and check them again. The external links guide covers what to do with each dead outbound link, and link rot covers a monthly routine. For the full range of ways to find broken links, including one-off checks, see how to find broken links on a website.

See what’s broken on your site

The free scan reads up to 25 pages and checks every link on them. No signup.

Related