Quickly check links in Markdown, HTML, and text files using lychee.
When used in conjunction with Create Issue From File, issues will be created when the action finds link problems.
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@v2
- name: Link Checker
id: lychee
uses: lycheeverse/lychee-action@v1.3.2
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
- name: Create Issue From File
if: ${{ steps.lychee.outputs.exit_code != 0 }}
uses: peter-evans/create-issue-from-file@v3
with:
title: Link Checker Report
content-filepath: ./lychee/out.md
labels: report, automated issue
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@v2
- name: Link Checker
uses: lycheeverse/lychee-action@v1.3.2
with:
fail: true
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
This action uses lychee for link checking.
lychee arguments can be passed to the action via the args
parameter.
On top of that, some other inputs are supported: format
, output
, and fail
.
- name: Link Checker
uses: lycheeverse/lychee-action@v1.3.2
with:
# Check all markdown and html files in repo (default)
args: --verbose --no-progress './**/*.md' './**/*.html'
# Use json as output format (instead of markdown)
format: json
# Use different output filename
output: /tmp/foo.txt
# Fail action on broken links
fail: true
See lychee's documentation for all possible arguments.
Add a .lycheeignore
file to the root of your repository to exclude links from
getting checked. It supports regular expressions. One expression per line.
Issues with links will be written to a file containing the error report.
The default path is lychee/out.md
. The path and filename may be overridden with the following variable:
LYCHEE_OUT
- The path to the output file for the Markdown error report
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:
See lychee's Troubleshooting Guide for solutions to common link-checking problems.
A full CI run to scan 576 links takes approximately 1 minute for the analysis-tools-dev/static-analysis repository.
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.
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@cb79c9607b37671965f8dbb54cae47795758a440 #1.1.1
#...
This action is based on peter-evans/link-checker and uses lychee (written in Rust) instead of liche (written in Go) for link checking. For a comparison of both tools, check out this comparison table.
lychee is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)
at your option.