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.
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
steps:
- uses: actions/checkout@v3
- name: Link Checker
id: lychee
uses: lycheeverse/[email protected]
- name: Create Issue From File
if: env.lychee_exit_code != 0
uses: peter-evans/create-issue-from-file@v4
with:
title: Link Checker Report
content-filepath: ./lychee/out.md
labels: report, automated issue
If you always want to use the latest features but avoid breaking changes, you can replace the version with
lycheeverse/lychee-action@v1
.
Alternative approach:
This will check all repository links during any git push event and for all pull
requests. If there's an error, it will fail the action. This has the benefit of
ensuring that during a Pull Request, no link is added that is broken and any
existing link will be caught if they become broken. Save this under
.github/workflows/links-fail-fast.yml
:
name: Links (Fail Fast)
on:
push:
pull_request:
jobs:
linkChecker:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Link Checker
uses: lycheeverse/[email protected]
with:
fail: true
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). |
format | markdown , json |
Summary output format. |
jobSummary | false |
Write GitHub job summary (on Markdown output only). |
lycheeVersion | 0.13.0 |
Overwrite the lychee version to be used. |
output | lychee/results.md |
Summary output file path. |
token | "" |
Custom GitHub token to use for API calls. |
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/[email protected]
with:
# Check all markdown and html files in repo (default)
args: --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 }}
# Fail action on broken links
fail: true
(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.)
Utilising the cache feature
In order to mitigate issues regarding rate limiting or to reduce stress on external resources, one can setup lychee's cache similar to this:
- name: Restore lychee cache
uses: actions/cache@v3
with:
path: .lycheecache
key: cache-lychee-${{ github.sha }}
restore-keys: cache-lychee-
- name: Run lychee
uses: lycheeverse/[email protected]
with:
args: "--cache --max-cache-age 1d ."
It will compare and save the cache based on the given key. So in this setup, as long as a user triggers the CI run from the same commit, it will be the same key. The first run will save the cache, subsequent runs will not update it (because it's the same commit hash). For restoring the cache, the most recent available one is used (commit hash doesn't matter).
If you need more control over when caches are restored and saved, you can split the cache step and e.g. ensure to always save the cache (also when the link check step fails):
- name: Restore lychee cache
id: restore-cache
uses: actions/cache/restore@v3
with:
path: .lycheecache
key: cache-lychee-${{ github.sha }}
restore-keys: cache-lychee-
- name: Run lychee
uses: lycheeverse/[email protected]
with:
args: "--cache --max-cache-age 1d ."
- name: Save lychee cache
uses: actions/cache/save@v3
if: always()
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.
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@ec7614d7605b47efb08dc370f6d0a71884cba944 # for v1.8.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
at your option.