أتمتة Broken Links: افتح Issue قبل ما الزائر يضيع
مستوى القارئ: متوسط
هتكسب من المقال ده أوتوميشن أسبوعي يكشف الروابط المكسورة، ويحوّل التقرير إلى GitHub Issue قابل للتنفيذ بدل ما تكتشف المشكلة من عميل غاضب.
المشكلة باختصار
اللينكات بتتكسر بصمت. صفحة وثائق اتنقلت. مقال قديم اتغير مساره. رابط خارجي رجّع 404. الطريقة الشائعة إنك تراجع الصفحات يدويًا كل فترة، ودي بتفشل لأن المراجعة بتتأجل أول ما الضغط يزيد.
السيناريو الواقعي هنا: عندك موقع توثيق أو مدونة تقنية فيها 250 صفحة، وكل أسبوع بتنشر 3 مقالات أو تعدل docs. لو بتراجع الروابط شهريًا، الرابط المكسور ممكن يفضل ظاهرًا 30 يوم. أوتوميشن أسبوعي يقلل نافذة الاكتشاف إلى 7 أيام تقريبًا. الرقم تقديري، لكنه كافي لتوضيح الفرق في التشغيل.
الفكرة بمثال بسيط
ركز في المثال ده. بدل ما شخص يفتح الموقع ويدخل على كل صفحة، GitHub Actions يشغل فحص تلقائي كل يوم اثنين. أداة Lychee تقرأ ملفات Markdown وHTML وتختبر الروابط. لو لقت خطأ، Workflow يفتح Issue بعنوان واضح، ويحط التقرير في جسم الـ Issue.
بالظبط زي smoke test، لكنه للروابط. مش بيصلح الرابط بدل منك. هو بيخلي المشكلة مرئية ومربوطة بمكان واحد في GitHub، وده أهم من تقرير بيتدفن في لوجات CI.
الـ workflow القابل للنسخ
اعمل ملف باسم .github/workflows/check-links.yml. الافتراض إن الموقع أو التوثيق موجودين داخل المستودع، وإنك عايز تفحص ملفات md وhtml مرة أسبوعيًا، مع تشغيل يدوي عند الحاجة.
name: Check broken links
on:
workflow_dispatch:
schedule:
- cron: "0 7 * * 1"
permissions:
contents: read
issues: write
jobs:
links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- name: Run lychee
id: lychee
uses: lycheeverse/lychee-action@v2
with:
args: --verbose --no-progress './**/*.md' './**/*.html'
format: markdown
output: ./lychee/out.md
fail: false
- name: Create issue from report
if: steps.lychee.outputs.exit_code != 0
uses: peter-evans/create-issue-from-file@v5
with:
title: "Broken links report"
content-filepath: ./lychee/out.md
labels: report, automated issue
الجزء المهم هنا هو fail: false. لو خليتها true هتفشل الـ workflow، وده مفيد في مشاريع strict. لكن لو هدفك تقرير أسبوعي بدون تعطيل الفريق، خليه يفتح Issue فقط. الـ trade-off هنا واضح: بتكسب استمرارية أقل إزعاجًا، لكن ممكن الفريق يتأخر في معالجة الـ Issue لو مفيش owner واضح.
