Skip to content

ci: check Markdown links on every PR and fix all dead links - #1609

Merged
lklimek merged 6 commits into
devfrom
ci/markdown-link-check-changed-files
Nov 10, 2026
Merged

lklimek merged 6 commits into
devfrom
ci/markdown-link-check-changed-files

Conversation

@Claudius-Maginificent

@Claudius-Maginificent Claudius-Maginificent commented Nov 10, 2026 •

Copy link
Copy Markdown
Collaborator

TL;DR: Fixes every dead link in the repository's Markdown, and makes the link check run on every pull request, only on the files a change touches, without false alarms.

User story

As a contributor or maintainer, I want broken links in the Markdown files I change reported on my pull request, without noise from files I did not touch or links that work.

Scenario

Base flow

A PR that edits any Markdown file is merged into dev, and the "Check Markdown links" workflow runs on the push.

Actual behavior

The job checks about 120 Markdown files, every file that differs from master, and fails on hundreds of old or unreachable links. The files the merge actually changed are buried among them. For example, run 42693029742 for #1602 changed only CHANGELOG.md, whose links were all fine, and still failed with 350 dead links. Every push to dev that touches a Markdown file has failed this way since 2026-11-05.

Expected behavior

On every pull request and on pushes to dev/master, the job checks only the Markdown files that were added or changed, and fails only when one of them has a dead link.

Detailed discussion

