check-links.yml

Run a lychee link check with a bundled config, a PR skip-label, and an auto-filed issue when links break on main.

Inputs

Input	Type	Default	Description
lychee-config	string	''	Path in the caller repo to a lychee config; falls back to the bundled default.
lychee-args	string	''	Arguments and globs passed to lychee; a sensible default glob set is used when empty.
fail-if-empty	boolean	false	Fail the run when no links are found.
create-issue-on-main	boolean	true	File an issue when links break on the main branch.
skip-label	string	'links checked by hand'	PR label that skips the link check.

Permissions

Grant issues: write, pull-requests: read, and contents: read (it opens an issue on main failures).

Example

# Copy to .github/workflows/check-links.yml in your repo.
# NOTE: the calling job grants issues:write so the workflow can open an issue
# when links break on main. Required because repos default to a read-only token.
name: Check Links

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
  schedule:
    # Run weekly on Mondays at 9:00 UTC to catch link rot
    - cron: "0 9 * * 1"
  workflow_dispatch:

jobs:
  check:
    permissions:
      contents: read
      issues: write
      pull-requests: read
    uses: Morrison-Lab/gha/.github/workflows/check-links.yml@v2
    # with:
    #   lychee-config: lychee.toml       # use a repo-local config instead of the bundled default
    #   fail-if-empty: true              # fail when no links are found (default: false)
    #   create-issue-on-main: true
    #   skip-label: 'links checked by hand'

See examples/check-links.yml for the full caller stub.