check-links.yml

name: Check Links

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, labeled, unlabeled]
  schedule:
    # Run weekly on Mondays at 9:00 UTC to catch link rot
    - cron: '0 9 * * 1'
  workflow_dispatch:

jobs:
  link-checker:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
      pull-requests: read
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Check for manual override label
        id: check-label
        if: github.event_name == 'pull_request'
        run: |
          LABEL_EXISTS=$(gh pr view "${{ github.event.pull_request.number }}" --json labels --jq 'if (.labels[].name | select(. == "links checked by hand")) then "true" else "false" end')
          echo "skip=$LABEL_EXISTS" >> "$GITHUB_OUTPUT"
          if [ "$LABEL_EXISTS" = "true" ]; then
            echo "Manual override enabled: 'links checked by hand' label found"
          fi
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Skip message
        if: github.event_name == 'pull_request' && steps.check-label.outputs.skip == 'true'
        run: |
          echo "::notice::Links check skipped - 'links checked by hand' label present on PR"

      - name: Check links in markdown and HTML files
        id: lychee
        if: github.event_name != 'pull_request' || steps.check-label.outputs.skip != 'true'
        uses: lycheeverse/lychee-action@v2
        with:
          # Check all .qmd (Quarto markdown), .md (markdown), and .html files
          args: --verbose --no-progress --config lychee.toml './**/*.qmd' './**/*.md' './**/*.html'
          # Fail action on broken links
          fail: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Create issue on main branch if links are broken
        if: failure() && github.ref == 'refs/heads/main'
        run: |
          # Create issue with broken link details
          BODY=$(cat <<'EOF'
          The link checker found broken links in the main branch.

          **Workflow Run:** ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}

          Please review the workflow logs above for details on which links are broken.

          This issue was automatically created by the link checker workflow.

          @copilot please fix the broken links found in the main branch.
          EOF
          )
          gh issue create \
            --title "Broken links detected in main branch" \
            --body "$BODY" \
            --label "bug,automated,copilot"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}