web-unified-docs repository uses a focused broken link monitoring system that provides visibility without blocking development. The system separates PR-time feedback (informational) from production monitoring (critical alerts).
How the system works
PR previews
Shows all broken links found in changed files as a PR comment. PRs never fail due to broken links. Development continues unblocked.
Production monitoring
Weekly full content scan every Monday. Broken links are logged to Datadog and tracked in a single auto-updated GitHub issue.
PR previews (informational only)
When you open or update a pull request, the link checker scans the content and posts a comment listing any broken links it finds.- PRs never fail due to broken links.
- All broken links are shown in PR comments for awareness.
- No Datadog alerts are triggered for PR previews.
- Development continues unblocked.
The link checker scans all content, not just the files you changed. It is normal to see broken links in your PR comment that are unrelated to your changes. Focus on fixing broken links in files you directly modified.
Production monitoring (critical alerts)
The production monitoring system runs a full content scan every Monday and targets issues that directly affect end users.- Weekly scan — every Monday, all published content is checked.
- GitHub issue — a single “Link Checker Report” issue is auto-updated with the latest results.
- Datadog logging — production broken links are logged and trigger alerts.
- Auto-close — the previous issue is closed when a new one is generated.
Finding current broken links
To find all currently known broken links in production:- Go to the repository’s Issues tab.
- Filter by label:
link-checker-report. - Open the most recent issue — it contains all current production broken links.
UDR Migration Link Check
A dedicated workflow is available for teams migrating products to the Unified Docs Repository. It lets you check links for a specific product before migrating. Workflow file:.github/workflows/udr-product-link-check.yml
Navigate to the workflow
Go to the Actions tab → UDR Product Link Check.
Optionally specify custom paths
Enter custom paths to check if you want to limit the scan to a specific subdirectory.
Running the link checker locally
You can run the broken link checker locally to preview results before opening a PR. To check all content:terraform-plugin-framework with the directory name of the product content you want to check.
Datadog monitoring
Production broken links are tagged in Datadog for alerting and tracking. Only production events generate Datadog entries — PR previews produce no Datadog noise.Tags
| Tag | Value |
|---|---|
environment | production |
service | web-unified-docs |
alert_type | broken_links_production |
Query
Best practices
- For developers
- For content teams
- Review PR comments — check which links are broken in your changes.
- Fix critical internal links — but don’t let external issues block your PR.
- Monitor the weekly GitHub issue — stay aware of overall link health.
- Focus on content quality — write accurate links and double-check paths before merging.
Troubleshooting
My PR shows broken links but I didn’t change those files
My PR shows broken links but I didn’t change those files
This is expected. The link checker scans all content to provide full visibility. Focus on:
- Fixing broken links in files you directly modified.
- Internal HashiCorp links (high priority).
- Considering whether external links in your area can be improved.
An external site is temporarily down
An external site is temporarily down
For temporary external outages:
- Check if the site recovers before merging.
- Consider whether the link is essential to your content.
- Document known unreliable sources in your team’s notes.
An internal link is broken but works in my browser
An internal link is broken but works in my browser
This usually means one of the following:Common path mistake:
- The link works locally but resolves differently in the production environment.
- The path is case-sensitive in production but not locally.
- Double-check the exact file path and capitalization.
Why PRs don’t fail for broken links
The system is intentionally non-blocking at PR time for these reasons:- External links can break at any time, beyond any contributor’s control.
- Development velocity shouldn’t be blocked by external site issues.
- PR previews are for testing, not final production validation.
- Full visibility is maintained through PR comments without forcing a failed status check.