Skip to main content
The action-linkspector GitHub Action provides seamless integration with GitHub workflows, featuring automated PR comments via reviewdog.

​
Quick Start

1

Add workflow file

Create .github/workflows/linkspector.yml in your repository:
.github/workflows/linkspector.yml
name: Check Links

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  linkspector:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Linkspector
        uses: UmbrellaDocs/action-linkspector@v1
2

Add configuration

Create .linkspector.yml in your repository root:
.linkspector.yml
dirs:
  - ./docs
  - ./README.md
useGitIgnore: true
aliveStatusCodes:
  - 200
  - 201
  - 204
3

Commit and push

The workflow will automatically run on pull requests and pushes to main.

​
Integration with Reviewdog

The action uses reviewdog to post link check results directly as PR review comments.

​
Complete Example with PR Comments

.github/workflows/linkspector.yml
name: Link Checker

on:
  pull_request:

jobs:
  linkspector:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Check links with reviewdog
        uses: UmbrellaDocs/action-linkspector@v1
        with:
          config_file: '.linkspector.yml'
          reporter: 'github-pr-review'
          fail_on_error: 'true'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
The GITHUB_TOKEN is automatically provided by GitHub Actions. The pull-requests: write permission allows reviewdog to comment on pull requests.

​
Action Inputs

InputDescriptionRequiredDefault
config_filePath to Linkspector configuration fileNo.linkspector.yml
reporterReviewdog reporter typeNogithub-pr-review
fail_on_errorFail workflow if broken links foundNotrue
filter_modeReviewdog filter modeNoadded
github_tokenGitHub token for API accessNo${{ github.token }}

​
Workflow Triggers

​
On Pull Requests Only

Check links only when PRs are opened or updated: 
on:
  pull_request:
    types: [opened, synchronize, reopened]

​
On Push to Specific Branches

on:
  push:
    branches:
      - main
      - develop
      - 'release/**'

​
On Schedule

Run periodic link checks to catch external links that break over time: 
on:
  schedule:
    # Run every Monday at 9:00 AM UTC
    - cron: '0 9 * * 1'
  workflow_dispatch: # Allow manual trigger

​
Combined Triggers

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: '0 9 * * 1'
  workflow_dispatch:

​
Advanced Configurations

​
Check Only Modified Files

Optimize PR checks by only validating changed files:
.linkspector.yml
dirs:
  - ./docs
modifiedFilesOnly: true
useGitIgnore: true

name: Check Changed Links

on:
  pull_request:

jobs:
  linkspector:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2  # Need previous commit for diff
          
      - uses: UmbrellaDocs/action-linkspector@v1

​
Using Custom Reporters

Reviewdog supports multiple reporter types: 
- name: Check links (PR comments)
  uses: UmbrellaDocs/action-linkspector@v1
  with:
    reporter: 'github-pr-review'  # Inline PR comments

- name: Check links (Check annotations)
  uses: UmbrellaDocs/action-linkspector@v1
  with:
    reporter: 'github-check'  # GitHub Check annotations

- name: Check links (PR status)
  uses: UmbrellaDocs/action-linkspector@v1
  with:
    reporter: 'github-pr-check'  # PR status check

​
Matrix Strategy for Multiple Directories

Check different documentation sets in parallel: 
jobs:
  linkspector:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        docs:
          - path: 'docs/user-guide'
            config: '.linkspector.user.yml'
          - path: 'docs/api-reference'
            config: '.linkspector.api.yml'
          - path: 'docs/tutorials'
            config: '.linkspector.tutorials.yml'
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Check ${{ matrix.docs.path }}
        uses: UmbrellaDocs/action-linkspector@v1
        with:
          config_file: ${{ matrix.docs.config }}

​
Using Secrets for Authentication

Access protected APIs with authentication tokens:
1

Add secret to repository

Go to Settings → Secrets and variables → Actions → New repository secretAdd API_AUTH_TOKEN with your token value.
2

Reference in configuration

.linkspector.yml
dirs:
  - ./docs
httpHeaders:
  - url:
      - https://api.example.com
    headers:
      Authorization: ${API_AUTH_TOKEN}
3

Pass secret to action

- uses: UmbrellaDocs/action-linkspector@v1
  env:
    API_AUTH_TOKEN: ${{ secrets.API_AUTH_TOKEN }}

​
Permissions Configuration

​
Minimal Permissions

For basic link checking without PR comments: 
jobs:
  linkspector:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    
    steps:
      - uses: actions/checkout@v4
      - uses: UmbrellaDocs/action-linkspector@v1
        with:
          reporter: 'github-check'

​
Full Permissions for PR Integration

For PR comments and annotations: 
jobs:
  linkspector:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      checks: write

​
Filtering Results

Control which findings are reported: 
- uses: UmbrellaDocs/action-linkspector@v1
  with:
    filter_mode: 'added'      # Only new issues in PR diff
    # filter_mode: 'diff_context'  # Issues in modified lines + context
    # filter_mode: 'file'          # All issues in modified files
    # filter_mode: 'nofilter'      # All issues in repository

​
Handling Errors

​
Continue on Error

Run workflow even if broken links are found: 
- name: Check links
  uses: UmbrellaDocs/action-linkspector@v1
  with:
    fail_on_error: 'false'
  continue-on-error: true

- name: Upload results
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: linkspector-results
    path: linkspector-output.json

​
Separate Check and Report Steps

- name: Run Linkspector
  id: linkspector
  run: |
    npm install -g @umbrelladocs/linkspector
    linkspector check -j > results.json || true

- name: Report with Reviewdog
  uses: reviewdog/action-setup@v1
  with:
    reviewdog_version: latest

- name: Post results
  run: |
    cat results.json | reviewdog -f=rdjson -reporter=github-pr-review
  env:
    REVIEWDOG_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}

​
Example Workflows

​
Documentation Site

.github/workflows/docs-links.yml
name: Documentation Links

on:
  pull_request:
    paths:
      - 'docs/**'
      - '.linkspector.yml'
  push:
    branches: [main]
    paths:
      - 'docs/**'

jobs:
  check-docs:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      
      - name: Check documentation links
        uses: UmbrellaDocs/action-linkspector@v1
        with:
          config_file: '.linkspector.yml'
          reporter: 'github-pr-review'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

​
Multi-Language Documentation

.github/workflows/i18n-links.yml
name: I18n Documentation Links

on:
  pull_request:

jobs:
  check-links:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        locale: [en, es, fr, de, ja]
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Check ${{ matrix.locale }} links
        uses: UmbrellaDocs/action-linkspector@v1
        with:
          config_file: '.linkspector.${{ matrix.locale }}.yml'

​
Troubleshooting

Ensure your workflow has the necessary permissions:
permissions:
  contents: read
  pull-requests: write
  1. Verify GITHUB_TOKEN is passed to the action
  2. Check that pull-requests: write permission is granted
  3. Ensure the workflow is triggered by pull_request event
Add path filters to only run on relevant changes:
on:
  pull_request:
    paths:
      - 'docs/**'
      - '*.md'
GitHub Actions has a 6-hour timeout limit. For large repos:
  1. Enable modifiedFilesOnly: true
  2. Use matrix strategy to split work
  3. Add problematic URLs to ignorePatterns

​
Action Repository

For more details, visit the action-linkspector repository on GitHub Marketplace.

​
Next Steps

CI/CD Integration

Learn about general CI/CD integration patterns

Docker

Run Linkspector in Docker containers

Build docs developers (and LLMs) love

Get started for freeTalk to us