check-external-links.yml

name: Check External Links

on:
  pull_request:
    branches:
      - main
    paths:
      - "docs/**"
      - ".github/workflows/check-external-links.yml"

jobs:
  check-external-links:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v6
      - name: Restore lychee cache
        uses: actions/cache@v5
        with:
          path: .lycheecache
          key: cache-lychee-${{ hashFiles('lychee.toml') }}
          restore-keys: cache-lychee-
      - name: Link Checker
        id: lychee
        uses: lycheeverse/lychee-action@v2
        continue-on-error: true
        with:
          lycheeVersion: "latest"
          args: |
            --config lychee.toml
            docs
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Prepare broken link report
        id: lychee_report
        if: ${{ steps.lychee.outputs.exit_code && steps.lychee.outputs.exit_code != '0' }}
        shell: bash
        run: |
          report_file="lychee/out.md"
          if [[ ! -s "$report_file" ]]; then
            echo "report<<EOF" >> "$GITHUB_OUTPUT"
            echo "Lychee detected broken links, but the report file (\`$report_file\`) was empty or missing." >> "$GITHUB_OUTPUT"
            echo "EOF" >> "$GITHUB_OUTPUT"
            exit 0
          fi

          echo "report<<EOF" >> "$GITHUB_OUTPUT"
          cat "$report_file" >> "$GITHUB_OUTPUT"
          echo "EOF" >> "$GITHUB_OUTPUT"
      - name: Comment on PR if broken links found
        if: ${{ steps.lychee.outputs.exit_code && steps.lychee.outputs.exit_code != '0' }}
        uses: thollander/actions-comment-pull-request@v3
        with:
          message: |
            ### 🚨 Broken links detected
            <details>
            <summary>Click to expand</summary>

            ${{ steps.lychee_report.outputs.report }}
            </details>
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - name: Fail if broken links found
        if: ${{ failure() || (steps.lychee.outputs.exit_code && steps.lychee.outputs.exit_code != '0') }}
        run: exit 1