Skip to main content
Linkspector is purposefully designed for CI/CD environments, making it easy to automate link checking as part of your development workflow.

​
Exit Codes

Linkspector uses standard exit codes to communicate the check results:
  • Exit 0: All links are valid
  • Exit 1: Errors occurred (broken links found or configuration errors)
These exit codes allow CI/CD systems to automatically fail builds when broken links are detected.

​
RDJSON Output Format

Linkspector supports RDJSON (Reviewdog Diagnostic Format) output, which is ideal for CI/CD integration. This format is automatically validated and fixed using the @umbrelladocs/rdformat-validator package.

​
Enabling JSON Output

Use the -j or --json flag to output results in RDJSON format: 
linkspector check -j

​
RDJSON Structure

The output follows this structure: 
{
  "source": {
    "name": "linkspector",
    "url": "https://github.com/UmbrellaDocs/linkspector"
  },
  "severity": "ERROR",
  "diagnostics": [
    {
      "message": "Cannot reach https://example.com/broken Status: 404 Not Found",
      "location": {
        "path": "README.md",
        "range": {
          "start": {
            "line": 42,
            "column": 15
          },
          "end": {
            "line": 42,
            "column": 45
          }
        }
      },
      "severity": "ERROR"
    }
  ]
}

​
When No Errors Are Found

If all links are valid, Linkspector outputs an empty RDJSON structure: 
{
  "source": {
    "name": "linkspector",
    "url": "https://github.com/UmbrellaDocs/linkspector"
  },
  "severity": "ERROR",
  "diagnostics": []
}

​
Integration Patterns

​
Basic CI Check

1

Add configuration file

Create a .linkspector.yml in your repository root:
dirs:
  - ./docs
  - ./
useGitIgnore: true
aliveStatusCodes:
  - 200
  - 201
  - 204
2

Add check command to CI

Add Linkspector check to your CI script:
npm install -g @umbrelladocs/linkspector
linkspector check
3

Handle exit codes

The CI system will automatically fail if broken links are found (exit code 1).

​
Check Only Modified Files

Optimize CI runtime by checking only files changed in the last commit:
.linkspector.yml
dirs:
  - ./docs
modifiedFilesOnly: true
useGitIgnore: true
This requires git to be installed and available in your CI environment.

​
Using RDJSON with Reviewdog

Combine Linkspector with reviewdog for inline PR comments: 
linkspector check -j | reviewdog -f=rdjson -reporter=github-pr-review

​
CI System Examples

​
Jenkins

Jenkinsfile
pipeline {
  agent any
  
  stages {
    stage('Check Links') {
      steps {
        sh 'npm install -g @umbrelladocs/linkspector'
        sh 'linkspector check'
      }
    }
  }
}

​
GitLab CI

.gitlab-ci.yml
check-links:
  stage: test
  image: node:lts
  script:
    - npm install -g @umbrelladocs/linkspector
    - linkspector check
  only:
    - merge_requests
    - main

​
CircleCI

.circleci/config.yml
version: 2.1

jobs:
  check-links:
    docker:
      - image: cimg/node:lts
    steps:
      - checkout
      - run:
          name: Install Linkspector
          command: npm install -g @umbrelladocs/linkspector
      - run:
          name: Check links
          command: linkspector check

workflows:
  test:
    jobs:
      - check-links

​
Travis CI

.travis.yml
language: node_js
node_js:
  - 'lts/*'

script:
  - npm install -g @umbrelladocs/linkspector
  - linkspector check

​
Advanced Configuration for CI

​
Using Environment Variables

Securely pass authentication tokens for private APIs:
1

Set CI environment variables

Configure AUTH_TOKEN in your CI system’s secrets/environment variables.
2

Reference in configuration

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

Run check

Linkspector automatically replaces ${AUTH_TOKEN} with the environment variable value.

​
Custom Configuration Path

Use different configurations for different environments: 
# Development
linkspector check -c .linkspector.dev.yml

# Production
linkspector check -c .linkspector.prod.yml

​
Statistics Output

View detailed statistics about link checks (cannot be combined with -j): 
linkspector check -s
Output: 
💀📊 Linkspector check stats
┌───────────────────────────────┬────────┐
│ 🟰 Total files checked        │     12 │
├───────────────────────────────┼────────┤
│ 🔗 Total links checked        │    156 │
├───────────────────────────────┼────────┤
│ 🌐 Hyperlinks                 │    134 │
├───────────────────────────────┼────────┤
│ 📁 File and header links      │     22 │
├───────────────────────────────┼────────┤
│ ✉️  Email links (Skipped)      │      0 │
├───────────────────────────────┼────────┤
│ ✅ Working links              │    156 │
├───────────────────────────────┼────────┤
│ 🚫 Failed links               │      0 │
└───────────────────────────────┴────────┘

​
Best Practices

Configure link checking to run on every pull request to catch broken links before they reach your main branch.
Enable modifiedFilesOnly: true in repositories with extensive documentation to improve CI performance.
Cache npm packages in your CI to speed up Linkspector installation.
Consider configuring custom timeout values for CI environments with slower network connections.
Enable useGitIgnore: true to automatically exclude generated or vendor files.

​
Troubleshooting

If external links frequently timeout in CI:
  1. Check your CI environment’s network connectivity
  2. Add problematic domains to ignorePatterns
  3. Consider using followRedirects: true (default) to handle redirects

​
False Positives

Some sites may block automated requests:
.linkspector.yml
ignorePatterns:
  - pattern: '^https://example.com/protected/.*$'

​
Configuration Not Found

If your configuration file is in a non-standard location: 
linkspector check -c path/to/custom-config.yml

​
Next Steps

GitHub Actions

Set up Linkspector with GitHub Actions

Docker

Run Linkspector in Docker containers

Build docs developers (and LLMs) love

Get started for freeTalk to us