Link checker CI passes despite broken links on master

[ihabadham]

Summary

The markdown link checker CI workflow passes in ~5 seconds despite master having 21+ broken GitHub URLs that return HTTP 404.

Evidence

Broken URLs on master (all return 404)

https://github.com/shakacode/react_on_rails/blob/master/lib/generators/react_on_rails/install_generator.rb
https://github.com/shakacode/react_on_rails/blob/master/spec/dummy/config/shakapacker.yml
https://github.com/shakacode/react_on_rails/tree/master/spec/dummy
https://github.com/shakacode/react_on_rails/tree/master/lib/react_on_rails/controller.rb
... (21+ total)

These should be prefixed with react_on_rails/ after the monorepo restructure in PR #2114.

Local vs CI behavior

Environment	Time	Result
Local (npx markdown-link-check)	~4 minutes	❌ Finds 404 errors correctly
CI (GitHub Actions)	~5 seconds	✅ "All links are good!"

Timeline

• Nov 4: wretry.action wrapper added (PR Add retry logic for transient HTTP errors in markdown link checker #1899)
• Nov 16: CI failed and caught broken relative link ../CHANGELOG.md (took 96-99 seconds)
• Nov 24: Monorepo restructure merged (PR Restructure monorepo with two top-level product directories #2114), breaking many GitHub URLs
• Nov 24+: All CI runs pass in ~5 seconds despite broken external URLs

CI Run Comparison

Failed run (Nov 16) - Run #19398864335

• find command took 96-99 seconds
• Found error: ERROR: 1 dead links found in docs/api-reference/configuration-deprecated.md !

Recent "successful" run on master - Run #20147672041

• find command took only 5 seconds
• Reports "All links are good!" despite 21+ broken URLs

Local verification

# This returns 404
curl -sI "https://github.com/shakacode/react_on_rails/blob/master/lib/generators/react_on_rails/install_generator.rb" | head -1
# HTTP/2 404

# Local tool catches it
npx markdown-link-check docs/api-reference/redux-store-api.md --config .github/markdown-link-check-config.json
# ERROR: 4 dead links found!

Root Cause Theory

Something changed in the GitHub Actions environment between Nov 16 and Nov 24 that causes the Docker container running markdown-link-check to complete almost instantly (~5 seconds for 102 files) without making actual HTTP requests.

The 5-second completion time is impossible if network requests are being made - each external link check takes 0.5-1 second minimum.

Workflow Configuration

.github/workflows/check-markdown-links.yml:

• Uses Wandalen/wretry.action@v3.5.0 wrapper
• Wraps tcort/github-action-markdown-link-check@a800ad5f1c35bf61987946fd31c15726a1c9f2ba
• Config file: .github/markdown-link-check-config.json

Impact

The link checker CI is not functioning as a safety net - broken links can merge to master undetected.

Possible Solutions

1. Investigate why Docker container isn't making HTTP requests
2. Switch to a different link checker (e.g., Linkspector recommended in the deprecation notice)
3. Add verbose logging to diagnose the issue
4. Test without the wretry.action wrapper

Related

• PR Fix outdated paths after monorepo restructuring #2216 fixes the broken URLs introduced by the monorepo restructure
• PR Restructure monorepo with two top-level product directories #2114 was the monorepo restructure that broke the URLs
• PR Add retry logic for transient HTTP errors in markdown link checker #1899 added the wretry.action wrapper

🤖 Generated with Claude Code

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

🔗 Similar Issues

Related Issues

• Ci check of assets:precompile stdout #2081
• CI: Improve workflow verification retry logic in run-skipped-ci #2000
• Investigate and Fix Streaming Flaky Tests in ReactOnRailsPro Gem Integration Suite #1866
• Migrate React on Rails Pro CI from CircleCI to GitHub Actions #1871
• CI/Build improvements: prepack scripts and yalc workflow fixes #1959

🔗 Related PRs

#1800 - Add automated markdown link checking GitHub Action [merged]
#1872 - Migrate React on Rails Pro CI from CircleCI to GitHub Actions [merged]
#1982 - Remove dead links from major-performance-breakthroughs-upgrade-guide.md [merged]
#2062 - Fix CI safety check to evaluate latest workflow attempt [merged]
#2065 - Break CI circular dependency with non-docs change [merged]

👤 Suggested Assignees

• justin808
• AbanoubGhadban
• Judahmeek
• ihabadham

---

🧪 Issue enrichment is currently in early access.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

[ihabadham]

Investigation Results from PR #2218

Just ran the link checker on a branch based on master. Results confirm the bug:

CI Run: #20182353123

find docs/ started: 23:04:55.606
set +x (completed): 23:05:00.146
Duration: 4.5 seconds
Result: "[✔] All links are good!"

Expected behavior

For 102 markdown files with external URLs, the link checker should take 4+ minutes (as observed locally and in the Nov 16 failed run which took 96 seconds).

Confirmed bug

The link checker:

• ✅ Runs and completes
• ❌ Takes only 4.5 seconds (should take 4+ minutes)
• ❌ Reports success despite 21+ broken 404 URLs
• ❌ Is NOT making actual HTTP requests to verify external links

Next steps

Options to fix:

1. Debug the Docker container's network behavior
2. Remove the wretry.action wrapper to see if that's the cause
3. Switch to a different link checker (e.g., Linkspector)
4. Add verbose logging to diagnose why HTTP requests aren't being made

🤖 Generated with Claude Code

[ihabadham]

Root Cause Found! 🎉

The markdown-link-check tool crashes silently in CI due to a Node.js ESM/CommonJS compatibility error.

The Problem

1. The action uses node:21.7.3-alpine3.18 as the base Docker image
2. markdown-link-check@3.13.7 has a dependency on marked that fails to load in Node.js 21:

Error [ERR_REQUIRE_ESM]: require() of ES Module .../marked.esm.js not supported.
Instead change the require of marked.esm.js ... to a dynamic import() which is available in all CommonJS modules.

3. The error message contains Error (lowercase) not ERROR: (uppercase with colon)
4. The entrypoint.sh checks for ERROR: using grep: grep -q "ERROR:" error.txt
5. The grep fails to match, so CI reports "All links are good!" even though no links were actually checked

Proof

The timing proves this:

• CI completes in ~4.5 seconds for 102 files (each crash takes ~30ms)
• Local testing takes 4+ minutes when links are actually checked

Reproduction

docker run --rm -v "$(pwd)":/github/workspace -w /github/workspace node:21.7.3-alpine3.18 sh -c "
apk add --no-cache bash git > /dev/null 2>&1
npm install -g markdown-link-check@3.13.7 > /dev/null 2>&1
markdown-link-check docs/README.md --config .github/markdown-link-check-config.json
"

This shows the ESM error immediately.

Solution Options

1. Stop using wretry.action wrapper - Use tcort/github-action-markdown-link-check directly (may work better)
2. Switch to a different tool - Use lychee or another link checker that doesn't have this issue
3. Report the bug upstream - The tcort action needs to update its Node.js version or markdown-link-check version
4. Pin to an older Node.js version - Use a custom Dockerfile with Node.js 20 or 18

Recommended Fix

Switch to lychee-action which is more robust and faster:

- name: Check markdown links
  uses: lycheeverse/lychee-action@v2
  with:
    args: --config .lychee.toml docs/
    fail: true