What was done

  • Root cause: gaurav-nelson/github-action-markdown-link-check@v1 (archived) ran with check-modified-files-only: yes and its default base-branch: master, so on dev it diffed against master. get-diff-action's file list only decided whether the step ran.
  • The step now runs markdown-link-check@3.14.2 (the version the maintained tcort action installs) directly on the files from get-diff-action (FORMAT: json, read with jq). The existing .md-link-check.json config is kept. A branch-creation push (GIT_DIFF=all) checks every tracked Markdown file.
  • book/** is excluded: book/SUMMARY.md and book/README.md link relative to the staged mdBook tree, which produced 155 false Status: 400 reports. prepare-docs.py and the mdBook build in the docs workflow already check them.
  • The pull_request trigger is back, for every PR (it was disabled in build(github): fix broken github actions and regenerate some code #615 while the check diffed against master), with the same concurrency and read-only permissions as the Markdown linter. A PR without Markdown changes passes at once.
  • .md-link-check.json: ignores eprint.iacr.org/www.iacr.org, which answer every non-browser client with a Cloudflare 403 challenge (cf-mitigated: challenge). Rewrites …/api/rpc/ to …/rpc/openapi/: prepare-docs.py publishes rpc/openapi/ as api/rpc/ on the docs site, so these links resolve to the file they will show, and a missing target is still reported.
  • File names are passed after --, so a PR file name cannot be read as an option.
  • 504 counts as alive: GitHub answers bursts of checks with transient 504s (the links returned 200 when retried).
  • Every dead link found by a full check (29, book/ excepted) is fixed: moved pages point to their current location or a tagged permalink, deleted ones to a Web Archive copy, and a deleted Google Doc is named instead of linked. Links to upstream Tendermint docs and to this repository's own files are relative where Tenderdash has the page (p2p spec, tools docs, internal/libs/confix, DOCKER/Dockerfile), as the docs site at https://dashpay.github.io/tenderdash/ is built from them.
  • make proto-doc links types from other packages in the generated spec/abci/api.md to their proto directories (and google.protobuf types to protobuf.dev) instead of anchors the page lacks; api.md is regenerated with it.

Testing

The step script was run locally:

  • [] → "No changed Markdown files.", exit 0;

  • ["CHANGELOG.md","README.md"] → exit 0;

  • ["docs/rfc/rfc-012-custom-indexing.md"] → reports its dead link, exit 1;

  • all → 187 tracked files, none under book/;

  • the four files linking api/rpc/index.html failed before the config change and pass after it; a link to a missing api/rpc/missing.html is still reported;

  • a file citing iacr.org passes.

  • a full check of all 187 tracked Markdown files outside book/ passes (29 dead links before).

markdownlint reports no new findings in the edited files. This PR also runs the workflow through its new pull_request trigger on the 20 Markdown files it changes.

actionlint reports only that it does not know the existing ubuntu-26.04 runner label.

Breaking changes

None. A PR that edits a file with an old dead link now gets a red, non-required check until that link is fixed.

Prior work

Attribution

🤖 Generated with Claude Code

🤖 Co-authored by Claudius the Magnificent AI Agent

PR Hygiene · 6e87dbd

  • Bots — thepastaclaw ✓
  • Self-review — not asked of a bot author
  • Build green
  • Approvals
    • github (.github/workflows/markdown-links.yml) — approved by lklimek
    • files with no dedicated owner (.md-link-check.json, DOCKER/README.md, Makefile and 18 more) — approved by lklimek

When every merge requirement is met, the PR Hygiene check passes. Reviewer limits do not block merging; other required GitHub checks and protections still apply.

lklimek and others added 2 commits November 10, 2026 10:07
The archived gaurav-nelson link-check action ran with
check-modified-files-only and its default base-branch master, so every
push to dev that touched a Markdown file checked all ~120 files that
differ from master and failed on their stale links. get-diff-action
already lists the files the push changed; the job now passes exactly
those to markdown-link-check, and leaves book/ (links relative to the
staged mdBook tree, checked by the docs build) out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@coderabbitai

coderabbitai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

The check now covers only the files a change touches, so it runs on all
pull requests again (it was disabled there while it diffed against
master). Its config ignores iacr.org, whose Cloudflare front answers any
non-browser client with a 403 challenge, and maps the docs-site path
api/rpc/ to rpc/openapi/, the repository files prepare-docs.py publishes
there. File names are passed after `--` so none is read as an option.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Claudius-Maginificent Claudius-Maginificent changed the title ci: check links only in the Markdown files a push changed ci: check Markdown links on every PR, only in changed files Nov 10, 2026
@thepastaclaw

thepastaclaw commented Nov 10, 2026 •

Copy link
Copy Markdown

✅ Final review complete — no blockers (commit 6e87dbd) · triage: normal

@lklimek lklimek added this to the v2.0 milestone Nov 10, 2026
A full markdown-link-check of the repository (book/ excepted) reported
29 dead links; it is clean now.

- Moved or deleted pages point to their current location, a tagged
  permalink, or a Web Archive copy; a deleted Google Doc is named
  instead of linked.
- Links to upstream Tendermint docs and to this repository's own files
  are relative where Tenderdash has the page (p2p spec, tools docs,
  confix, Dockerfile).
- proto-doc links types from other packages in spec/abci/api.md to their
  proto directories (and google.protobuf types to protobuf.dev) instead
  of anchors the page does not have; api.md is regenerated.
- The link check treats 504 as alive: GitHub answers bursts of checks
  with transient 504s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@Claudius-Maginificent Claudius-Maginificent changed the title ci: check Markdown links on every PR, only in changed files ci: check Markdown links on every PR and fix all dead links Nov 10, 2026
@lklimek
lklimek marked this pull request as ready for review November 10, 2026 10:41
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added the waiting-bots Waiting for the review bots to report on this head label Nov 10, 2026

@thepastaclaw thepastaclaw left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Final validation — Phase 1 + Phase 2

The workflow and documentation fixes are generally correct, and the available CI checks are green, including the Markdown link check. One blocking coverage gap remains: changed Markdown files inside dot-directories are silently omitted because the diff action does not enable minimatch dot matching; the new blanket IACR ignore is also an in-scope suggestion because it allows future mistyped IACR URLs to pass.

🔴 1 blocking | 🟡 1 suggestion(s)

Review provenance

Source: reviewer 1: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: general); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)

  • Triage: normal by gpt-6.1-sol (effort low) — The change is primarily documentation and CI tooling, but it modifies workflow execution, link-check configuration, generated documentation, and Makefile behavior across the repository, warranting more than a trivial or low-effort review without affecting a critical surface.
  • Phase 1 reviewers: muse-spark-1.3-contributor — general (completed, effort xhigh); agent phase1-reviewer
  • Phase 1 model: muse-spark-1.3-contributor — not quota-gated; passed over gemini-3.8-flash-high (antigravity quota lookup failed), glm-5.3-flash (not used above high effort; tier asks max)
  • Second Phase-2 pass: on this first full review every Phase-2 reviewer also ran a second, independent time, and the verifier weighed both sets
  • Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-verifier
  • Phase 2 reviewers: gpt-6.1-sol — general (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — general (completed, effort high); agent phase2-reviewer
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review (PastaClaw). How to work through them:
- Verify each finding against the code; fix only what is real, as narrowly as the finding.
- If a finding is wrong, decline it on its thread in one or two sentences; the bot answers once and stops.
- To defer one, link a tracking issue on its thread (or reply asking the bot to file one).
- Suggestions are optional: fix them forward in a later PR rather than pushing another round just for them.
- Address every current finding in one push: self-review the full diff first, and don't push piecemeal.
- Keep the PR's scope; don't grow it to satisfy hardening suggestions.
- Carried items were raised in an earlier round: read the thread first, and don't re-fix what you already fixed, declined or deferred there. Disputed and deferred items are already handled and are not listed.

In `.github/workflows/markdown-links.yml`:
- [BLOCKING] .github/workflows/markdown-links.yml:32-35: Include Markdown files in dot-directories
  The `**/**.md` pattern is evaluated without minimatch dot matching, so tracked Markdown files such as `.github/PULL_REQUEST_TEMPLATE.md`, `.github/copilot-instructions.md`, and `.agents/skills/tenderdash-release/SKILL.md` are not selected when they are changed. A pull request touching only one of these files therefore produces an empty file list and exits successfully without checking its links. This also differs from the branch-creation path, which enumerates tracked Markdown files directly. Enable dot matching so that `book/**` remains the only deliberate exclusion.

In `.md-link-check.json`:
- [SUGGESTION] .md-link-check.json:6-11: Avoid a blanket ignore for IACR URLs
  The domain-wide ignore exempts every `eprint.iacr.org` and `www.iacr.org` URL, not just the three currently cited papers that return Cloudflare challenges. As a result, a future typo in an IACR URL, such as an incorrect paper number, will pass the link check and conflicts with this PR's goal of detecting dead links in changed Markdown. Archived copies are available for the three existing RFC references, so those links can be changed to archive URLs and the blanket ignore removed.

Comment thread .github/workflows/markdown-links.yml Resolved
Comment thread .md-link-check.json Resolved
@github-actions github-actions Bot added waiting-self-review Waiting for the author to post /self-reviewed and removed waiting-bots Waiting for the review bots to report on this head labels Nov 10, 2026
lklimek and others added 2 commits November 10, 2026 12:53
get-diff-action matches PATTERNS with minimatch, which skips dot paths by
default, so changes to .github/*.md or .agents/**/*.md were never checked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@github-actions

