lychee link checking action

Quickly check links in Markdown, HTML, and text files using lychee.

When used in conjunction with Create Issue From File, issues will be opened when the action finds link problems (make sure to specify the issues: write permission in the workflow or the job).

Usage

Here is a full example of a GitHub workflow file:

It will check all repository links once per day and create an issue in case of errors. Save this under .github/workflows/links.yml:

name: Links

on:
  repository_dispatch:
  workflow_dispatch:
  schedule:
    - cron: "00 18 * * *"

jobs:
  linkChecker:
    runs-on: ubuntu-latest
    permissions:
      issues: write # required for peter-evans/create-issue-from-file
    steps:
      - uses: actions/checkout@v5

      - name: Link Checker
        id: lychee
        uses: lycheeverse/lychee-action@v2
        with:
          fail: false

      - name: Create Issue From File
        if: steps.lychee.outputs.exit_code != 0
        uses: peter-evans/create-issue-from-file@v5
        with:
          title: Link Checker Report
          content-filepath: ./lychee/out.md
          labels: report, automated issue

Passing arguments

This action uses lychee for link checking. lychee arguments can be passed to the action via the args parameter.

On top of that, the action also supports some additional arguments.

Argument	Examples	Description
args	--cache, --insecure	See lychee's documentation for all arguments and values
debug	false	Enable debug output in action (set -x). Helpful for troubleshooting
fail	false	Fail workflow run on error (i.e. when lychee exit code is not 0)
failIfEmpty	false	Fail entire pipeline if no links were found
format	markdown, json	Summary output format
jobSummary	false	Write GitHub job summary (on Markdown output only)
lycheeVersion	v0.15.0, nightly	Overwrite the lychee version to be used
output	lychee/results.md	Summary output file path
cache	true	Enable lychee's request cache and persist it with GitHub Actions cache
cachePath	.lycheecache	Cache file path, relative to workingDirectory
token	""	Custom GitHub token to use for API calls
workingDirectory	., path/to/subdir/	Custom working directory to run lychee in. This affects where output.md gets created.

See action.yml for a full list of supported arguments and their default values.

Passing arguments

Here is how to pass the arguments.

- name: Link Checker
  uses: lycheeverse/lychee-action@v2
  with:
    # Check all markdown, html and reStructuredText files in repo (default)
    args: --root-dir "$(pwd)" --verbose --no-progress './**/*.md' './**/*.html' './**/*.rst'
    # Use json as output format (instead of markdown)
    format: json
    # Use different output file path
    output: /tmp/foo.txt
    # Use a custom GitHub token, which
    token: ${{ secrets.CUSTOM_TOKEN }}
    # Don't fail action on broken links
    fail: false
    # Run lychee in a different directory.
    # Note: This changes the lychee output directory as well.
    workingDirectory: website/subdir

(If you need a token that requires permissions that aren't available in the default GITHUB_TOKEN, you can create a personal access token and pass it to the action via the token parameter.)

Using the cache feature

To reduce rate limiting and avoid repeated checks against the same URLs, enable the built-in cache:

- name: Run lychee
  uses: lycheeverse/lychee-action@v2
  with:
    cache: true
    args: --root-dir "$(pwd)" --max-cache-age 1d .

This turns on lychee's request cache and stores the cache file with GitHub Actions cache. By default, the cache lives at .lycheecache relative to workingDirectory. Use cachePath to choose a different relative path:

- name: Run lychee
  uses: lycheeverse/lychee-action@v2
  with:
    cache: true
    cachePath: website/.lycheecache

When cache: true is set, don't also pass --cache or --cache-path in args; the action adds the lychee cache flag for you. If you prefer to manage caching yourself, leave cache disabled and pass lychee's cache flags manually.

For custom cache keys or finer control over restore and save behavior, use actions/cache directly:

- name: Restore lychee cache
  id: restore-cache
  uses: actions/cache/restore@v6
  with:
    path: .lycheecache
    key: cache-lychee-${{ github.sha }}
    restore-keys: cache-lychee-

- name: Run lychee
  uses: lycheeverse/lychee-action@v2
  with:
    args: --root-dir "$(pwd)" --cache --max-cache-age 1d .

- name: Save lychee cache
  uses: actions/cache/save@v6
  if: steps.restore-cache.outputs.cache-hit != 'true' && !cancelled()
  with:
    path: .lycheecache
    key: ${{ steps.restore-cache.outputs.cache-primary-key }}

Excluding links from getting checked

Add a .lycheeignore file to the root of your repository to exclude links from getting checked. It supports regular expressions. One expression per line.

You can also put your .lycheeignore into a subdirectory if you set that as the workingDirectory.

Fancy badge

Pro tip: You can add a little badge to your repo to show the status of your links. Just replace org with your organisation name and repo with the repository name and put it into your README.md:

[![Check Links](https://github.com/org/repo/actions/workflows/links.yml/badge.svg)](https://github.com/org/repo/actions/workflows/links.yml)

It will look like this:

Troubleshooting and common problems

See lychee's Troubleshooting Guide for solutions to common link-checking problems.

Performance

A full CI run to scan 576 links takes approximately 1 minute for the analysis-tools-dev/static-analysis repository.

Security and Updates

It is recommended to pin lychee-action to a fixed version for security reasons. You can use dependabot to automatically keep your GitHub actions up-to-date. This is a great way to pin lychee-action, while still receiving updates in the future. It's a relatively easy thing to do.

Create a file named .github/dependabot.yml with the following contents:

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: ".github/workflows"
    schedule:
      interval: "daily"

When you add or update the dependabot.yml file, this triggers an immediate check for version updates. Please see the documentation for all configuration options.

Security tip

For additional security when relying on automation to update actions you can pin the action to a SHA-256 rather than the semver version so as to avoid tag spoofing Dependabot will still be able to automatically update this.

For example:

- name: Link Checker
  uses: lycheeverse/lychee-action@7da8ec1fc4e01b5a12062ac6c589c10a4ce70d67 # for v2.0.0

Credits

This action is based on the deprecated peter-evans/link-checker and uses lychee (written in Rust) instead of liche (written in Go) for link checking.

License

lychee is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.