Add an ignore-patterns input for known false positives, and update the existing issue instead of opening duplicates

[mmcky]

Problem

action-link-checker has no way to whitelist known-good URLs, so hosts that block or throttle datacenter IP ranges get reported as broken every single run. Combined with create-issue: true on a weekly cron, this opens a new duplicate issue every week for links that are perfectly fine.

Concrete case: QuantEcon/lecture-python-programming has accumulated nine open duplicate issues between 2026-06-01 and 2026-07-27, all reporting the same two links:

URL	Reported status	Actual status from a normal network
https://fred.stlouisfed.org/	0 (Timeout)	200, 0.32s
https://fred.stlouisfed.org/series/UNRATE	0 (Timeout)	200, 0.49s

FRED (St. Louis Fed) throttles requests from cloud/CI IP ranges, so GitHub Actions runners time out while the links work fine for readers. Every QuantEcon lecture repo links to FRED, so this affects all of them.

The signal-to-noise ratio on these issues is now effectively zero, which is exactly how a genuine broken link gets missed. Issue QuantEcon/lecture-python-programming#587 is the first in two months to contain a real finding (a stale GitHub docs URL), and it is buried under eight identical false positives.

Request 1: an ignore-patterns input

Add an input that accepts a list of regex or glob patterns for URLs to skip entirely, mirroring Sphinx's long-standing linkcheck_ignore. Something like an ignore-patterns input taking a newline-separated list of patterns, each matched against the full URL, with matching URLs excluded from the report and from the broken/redirect counts.

The lecture repos already maintain exactly this list in _config.yml under sphinx.config.linkcheck_ignore — for lecture-python-programming that is https://fred.stlouisfed.org/.* among others. Because this action scans built HTML rather than running through Sphinx, it never sees that configuration and re-reports the same URLs indefinitely. An equivalent input would let repos keep one source of truth for known false positives.

Note that silent-codes is not a workaround here. Setting it to include 0 would silence every timeout, including real ones — it suppresses a status code, not a URL, so it trades one false-negative class for another.

This is also becoming more relevant as the lecture repos migrate to Jupyter Book 2: _config.yml is replaced by myst.yml, which has no linkcheck_ignore equivalent, so an action-level ignore list becomes the only place to record known-good-but-unreachable-from-CI URLs.

Request 2: update the existing issue instead of opening a new one

When create-issue: true and an open issue created by this action already exists in the repo, the action should update that issue (edit the body, or add a comment) rather than creating another one. Optionally gate this on a configurable label or on the issue title matching issue-title.

Right now a weekly cron against a persistent problem produces an unbounded pile of identical issues that nobody triages. Happy to split this into a separate issue if you would prefer to track the two requests independently.

Environment

Reported from the Link Checker [Anaconda, Linux] workflow in QuantEcon/lecture-python-programming, using QuantEcon/action-link-checker@main with silent-codes: '403,503', fail-on-broken: 'false', create-issue: 'true'.

[mmcky]

Some further detail from the repo that prompted this, plus a code-level finding that I think sharpens the ask.

The exclusion list already exists, once per repo

Every QuantEcon lecture repo maintains a linkcheck_ignore list in lectures/_config.yml for Sphinx's built-in checker. https://fred.stlouisfed.org/.* has been in the lecture-python-programming list since at least April, alongside nine other accumulated false positives — keras.io, data.oecd.org, reddit.com, openai.com, chatgpt.com, an ieeexplore.ieee.org DOI, a sciencedirect.com article and a pinned matplotlib source link.

This checker scans built HTML and never reads that configuration, so it re-reports links the repo has already declared exempt.

So rather than a standalone ignore-patterns input, it may be worth having the action read linkcheck_ignore from the project's _config.yml — with an input to point at the file, and an explicit list as an override for repos that need one. That gives one exclusion list per repo instead of two that drift apart, and every existing QuantEcon repo inherits the fix with no workflow edit. The patterns are already regex, so they carry over directly.

Prior art worth recording

QuantEcon/lecture-python-programming#518 attempted a workflow-side workaround: a pre-processing step that rewrote matching hrefs to # in the built HTML before the checker ran. It was closed on 2026-04-14 as not the approach we want, and I think rightly — mangling the build artifact to satisfy the checker also masks genuine breakage in those same files. Worth noting here so it does not get re-proposed.

The existing bot-blocking heuristic cannot fire on timeouts

is_likely_bot_blocked() already exists to catch exactly this class of false positive, but for a timeout it can never help. Three separate reasons, from link_checker.py:

