From a57f2ef42df8def107933460f52bbbb695de135d Mon Sep 17 00:00:00 2001
From: Charlie Egan <charlie_egan@apple.com>
Date: Tue, 7 Apr 2026 15:05:44 +0100
Subject: [PATCH] cicd: Split link checker into docs & repo checks (#8492)

We have fixed most of the broken links! But,
https://github.com/open-policy-agent/opa/issues/8464 is mostly not useful now
as we are checking the docs site internal links which are already checked at
build time which is done in PRs.

This change makes two jobs, one for the repo, and one for the docs site. The
OPA domain is ignored for website checks.

Signed-off-by: Charlie Egan <charlie_egan@apple.com>
---
 .github/workflows/link-checker.yaml | 50 +++++++++++++++++------------
 build/lychee/repo.toml              | 17 ++++++++++
 build/lychee/website.toml           | 28 ++++++++++++++++
 3 files changed, 75 insertions(+), 20 deletions(-)
 create mode 100644 build/lychee/repo.toml
 create mode 100644 build/lychee/website.toml

diff --git a/.github/workflows/link-checker.yaml b/.github/workflows/link-checker.yaml
index c55e699e53..d2fb3eef62 100644
--- a/.github/workflows/link-checker.yaml
+++ b/.github/workflows/link-checker.yaml
@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   linkChecker:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     permissions:
       issues: write # required for peter-evans/create-issue-from-file
     steps:
@@ -19,36 +19,46 @@ jobs:
       with:
         persist-credentials: false
 
-    - name: Link Checker
+    - name: Build docs
+      run: make docs-install docs-build
+
+    - name: Link Checker (Docs Site)
+      id: lychee-docs
+      uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
+      with:
+        args: --config build/lychee/website.toml --root-dir ${{ github.workspace }}/docs/build docs/build
+        fail: false
+        output: lychee/docs-out.md
+
+    - name: Link Checker (Repository)
       id: lychee
       uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411 # v2.8.0
       # ignored domains are a source of false positives in
       # https://github.com/open-policy-agent/opa/issues/7888 for example
       with:
-        args: >
-          --max-concurrency 1
-          --no-progress
-          --exclude-path vendor
-          --exclude-path internal
-          --exclude-path CHANGELOG.md
-          --scheme https
-          --scheme http
-          --exclude medium.com
-          --exclude blog.openpolicyagent.org
-          --exclude itnext.io
-          --accept 200..=206,403,429
-          --retry-wait-time 5
-          --max-retries 1
-          .
+        args: --config build/lychee/repo.toml .
         fail: false
+        output: lychee/repo-out.md
+
+    - name: Combine Reports
+      run: |
+        {
+          echo "# Link Checker Report"
+          echo ""
+          echo "## Docs Site"
+          cat lychee/docs-out.md
+          echo ""
+          echo "## Repository"
+          cat lychee/repo-out.md
+        } > lychee/combined-out.md
 
     - name: Show Report
-      run: cat lychee/out.md
+      run: cat lychee/combined-out.md
 
     - name: Create Issue From File
-      if: steps.lychee.outputs.exit_code != 0
+      if: steps.lychee-docs.outputs.exit_code != 0 || steps.lychee.outputs.exit_code != 0
       uses: peter-evans/create-issue-from-file@fca9117c27cdc29c6c4db3b86c48e4115a786710 # v6.0.0
       with:
         title: "docs: Link Checker Report"
-        content-filepath: ./lychee/out.md
+        content-filepath: ./lychee/combined-out.md
         labels: report, automated issue
diff --git a/build/lychee/repo.toml b/build/lychee/repo.toml
new file mode 100644
index 0000000000..99188bda53
--- /dev/null
+++ b/build/lychee/repo.toml
@@ -0,0 +1,17 @@
+# Lychee configuration for checking the repository (excluding docs/)
+
+no_progress = true
+max_concurrency = 1
+max_retries = 1
+retry_wait_time = 5
+accept = ["200..=206", "403", "429"]
+scheme = ["https", "http"]
+
+exclude_path = [
+    # docs is tested with the website.toml config instead
+    'docs',
+
+    'vendor',
+    'internal',
+    'CHANGELOG\.md',
+]
diff --git a/build/lychee/website.toml b/build/lychee/website.toml
new file mode 100644
index 0000000000..bec756c38c
--- /dev/null
+++ b/build/lychee/website.toml
@@ -0,0 +1,28 @@
+# Lychee configuration for checking the built docs website
+
+no_progress = true
+max_concurrency = 1
+max_retries = 1
+retry_wait_time = 5
+accept = ["200..=206", "403", "429"]
+scheme = ["https", "http"]
+
+# Root dir must be an absolute path, set as CLI arg with --root-dir
+# root_dir = ...
+
+exclude = [
+    # Exclude openpolicyagent.org links in the built site as they're internal links
+    # that are validated at build time by Docusaurus.
+    'openpolicyagent\.org',
+    # These domains block the link checker creating false positives
+    'medium\.com',
+    'blog\.openpolicyagent\.org',
+    'itnext\.io',
+    'stacklok\.com',
+]
+
+exclude_path = [
+    # some libraries contain files that we don't control and so do not need to be
+    # checked
+    'docs/build/assets/js',
+]