GitHub Actions: Dead Link Checker

Catch broken links in CI/CD before they reach production

Add automated broken link detection to your GitHub Actions pipeline. Get native build annotations that appear directly on your pull requests and commits — no extra tools or API keys needed.

What It Looks Like

When broken links are found, GitHub shows annotations like these on your build:

When all links are healthy:

Quick Start

mkdir -p .github/workflows && curl -o .github/workflows/check-links.yml https://51-68-119-197.sslip.io/tools/check-links.ymlCopy

name: Check for broken links

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'  # Weekly on Monday at 6am

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - name: Check for broken links
        run: |
          curl -sSL https://51-68-119-197.sslip.io/tools/check-links.sh | bash -s -- --threshold 0 https://yoursite.comCopy

      - name: Check for broken links
        run: |
          RESULT=$(curl -s "https://51-68-119-197.sslip.io/api/deadlinks?url=https://yoursite.com&mode=quick&format=github")
          echo "$RESULT"Copy

Advanced: Fail Build on Broken Links

Use the threshold parameter to fail your build when too many broken links are found:

name: Check for broken links

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - name: Check for broken links
        run: |
          # threshold=0 means ANY broken link fails the build
          RESULT=$(curl -sf "https://51-68-119-197.sslip.io/api/deadlinks?url=https://yoursite.com&mode=quick&threshold=0&format=github")
          echo "$RESULT"

          # RESULT: FAIL/PASS is appended when threshold is set
          if echo "$RESULT" | grep -q 'RESULT: FAIL'; then
            exit 1
          fiCopy

Check Only Internal or External Links

Focus your check with the check_only parameter:

# Check only internal links (same domain)
curl -s "https://51-68-119-197.sslip.io/api/deadlinks?url=https://yoursite.com&mode=quick&check_only=internal&format=github"

# Check only external links (other domains)
curl -s "https://51-68-119-197.sslip.io/api/deadlinks?url=https://yoursite.com&mode=quick&check_only=external&format=github"Copy

Check GitHub README Links

New in v2.7: Check all links in any public repository's README.md. Uses github=owner/repo instead of url:

name: Check README links

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'

jobs:
  check-readme:
    runs-on: ubuntu-latest
    steps:
      - name: Check README for broken links
        run: |
          RESULT=$(curl -sf "https://51-68-119-197.sslip.io/api/deadlinks?github=${{ github.repository }}&format=github&threshold=0")
          echo "$RESULT"
          if echo "$RESULT" | grep -q 'RESULT: FAIL'; then
            exit 1
          fiCopy

Uses ${{ github.repository }} to automatically use the current repo. Supports main/master branches and README.md/readme.md variants.

API Parameters

Full CI/CD Example with Multiple Sites

name: Link health check

on:
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours
  workflow_dispatch:        # Manual trigger

jobs:
  check-links:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        site:
          - https://yoursite.com
          - https://docs.yoursite.com
          - https://blog.yoursite.com
    steps:
      - name: Check ${{ matrix.site }}
        run: |
          echo "Checking ${{ matrix.site }}..."
          curl -s "https://51-68-119-197.sslip.io/api/deadlinks?url=${{ matrix.site }}&mode=quick&threshold=0&format=github"Copy

Post Results as a PR Comment

Use format=markdown to get a formatted report you can post as a GitHub PR comment:

name: Link check on PR

on:
  pull_request:
    branches: [main]

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - name: Check for broken links
        id: linkcheck
        run: |
          REPORT=$(curl -s "https://51-68-119-197.sslip.io/api/deadlinks?url=https://yoursite.com&mode=quick&threshold=0&format=markdown")
          echo "report<> $GITHUB_OUTPUT
          echo "$REPORT" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Post PR comment
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `${{ steps.linkcheck.outputs.report }}`
            })Copy

The markdown report includes a summary table, broken links detail, redirect chains, and mixed content warnings — all formatted for GitHub rendering.

Add a Status Badge to Your README

Show your project's link health with a live badge. Add this to your README.md:

![Dead Links](https://51-68-119-197.sslip.io/badge/deadlinks?url=https://yoursite.com)Copy

The badge updates on each request and shows:

Live example for example.com

Also available: /badge/seo?url= (SEO score A-F) and /badge/perf?url= (response time).

Complete CI/CD + Badge Setup

Combine automated checking with a README badge for full link health visibility:

name: Check links and update badge

on:
  schedule:
    - cron: '0 6 * * 1'  # Weekly
  workflow_dispatch:

jobs:
  check-links:
    runs-on: ubuntu-latest
    steps:
      - name: Check for broken links
        run: |
          curl -sSL https://51-68-119-197.sslip.io/tools/check-links.sh | bash -s -- --threshold 0 https://yoursite.com

# In your README.md, add:
# ![Link Health](https://51-68-119-197.sslip.io/badge/deadlinks?url=https://yoursite.com)Copy

FAQ