|
| 1 | +# .github/workflows/link-check.yml |
| 2 | +name: Link Checker |
| 3 | + |
| 4 | +# Runs Lychee (link checker) on Markdown / MDX docs. |
| 5 | +# |
| 6 | +# What this workflow does: |
| 7 | +# - Triggers on: |
| 8 | +# - pushes to main |
| 9 | +# - all pull requests |
| 10 | +# - manual runs via "Run workflow" |
| 11 | +# - Scans Markdown / MDX files under: |
| 12 | +# - main/ (Mintlify site branded as "auth0") |
| 13 | +# - auth4genai/ (Mintlify site branded as "auth0-genai") |
| 14 | +# - Respects .lycheeignore in the repo root |
| 15 | +# - Accepts 302 redirects and 429 rate limits as valid |
| 16 | +# - Currently warns on failures instead of failing CI |
| 17 | + |
| 18 | +on: |
| 19 | + push: |
| 20 | + branches: |
| 21 | + - main |
| 22 | + pull_request: |
| 23 | + workflow_dispatch: {} |
| 24 | + |
| 25 | +jobs: |
| 26 | + link-check: |
| 27 | + # This name becomes the check name in the GitHub UI. |
| 28 | + # Examples: |
| 29 | + # Link Checker (auth0) - link-rot |
| 30 | + # Link Checker (auth0-genai) - link-rot |
| 31 | + name: Link Checker (${{ matrix.site.name }}) - link-rot |
| 32 | + runs-on: ubuntu-latest |
| 33 | + |
| 34 | + strategy: |
| 35 | + fail-fast: false |
| 36 | + matrix: |
| 37 | + site: |
| 38 | + # Main Auth0 docs (Mintlify project branded as "auth0") |
| 39 | + - name: auth0 |
| 40 | + path: main |
| 41 | + # Auth0 for AI Agents docs (Mintlify project branded as "auth0-genai") |
| 42 | + - name: auth0-genai |
| 43 | + path: auth4genai |
| 44 | + |
| 45 | + steps: |
| 46 | + # Fetch repository contents so Lychee can scan Markdown / MDX files |
| 47 | + - name: Checkout repo |
| 48 | + uses: actions/checkout@93cb6efe18208431cddfb8368fd83d5badbf9bfd # v5.0.1 |
| 49 | + |
| 50 | + # Run Lychee on the current docs tree from the matrix. |
| 51 | + # |
| 52 | + # Notes on args: |
| 53 | + # - --scheme https |
| 54 | + # Only check HTTPS links. Other schemes (mailto:, file:, etc) are skipped. |
| 55 | + # - --accept 200..=299,302,429 |
| 56 | + # Treat 2xx, 302, and 429 as success. |
| 57 | + # - 302 is common for docs redirects. |
| 58 | + # - 429 is rate limiting that we do not want to treat as "broken". |
| 59 | + # Note: URLs returning 429 should be investigated separately to ensure |
| 60 | + # they are actually functional and not just silently rate-limited. |
| 61 | + # - --exclude-path .vale |
| 62 | + # Skip the .vale directory used for prose linting (if present). |
| 63 | + # - ${{ matrix.site.path }}/**/*.md / .mdx |
| 64 | + # Scope to the docs in the current tree: |
| 65 | + # - main/ when name == auth0 |
| 66 | + # - auth4genai/ when name == auth0-genai |
| 67 | + # |
| 68 | + # Internal routing, API-only endpoints, and other noisy URLs are |
| 69 | + # filtered via .lycheeignore in the repo root. |
| 70 | + - name: Run Lychee on ${{ matrix.site.name }} docs |
| 71 | + id: lychee |
| 72 | + uses: lycheeverse/lychee-action@a8c4c7cb88f0c7386610c35eb25108e448569cb0 # v2.7.0 |
| 73 | + env: |
| 74 | + # Used by Lychee for authenticated GitHub requests to reduce rate limiting. |
| 75 | + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
| 76 | + with: |
| 77 | + args: > |
| 78 | + --verbose |
| 79 | + --no-progress |
| 80 | + --scheme https |
| 81 | + --accept 200..=299,302,429 |
| 82 | + --exclude-path .vale |
| 83 | + ${{ matrix.site.path }}/**/*.md |
| 84 | + ${{ matrix.site.path }}/**/*.mdx |
| 85 | +
|
| 86 | + # For now, only warn on failures so you can tune .lycheeignore and fix |
| 87 | + # obvious issues without blocking merges. |
| 88 | + # |
| 89 | + # Once you are happy with the signal/noise ratio, delete this step so that |
| 90 | + # Lychee's non-zero exit code will fail the job. |
| 91 | + - name: Warn on failures instead of failing CI |
| 92 | + if: steps.lychee.outputs.exit_code != 0 |
| 93 | + run: | |
| 94 | + echo "Lychee found broken links in ${{ matrix.site.name }} docs." |
| 95 | + echo "Exit code: ${{ steps.lychee.outputs.exit_code }}" |
| 96 | + echo "Check the Lychee step logs above for details." |
| 97 | + exit 0 |
0 commit comments