silent_codes is unreachable. It is only consulted in the success path, at if response.status_code in silent_codes. The requests.exceptions.Timeout handler returns before any such check, so silent-codes: '0,403,503' cannot suppress a timeout. That was the first workaround I looked for, and it is not available.

legitimate_domains is unreachable. That list is only consulted when the error string contains Connection Error:

for domain in legitimate_domains:
    if domain in url.lower() and error and 'Connection Error' in str(error):
        return True

but the timeout handler passes error='timeout':

except requests.exceptions.Timeout:
    likely_blocked = is_likely_bot_blocked(url, error='timeout')

Demonstrated by calling the function directly — note that even an explicitly listed domain is unprotected on timeout:

URL	error	result
https://github.com/x	Connection Error	True
https://github.com/x	timeout	False
https://fred.stlouisfed.org/	Connection Error	False
https://fred.stlouisfed.org/	timeout	False

Neither hardcoded list contains fred.stlouisfed.org — and hardcoding individual domains is not the fix, which is what this issue is about.

The net effect is that a timeout always yields broken: True unless the URL happens to match domain_indicators. Making the timeout and connection-error paths share the same evaluation — and consulting silent_codes there too — looks like a small fix worth having independently of the ignore-patterns work, since it currently means a listed domain is protected against one failure mode but not the other.

State downstream

The nine duplicates in lecture-python-programming are now closed, along with an older batch of eight from 2026-04-06 to 2026-05-25 that had dropped out of GitHub's issue search index and so never appeared in the repository's open-issues list at all. Seventeen issues for two URLs that return 200 in under half a second from a normal network.

The next scheduled run will report six FRED URLs rather than four: a new Polars lecture using FRED data was published on 2026-07-30, which is the deduplication half of this issue becoming the more pressing half.

[mmcky]

Both requests shipped in #3, merged as d9df5d4.

Request 1 — ignore-patterns. A newline-separated list of regular expressions for URLs to skip entirely. Newline-separated rather than comma-separated so quantifiers such as {1,3} survive, and matched with re.search, so a bare domain works as a substring and a Sphinx linkcheck_ignore list can be pasted in nearly unchanged. Matching URLs are never requested at all, so they can be reported as neither broken nor redirected — an explicit exemption rather than a suppressed finding. They are counted separately and exposed as a new ignored-count output, so an exemption stays visible instead of silently shrinking the scanned set.

Request 2 — reuse the open issue. update-existing-issue, defaulting to true. Before creating an issue the action now looks for the newest open issue with the same title and the broken-links label and refreshes its body. A weekly cron on a persistent finding produces one issue rather than one per week. Close it once the links are fixed and a recurrence opens a fresh one. Set the input to false to restore the old behaviour, and there is a new issue-updated output reporting which path was taken.

The underlying bug you found. is_likely_bot_blocked() could never fire on a timeout: the legitimate_domains allowance required the error string Connection Error while the timeout handler passed timeout, so a listed domain was protected against one failure mode and reported broken on the other. silent-codes was only consulted on responses that carried a status code, so it could not apply to a timeout either. Both are fixed, and the allowance is now keyed on which handler caught the failure rather than on the error text — an arbitrary exception message containing the word "timeout" no longer counts. Status 0 is honoured in silent-codes, but only for genuine transport failures: a malformed link or a redirect loop also reports 0 and stays reported, since those are the project's own to fix.

For the case that prompted this, the lecture repos can now write:

- uses: QuantEcon/action-link-checker@v1
  with:
    html-path: '_build/html'
    ignore-patterns: |
      https://fred\.stlouisfed\.org/.*

A review pass on #3 turned up several more fail-quiet paths, all fixed before merge: an invalid ignore pattern could abort the run rather than be skipped as documented, the checker's stderr went to a file that was never displayed so none of its warnings could reach a job log, and a crash aborted the step with no diagnostic at all. #4 then moved the test suite off httpstat.us and httpbin.org, both of which had stopped answering, leaving the CI step named for silent-codes exercising nothing.

The linkcheck_ignore auto-discovery idea from the comment above is not implemented and is now tracked separately in #6, with the trade-offs written up — it needs a YAML dependency and a second configuration surface, and the Jupyter Book 2 migration may make it obsolete before it is worth building.

Closing as delivered. v1.1.0 is being tagged now; note that the reporting workflows in QuantEcon/lecture-python-programming pin @main, so they already have all of this.