|
| 1 | +name: external-reference-check |
| 2 | + |
| 3 | +# Reach out to every external URL referenced from our markdown and report |
| 4 | +# anything that's unreachable. This is intentionally split from `validate` |
| 5 | +# because external checks are flaky (transient 5xx, rate limits, runner IP |
| 6 | +# blocks, DNS hiccups). The workflow fails on PR and manual runs so broken |
| 7 | +# links are visible; whether they actually block merge is controlled by |
| 8 | +# whether this check is marked required in branch protection (recommended: |
| 9 | +# leave it not-required so a transient hiccup can't block a merge). |
| 10 | +# |
| 11 | +# Internal references and anchors are checked by `validate.yml` with |
| 12 | +# `lychee --offline`. |
| 13 | + |
| 14 | +on: |
| 15 | + pull_request: |
| 16 | + paths: |
| 17 | + - "**/*.md" |
| 18 | + - ".github/lychee.toml" |
| 19 | + - ".github/workflows/external-reference-check.yml" |
| 20 | + schedule: |
| 21 | + # Mondays at 12:00 UTC. Catches link rot in unchanged content. |
| 22 | + - cron: "0 12 * * 1" |
| 23 | + workflow_dispatch: |
| 24 | + |
| 25 | +permissions: |
| 26 | + contents: read |
| 27 | + issues: write |
| 28 | + |
| 29 | +jobs: |
| 30 | + external-references: |
| 31 | + name: Check external references in skills |
| 32 | + runs-on: ubuntu-latest |
| 33 | + steps: |
| 34 | + - name: Check out repository |
| 35 | + uses: actions/checkout@v4 |
| 36 | + |
| 37 | + - name: Check external references |
| 38 | + id: lychee |
| 39 | + uses: lycheeverse/lychee-action@v2 |
| 40 | + with: |
| 41 | + args: --config .github/lychee.toml --no-progress "./**/*.md" |
| 42 | + # Fail the workflow on PR and manual runs so broken external |
| 43 | + # references show up as a red check (mark this workflow as |
| 44 | + # not-required in branch protection if you don't want it to |
| 45 | + # block merges). |
| 46 | + # |
| 47 | + # On the scheduled cron run we deliberately do NOT fail here, |
| 48 | + # so the issue-filing step below can still execute. |
| 49 | + fail: ${{ github.event_name != 'schedule' }} |
| 50 | + |
| 51 | + # Scheduled runs file (or update) an issue when something is rotten, |
| 52 | + # so unchanged-but-broken links don't silently sit in main. |
| 53 | + - name: File or update link-rot issue on scheduled failure |
| 54 | + if: github.event_name == 'schedule' && steps.lychee.outputs.exit_code != 0 |
| 55 | + env: |
| 56 | + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} |
| 57 | + REPO: ${{ github.repository }} |
| 58 | + SERVER_URL: ${{ github.server_url }} |
| 59 | + RUN_ID: ${{ github.run_id }} |
| 60 | + run: | |
| 61 | + set -euo pipefail |
| 62 | +
|
| 63 | + # Create the label on first use; ignore if it already exists. |
| 64 | + gh label create external-reference-rot \ |
| 65 | + --color ffaa00 \ |
| 66 | + --description "Unreachable external references found by scheduled lychee run" \ |
| 67 | + 2>/dev/null || true |
| 68 | +
|
| 69 | + run_url="${SERVER_URL}/${REPO}/actions/runs/${RUN_ID}" |
| 70 | +
|
| 71 | + if [ ! -s ./lychee/out.md ]; then |
| 72 | + echo "lychee report file is missing or empty; nothing to file." >&2 |
| 73 | + exit 0 |
| 74 | + fi |
| 75 | +
|
| 76 | + existing=$(gh issue list \ |
| 77 | + --label external-reference-rot \ |
| 78 | + --state open \ |
| 79 | + --json number \ |
| 80 | + --jq '.[0].number // empty') |
| 81 | +
|
| 82 | + if [ -n "$existing" ]; then |
| 83 | + echo "Updating existing issue #$existing" |
| 84 | + gh issue edit "$existing" --body-file ./lychee/out.md |
| 85 | + gh issue comment "$existing" \ |
| 86 | + --body "Refreshed by scheduled run: $run_url" |
| 87 | + else |
| 88 | + echo "Filing new issue" |
| 89 | + gh issue create \ |
| 90 | + --title "External reference rot detected" \ |
| 91 | + --label external-reference-rot \ |
| 92 | + --body-file ./lychee/out.md |
| 93 | + fi |
0 commit comments