github-actions Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Waiting for bot review — thepastaclaw not yet. Wait for the missing reviews, or a writer can post /skip-bots to proceed without them; blocking findings still need addressing.
Full checklist in the description.

@github-actions github-actions Bot added waiting-bots Waiting for the review bots to report on this head and removed waiting-self-review Waiting for the author to post /self-reviewed labels Nov 10, 2026

@thepastaclaw thepastaclaw left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-review — Final validation — Phase 1 + Phase 2

The current implementation correctly restores pull-request coverage, includes Markdown files in dot-directories, excludes the staged mdBook sources, and applies the generated documentation link rewrites consistently. CI reports success for the build, tests, lint, documentation, and Markdown-link checks; only review and PR Hygiene checks remain pending. One in-scope suggestion remains regarding the breadth of the IACR URL exemption.

🟡 1 suggestion(s)

Approved: nothing here blocks the merge. The non-blocking findings are optional: fix them forward, in this PR or a follow-up, without waiting for another review round.

Still open from earlier rounds (1)

  • 🟡 Suggestion: Avoid a blanket ignore for IACR URLs — .md-link-check.json:6-11 (thread)
Review provenance

Source: reviewer 1: muse-spark-1.3-contributor (agent: phase1-reviewer, role: general); reviewer 2: gpt-6.1-sol (agent: phase2-reviewer, role: general); reviewer 3: gpt-6.1-sol (agent: phase2-reviewer, role: general); final verifier: gpt-6.1-sol (agent: sol-verifier, role: final-verifier)

  • Triage: normal by gpt-6.1-sol (effort low) — The pull request makes a cross-cutting CI workflow and link-check configuration change, including script behavior, dependency usage, path handling, and generated documentation updates, so it warrants ordinary review despite not touching critical runtime code.
  • Phase 1 reviewers: muse-spark-1.3-contributor — general (completed, effort xhigh); agent phase1-reviewer
  • Phase 1 model: muse-spark-1.3-contributor — not quota-gated; passed over gemini-3.8-flash-high (antigravity quota lookup failed), glm-5.3-flash (not used above high effort; tier asks max)
  • Fresh final gate: an independent Phase-2 review ran after iterative findings were reconciled
  • Fresh verifier: gpt-6.1-sol — final-verifier; agent sol-verifier
  • Phase 2 reviewers: gpt-6.1-sol — general (completed, effort high); agent phase2-reviewer, gpt-6.1-sol — general (completed, effort high); agent phase2-reviewer
🤖 Prompt for all review comments with AI agents
These findings are from an automated code review (PastaClaw). How to work through them:
- Verify each finding against the code; fix only what is real, as narrowly as the finding.
- If a finding is wrong, decline it on its thread in one or two sentences; the bot answers once and stops.
- To defer one, link a tracking issue on its thread (or reply asking the bot to file one).
- Suggestions are optional: fix them forward in a later PR rather than pushing another round just for them.
- Address every current finding in one push: self-review the full diff first, and don't push piecemeal.
- Keep the PR's scope; don't grow it to satisfy hardening suggestions.
- Carried items were raised in an earlier round: read the thread first, and don't re-fix what you already fixed, declined or deferred there. Disputed and deferred items are already handled and are not listed.

In `.md-link-check.json`:
- [SUGGESTION] .md-link-check.json:6-11: Avoid a blanket ignore for IACR URLs
  (carried; thread: https://github.com/dashpay/tenderdash/pull/1609#discussion_r4524843220)

@github-actions github-actions Bot removed the waiting-bots Waiting for the review bots to report on this head label Nov 10, 2026
@github-actions

Copy link
Copy Markdown

Ready for review — github: ktechmidas or lklimek or shumkov · files with no dedicated owner: lklimek or shumkov.
Full checklist in the description.

@github-actions github-actions Bot added the ready-for-human PR Hygiene: bots done, author self-reviewed, awaiting human review label Nov 10, 2026
@github-actions

Copy link
Copy Markdown

Policy satisfied — this can merge.
Full checklist in the description.

@github-actions github-actions Bot removed the ready-for-human PR Hygiene: bots done, author self-reviewed, awaiting human review label Nov 10, 2026
@lklimek
lklimek merged commit 55594f3 into dev Nov 10, 2026
41 of 42 checks passed
@lklimek
lklimek deleted the ci/markdown-link-check-changed-files branch November 10, 2026 16:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants