Skip to main content

linkinator-action

A happy little GitHub Action that checks your README.md and other markdown for broken links. Uses linkinator under the hood.

linkinator-action

GitHub Repository

📦 Source Code: github.com/JustinBeckwith/linkinator-action

View the source code, report issues, and contribute to the project.

Linkinator Action brings powerful link validation to your GitHub workflows. Automatically scan markdown files, documentation, and entire websites for broken links during CI/CD, ensuring your links stay healthy across pull requests and deployments.

Features​

  • 🔥 Automatically scan README.md and markdown files
  • 🔥 Works on push and pull request events
  • 🔥 Recursive crawling for comprehensive link checking
  • 🔥 Skip specific URLs with regex patterns
  • 🔥 Validate URL fragments and anchors
  • 🔥 Check links in CSS files and styles
  • 🔥 Custom retry logic for flaky endpoints
  • 🔥 HTTPS enforcement options
  • 🔥 Extensive configuration options

Basic Usage​

With no arguments, this will scan your README.md in the root of the repository:

on:
  push:
    branches:
      - main
  pull_request:
name: ci
jobs:
  linkinator:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: JustinBeckwith/linkinator-action@v2

Advanced Configuration​

Pass many of the same parameters that linkinator provides:

on:
  push:
    branches:
      - main
  pull_request:
name: ci
jobs:
  linkinator:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: JustinBeckwith/linkinator-action@v2
        with:
          paths: "docs/**/*.md"
          recurse: true
          markdown: true
          linksToSkip: "http://fake.local, http://fake.local/fake"
          concurrency: 50

Enable all validation features for thorough link checking:

- uses: JustinBeckwith/linkinator-action@v2
  with:
    paths: "**/*.md"
    recurse: true
    checkFragments: true
    checkCss: true
    requireHttps: true
    retry: true
    retryErrors: true

Configuration Options​

Scanning​

  • paths - Paths to scan for 404s. Defaults to *.md.
  • config - Path to a config file to use. Looks for linkinator.config.json by default.
  • recurse - Recursively follow links on the same root domain. Defaults to false.
  • markdown - Automatically parse and scan markdown files. Defaults to true.
  • concurrency - Number of simultaneous connections. Defaults to 100.
  • checkFragments - Validate fragment identifiers (anchor links) on HTML pages. Defaults to false.
  • checkCss - Parse and extract URLs from CSS files and styles. Defaults to false.
  • linksToSkip - List of URLs in regex form to skip (also accepts skip).
  • requireHttps - Require all links to use HTTPS. Defaults to false.

Network & Retry​

  • timeout - Request timeout in milliseconds. Defaults to 0 (no timeout).
  • retry - Automatically retry HTTP 429 responses with retry-after header. Defaults to false.
  • retryErrors - Automatically retry 5xx or network errors. Defaults to false.
  • retryErrorsCount - Number of times to retry errors. Defaults to 3.
  • retryErrorsJitter - Maximum jitter in milliseconds for retry delays. Defaults to 2000.

Advanced​

  • serverRoot - Customize server location when scanning local directories.
  • directoryListing - Include automatic directory index when linking to directories. Defaults to false.
  • allowInsecureCerts - Allow insecure certificates for local development. Defaults to false.
  • cleanUrls - Enable extensionless URL support for modern static hosting. Defaults to false.
  • userAgent - Custom User-Agent header for requests.
  • urlRewriteSearch - Pattern to search in URLs (use with urlRewriteReplace).
  • urlRewriteReplace - Replacement expression (use with urlRewriteSearch).
  • verbosity - Control output verbosity: DEBUG, INFO, WARNING, ERROR, or NONE. Defaults to WARNING.

Outputs​

  • results - An object containing the scan results and link validation data.

Example Workflows​

Scan Documentation on Pull Requests​

on:
  pull_request:
    paths:
      - 'docs/**'
name: docs-validation
jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: JustinBeckwith/linkinator-action@v2
        with:
          paths: "docs/**/*.md"
          recurse: true
- uses: JustinBeckwith/linkinator-action@v2
  with:
    paths: "."
    recurse: true
    checkFragments: true
    requireHttps: true
    verbosity: "INFO"
- uses: JustinBeckwith/linkinator-action@v2
  with:
    paths: "README.md"
    linksToSkip: "https://external-site.com, ^https://twitter.com"

Debugging​

To view skipped links, failure details, and more debugging information, enable step debug logging in your GitHub Actions workflow.

License​

MIT