.github/workflows/check-links.yml

# Copyright (c) 2024-2026, The UW Lab Project Developers. (https://github.com/uw-lab/UWLab/blob/main/CONTRIBUTORS.md).
# All Rights Reserved.
#
# SPDX-License-Identifier: BSD-3-Clause

name: Check Documentation Links

on:
  # Run on pull requests that modify documentation
  pull_request:
    paths:
      - 'docs/**'
      - '**.md'
      - '.github/workflows/check-links.yml'
  # Run on pushes to main branches
  push:
    branches:
      - main
      - devel
      - 'release/**'
    paths:
      - 'docs/**'
      - '**.md'
      - '.github/workflows/check-links.yml'
  # Allow manual trigger
  workflow_dispatch:
  # Run weekly to catch external links that break over time
  schedule:
    - cron: '0 0 * * 0'  # Every Sunday at midnight UTC

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  check-links:
    name: Check for Broken Links
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4
      with:
        fetch-depth: 0

    - name: Restore lychee cache
      uses: actions/cache@v4
      with:
        path: .lycheecache
        key: cache-lychee-${{ github.sha }}
        restore-keys: cache-lychee-

    - name: Run Link Checker
      uses: lycheeverse/lychee-action@v2
      with:
        # Check all markdown files and documentation
        args: >-
          --verbose
          --no-progress
          --cache
          --max-cache-age 1d
          --exclude-path './docs/_build'
          --exclude-path './apps/warp-*'
          --exclude-path './logs'
          --exclude-path './outputs'
          --exclude-loopback
          --exclude '^file://'
          --exclude '^mailto:'
          --exclude 'localhost'
          --exclude '127\.0\.0\.1'
          --exclude 'example\.com'
          --exclude 'your-organization'
          --exclude 'YOUR_'
          --exclude 'yourdomain'
          --exclude 'user@'
          --exclude 'helm\.ngc\.nvidia\.com'
          --exclude 'slurm\.schedmd\.com'
          --max-retries 3
          --retry-wait-time 5
          --timeout 30
          --accept 200,201,202,203,204,206,301,302,303,307,308,429
          --scheme https
          --scheme http
          '*.md'
          '**/*.md'
          'docs/**/*.rst'
          'docs/**/*.html'
        # Output results to a file
        output: ./lychee-output.md
        # Fail action on broken links
        fail: true
        # Optional: Use GitHub token for authenticated requests (higher rate limit)
        token: ${{ secrets.GITHUB_TOKEN }}

    - name: Print results to logs
      if: always()
      run: |
        echo "========================================"
        echo "Link Checker Results:"
        echo "========================================"
        if [ -f ./lychee-output.md ]; then
          cat ./lychee-output.md
          echo ""
          echo "========================================"

          # Also add to GitHub step summary for easy viewing
          echo "## Link Checker Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          cat ./lychee-output.md >> $GITHUB_STEP_SUMMARY
        else
          echo "No output file generated"
          echo "========================================"
        fi

    - name: Fail job if broken links found
      if: failure()
      run: |
        echo "❌ Broken links were found in the documentation!"
        echo "Please review the link checker report above and fix all broken links."
        exit 1