How to check links with lychee in GitHub Actions (config, caching, and the false positives to exclude)

Lychee is a link checker written in Rust, offering fast performance and support for Markdown, HTML, and plain text. It features an official GitHub Action, making it an easy solution to detect broken links in documentation repositories or static sites. The default setup may produce noisy results during the first run, including rate-limited sites, links requiring login, or example URLs that were never meant to resolve.

This article provides a step-by-step guide to minimize these issues, ensuring a quiet and useful link check.

To set up a link check in GitHub Actions, create a workflow file (.github/workflows/links.yml) with the following structure:

1. Define the workflow for pull requests and schedule it to run weekly.

2. Use the lychee-action version 2 with the --config option pointing to the lychee.toml configuration file located in the repository root.

3. In the lychee.toml config file:

a. Set max_concurrency to 16 and max_retries to 2 to avoid overwhelming rate-limited sites.

b. Specify acceptable HTTP status codes (200, 204, 206, and 429) as success responses, excluding 429 (Too Many Requests) for CI environments.

c. Define a list of URLs to exclude from checking (e.g., localhost, 127.0.0.1, example.com, org, net, and linkedin.com).

d. Specify file patterns to include (all Markdown and HTML files) and exclude (node_modules, vendor, and CHANGELOG.md) using glob patterns.

e. Set include_mail to false to only check for valid syntax in mailto: addresses.

To optimize the link check for pull requests, create a separate step in the workflow that:

1. Fetches changes from the base branch using git fetch.

2. Extracts the list of changed files (.md and .html) using git diff.

3. Executes lychee on the extracted files and reports failures if any broken links are found.

For scheduled runs (weekly sweep), modify the lychee action to incorporate caching and limit cache age to one day. This ensures frequent runs are fast, and old results are not cached for too long.

Lastly, create an issue with the broken links report when the scheduled run fails, using the create-issue-from-file GitHub Action. This way, you can easily manage and track the broken links in a separate issue instead of relying on the GitHub Actions status.