How to Automate Website and Markdown Link Checks in CI/CD

In a modern development environment, documentation is code. Just as you wouldn't merge code without running tests, you shouldn't publish documentation without verifying its integrity. Automating link checks ensures your "Link Health" stays at 100% without manual labor.

The goal is not to fail every pipeline on every flaky external URL. A good CI link-check setup separates critical internal regressions from slower-moving external degradation so teams can keep shipping without normalizing broken docs.

Why CI Link Checks Matter

Regression Testing: Catch links that break when you move files around.
External Monitor: Discover when a site you link to goes offline.
Developer Confidence: Know that your docs are always production-ready.

Recommended Policy for Mature Teams

Fail fast on internal links: broken README paths, docs pages, and anchor jumps should block merge.
Warn on unstable externals: 403, 429, and temporary 5xx responses are often not code regressions.
Run scheduled audits: weekly or daily jobs catch older outbound links that decay over time.
Scope checks to changed files first: faster feedback beats expensive full-repo scans on every commit.

Implementation: GitHub README Link Checker Job

The easiest way to start is with the lychee-action. It's fast, concurrent, and provides excellent reports.

# .github/workflows/links.yml
name: Check Links
on:
  push:
    branches: [main]
  schedule:
    - cron: "0 0 * * 1" # Run weekly

jobs:
  linkChecker:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Link Checker
        uses: lycheeverse/lychee-action@v1.9.0
        with:
          args: --fail --exclude-mail --verbose README.md docs/*.md

Implementation: GitLab Link Checker Job

For GitLab users, you can run the same tool within a job using the official Docker image:

link_check:
  image: lycheeverse/lychee:latest
  script:
    - lychee README.md docs/*.md
  allow_failure: true

Policy Recommendation

Fail pull requests on internal broken links.
Warn (not fail) on temporary 403/429 external links.
Run full link audits weekly on default branch.

Best Rollout Path

Start by checking README and docs folders only. Once false positives are under control, expand coverage to generated docs, marketing pages, and scheduled full-site audits.