Check Links in Pull Requests

This recipe shows how to check for broken links in pull requests. It only checks newly added links by comparing against the base branch, reducing noise from existing broken links.

The workflow is triggered on pull request events against the main branch. It clones the repository and checks out the main branch to dump all links. It then stashes untracked files and checks out the feature branch. The stashed changes are applied and the links from the main branch are appended to the .lycheeignore file. Finally, the links in the feature branch are checked and suggestions are provided if the check fails.

Note

Discussion on GitHub

.github/workflows/check-pr-links.yml

name: PR Links

on:
  pull_request:
    branches: [master]
  workflow_dispatch:

jobs:
  linkChecker:
    runs-on: ubuntu-latest
    steps:
      - name: Clone repository
        uses: actions/checkout@v5
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: "20"

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: latest

      - name: Check out master branch
        run: git checkout master

      - name: Install dependencies for master
        run: pnpm install --frozen-lockfile

      - name: Build site from master
        run: pnpm build

      - name: Dump all links from master
        id: dump_links_from_master
        uses: lycheeverse/lychee-action@v2
        with:
          args: --dump --base-url dist --exclude-all-private dist
          output: ./links-master.txt

      - name: Stash untracked files
        run: git stash push --include-untracked

      - name: Check out feature branch
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            git checkout ${{ github.head_ref }}
          else
            git checkout ${{ github.ref_name }}
          fi

      - name: Apply stashed changes
        run: git stash pop || true

      - name: Install dependencies for feature branch
        run: pnpm install --frozen-lockfile

      - name: Build site from feature branch
        run: pnpm build

      - name: Append links-master.txt to .lycheeignore
        run: cat links-master.txt >> .lycheeignore

      - name: Check links in PR changes
        uses: lycheeverse/lychee-action@v2
        with:
          args: --base-url dist --exclude-all-private dist
          fail: true

      - name: Suggestions
        if: failure()
        run: |
          echo -e "\nPlease review the links reported in the 'Check links in PR changes' step above."
          echo -e "If a link is valid but fails due to a CAPTCHA challenge, IP blocking, login requirements, etc.,"
          echo -e "consider adding such links to .lycheeignore file to bypass future checks.\n"
          exit 1