When an engineer renames docs/setup.md or edits a heading from ## Authentication to ## Token Setup, unit tests and TypeScript builds still pass green. Every code check succeeds while #authentication in your README silently becomes a dead jump.
Traditional HTTP crawlers fall short in pull requests for two reasons: they often miss local relative paths and GitHub Flavored Markdown (GFM) heading slugification rules, and external rate limits (429/403) turn deterministic CI runs flaky.
Step 1: Verify relative files, images, and GFM #anchors offline
The cleanest CI gate is deterministic and network-free: validate Markdown links, relative image assets, and exact GFM heading anchors (including Unicode, emojis, punctuation, and duplicate -1, -2 suffixes) directly against the workspace files.
The zero-dependency Python CLI deadlinkfinder does more than exit non-zero: when a target breaks, it uses difflib similarity matching to print "did you mean" suggestions for renamed files and headings.
pip install deadlinkfinder
# Scan workspace Markdown links, images, and #heading anchors offline
deadlinkfinder check .
# Scan docs/ with JSON output and optional external URL check
deadlinkfinder check docs/ --format json --external
Step 2: Gate pull requests in GitHub Actions with SARIF annotations
Wiring the check into a pull_request workflow and passing --format sarif output to GitHub Code Scanning surfaces broken links inline on the pull request diff with line-level fingerprints.
Keeping PR checks strictly offline while delegating --external URL sweeps to a nightly schedule gives you sub-second deterministic pull request feedback with zero network flakiness.
name: Markdown Link Check
on:
pull_request:
paths:
- "**/*.md"
- "docs/**"
jobs:
links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: pip install deadlinkfinder && deadlinkfinder check .
- name: Generate SARIF report
if: always()
run: deadlinkfinder check . --format sarif > links.sarif
continue-on-error: true
Originally published at umutgungorr.com/blog/github-actions-broken-links-deadlinkfinder.
Source & architecture notes: DeadLinkFinder case study · GitHub · PyPI
Top comments (0)