genai-toolbox/.github/workflows/link_checker_workflow.yaml

# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
name: Link Checker

on:
  pull_request:


jobs:
  link-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6

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

      - name: Link Checker
        uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2
        with:
          args: >
            --verbose
            --no-progress
            --cache
            --max-cache-age 1d
            --exclude '^neo4j\+.*' --exclude '^bolt://.*'
            README.md
            docs/
          output: /tmp/foo.txt
          fail: true
          jobSummary: true
          debug: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # This step only runs if the 'lychee_check' step fails, ensuring the 
      # context note only appears when the developer needs to troubleshoot.
      - name: Display Link Context Note on Failure
        if: ${{ failure() }}
        run: |
          echo "## Link Resolution Note" >> $GITHUB_STEP_SUMMARY
          echo "Local links and directory changes work differently on GitHub than on the docsite." >> $GITHUB_STEP_SUMMARY
          echo "You must ensure fixes pass the **GitHub check** and also work with **\`hugo server\`**." >> $GITHUB_STEP_SUMMARY
          echo "---" >> $GITHUB_STEP_SUMMARY