كل ما سبق اعتمد على تذكّرك أنت. أن تتذكّر تشغيل فحص الـ HTML، وأن تفتح pull request بدل الرفع إلى main، وألّا ترفع بالقوة أبدًا. والناس ينسون، خصوصًا في الحادية عشرة ليلًا قبل التقدّم إلى وظيفة. ينقل هذا الدرس هذه العادات من رأسك إلى GitHub: آلة تشغّل الفحوص على كل pull request، وقواعد تجعل تغيير main بأي طريقة أخرى مستحيلًا.
التكامل المستمر (continuous integration) يحتاج إلى أمر يفشل حين يكون هناك خطأ. ولموقع HTML، فإن أداة التحقّق (validator) بداية جيدة. في موقعك الشخصي، على فرع جديد:
\ngit switch -c add-ci\nnpm init -y\nnpm install --save-dev html-validate\nnpm pkg set scripts.test=\"html-validate index.html projects.html\"\necho '{ \"extends\": [\"html-validate:recommended\"] }' > .htmlvalidate.json\nnpm testnode_modules/ موجود أصلًا في .gitignore منذ درسين؛ سجّل في commit كلًا من package.json و package-lock.json و .htmlvalidate.json. وإن أبلغ npm test عن مشكلات، فهذا هو المقصود: أصلحها، أو دوّنها لأول تشغيل للـ CI. وفي موقع شخصي جديد كثيرًا ما يجد هذا:
index.html\n 1:1 error DOCTYPE should be uppercase doctype-styleتشغّل GitHub Actions الـ workflows المعرَّفة في ملفات YAML تحت .github/workflows/. أنشئ واحدًا:
name: CI\n\non:\n pull_request:\n branches: [main]\n push:\n branches: [main]\n\njobs:\n check:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v7\n - uses: actions/setup-node@v7\n with:\n node-version: 24\n cache: npm\n - run: npm ci\n - run: npm testاقرأه من الأعلى إلى الأسفل:
\non يسرد الأحداث (events) التي تبدأ الـ workflow: أي pull request إلى main (عند فتحه، أو تحديثه بـ commits جديدة)، وعمليات الرفع إلى main بعد الدمج.jobs يحتوي job واحدًا، check. هذا المعرّف يصبح اسم الـ status check الذي يعرضه GitHub على الـ pull request.runs-on يختار runner، وهو آلة افتراضية جديدة يوفّرها GitHub. وتبدأ فارغة في كل مرة.steps تُنفَّذ بالترتيب. uses يشغّل action منشورًا: actions/checkout ينسخ الـ repository إلى الـ runner، و actions/setup-node يثبّت Node.js 24 ويخزّن تنزيلات npm مؤقتًا. و run ينفّذ أمر shell: npm ci يثبّت بالضبط ما يسرده package-lock.json، و npm test يشغّل أداة التحقّق.أي خطوة تنتهي بخطأ تُفشل الـ job. سجّل الـ workflow في commit، وارفع الفرع، وافتح pull request.
\nخلال ثوانٍ يعرض الـ pull request فحصًا، “CI / check (pull_request)”، بنقطة صفراء أثناء التشغيل. ثم علامة صح خضراء، أو علامة خطأ حمراء. انقر Details لترى السجلّ الكامل لكل خطوة؛ والخطوة الفاشلة تكون موسّعة، وتعرض ناتج أداة التحقّق نفسه الذي ستحصل عليه محليًا.
\nلإصلاح فحص أحمر، افعل ما تفعله مع ملاحظات المراجعة: أنشئ commit على الفرع نفسه وارفعه. يعمل الـ workflow مجددًا على الـ commit الجديد. اعتد على قراءة هذه السجلّات. الـ CI لا يحكم عليك؛ إنه زميل يعيد تشغيل الفحوص في كل مرة دون أن يملّ.
\nالفحص الناجح لا يفيد إلا إذا انتظره الدمج. وهذا ما يفرضه الـ ruleset (مجموعة القواعد). على GitHub، افتح Settings في الـ repository، ثم Rules، ثم Rulesets، واختر New ruleset، ثم New branch ruleset:
\ncheck، واحفظ.الآن حاول تخطّي العملية:
\ngit switch main\ngit commit --allow-empty -m \"Sneak a commit onto main\"\ngit push origin mainremote: error: GH013: Repository rule violations found for refs/heads/main.يُرفض الرفع، ويبقى الـ commit المحلي دون أن يُمسّ. كل تغيير على main يمرّ الآن عبر pull request، ويبقى زر الدمج معطّلًا حتى يصبح الفحص أخضر. شغّل git reset --hard origin/main لتتخلّص من الـ commit الفارغ.
الـ rulesets مجانية في الـ repositories العامة؛ أما في الخاصة فتحتاج إلى خطة مدفوعة مثل GitHub Pro أو Team. وقد ترى أيضًا branch protection rules الأقدم في الإعدادات. إنها تؤدّي مهمّة مشابهة؛ لكن الـ rulesets أحدث، ويمكن تركيبها في طبقات، ويستطيع أي شخص لديه صلاحية القراءة أن يرى القواعد المطبّقة.
\n\nانظر من أين بدأ الموقع الشخصي: مجلد فيه index.html. صار الآن repository بسجلّ مقروء، وفروع تُدمج أو يُعاد تأسيسها بنظافة، و remote على GitHub تصل إليه بمصادقة سليمة، و issues تشرح سبب وجود كل عمل، وإصدارات موسومة بـ tags، وفرع main لا يقبل إلا pull requests مراجَعة ومفحوصة آليًا. وتستطيع التراجع عن معظم الأخطاء، وتعرف أيّ طريقة تراجع تناسب كلًا منها.
وأهمّ من الأوامر، صار لديك النموذج: الـ commits لقطات مرتبطة بآبائها، والـ branches والـ tags أسماء دالّة، والـ HEAD هو حيث تقف، والـ remotes نسخ أخرى من الرسم البياني نفسه. وحين يفاجئك Git مستقبلًا، شغّل git log --oneline --graph --all، وارسم ما تراه، وغالبًا سيكون الأمر التالي واضحًا.
.github/workflows/؛ يحدّد on الأحداث، وتعمل الـ jobs على runners، وكل خطوة في steps إما تستخدم action عبر uses أو تنفّذ أمرًا عبر run.","كل job يبلّغ عن status check على الـ pull request، يظهر كعلامة صح خضراء أو علامة خطأ حمراء مع السجلّات الكاملة.","الـ branch ruleset على main يستطيع منع الرفع بالقوة والحذف، واشتراط pull request، واشتراط نجاح status checks مسمّاة.","الـ status check المطلوب يُطابَق باسم الـ job، ولا يقترح GitHub إلا الفحوص التي أبلغت عن نتيجتها من قبل، لذا شغّل الـ workflow قبل أن تشترطه.","الحلقة المكتملة هي فرع، ثم رفع، ثم pull request، ثم فحص آلي، ثم مراجعة، ثم دمج، ولا أحد يستطيع تخطّي خطوة."],"further":[{"title":"Building and testing Node.js","url":"https://docs.github.com/en/actions/tutorials/build-and-test-code/nodejs"},{"title":"Workflow syntax for GitHub Actions","url":"https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax"},{"title":"About rulesets","url":"https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/about-rulesets"},{"title":"Available rules for rulesets","url":"https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets"}],"quiz":[{"q":"يبدأ الـ workflow الخاص بك بـ on: pull_request. متى يعمل؟
workflow_dispatch. أما pull_request فيُطلق تلقائيًا بنشاط الـ pull requests."},{"text":"حين يُفتح pull request، ومجددًا في كل مرة تُرفع فيها commits جديدة إلى فرعه.","why":"صحيح. افتراضيًا يعمل pull_request عند الفتح (opened) والمزامنة (synchronize، أي commits جديدة) وإعادة الفتح (reopened)، فيُفحص كل تحديث."},{"text":"فقط بعد دمج الـ pull request.","why":"الغرض من فحص الـ pull request هو المعرفة قبل الدمج. والتشغيل بعد الدمج يكون حدث push إلى main."},{"text":"في كل مرة يرفع فيها أي شخص إلى أي فرع.","why":"هذا هو الحدث push دون مرشّح للفروع. أما pull_request فلا يُطلق إلا بنشاط الـ pull requests."}],"answer":1},{"q":"يفشل الـ CI job عند npm ci بخطأ مفاده أن package.json غير موجود. الخطوة الأولى هي run: npm ci. ما المشكلة؟
npm ci لا يعمل إلا على runners بنظام Windows.","why":"npm ci يعمل على كل أنظمة التشغيل التي توفّرها الـ runners."},{"text":"ملف الـ workflow في المجلد الخطأ.","why":"لو كان الملف في المجلد الخطأ لما عمل الـ workflow أصلًا. لكنه عمل، وفشل عند إحدى الخطوات."},{"text":"لم ينسخ الـ job الـ repository قط؛ يجب أن تأتي actions/checkout قبل أي خطوة تحتاج إلى ملفاتك.","why":"صحيح. يبدأ الـ runner آلةً فارغة. و actions/checkout يضع ملفات الـ repository في مكانها."}],"answer":3},{"q":"أضفت ruleset على main يشترط pull request. ماذا يحدث حين تشغّل git push origin main ولديك commit محلي؟
main، ويبقى الـ commit المحلي دون أن يُمسّ، فتستطيع رفعه إلى فرع وفتح pull request."},{"text":"ينجح الرفع ويفتح GitHub pull request تلقائيًا.","why":"لا يحوّل GitHub عمليات الرفع إلى pull requests. القواعد إما تسمح بالتحديث أو ترفضه."},{"text":"ينجح الرفع لأن القواعد لا تنطبق إلا على الآخرين.","why":"القواعد تنطبق على الجميع، بمن فيهم المالك، ما لم تضف نفسك إلى قائمة الاستثناء (bypass list)."},{"text":"يُحذف الـ commit المحلي ليبقى متزامنًا مع main.","why":"القواعد البعيدة لا تستطيع لمس الـ repository المحلي. لا شيء محلي يتغيّر حين يُرفض الرفع."}],"answer":0},{"q":"أعدت تسمية الـ job في الـ workflow من check إلى html. والآن يعرض كل pull request الفحص المطلوب check بالحالة “Expected — Waiting for status to be reported”، ولا شيء يمكن دمجه. لماذا؟
check أو test.","why":"أي اسم job يصلح. المشكلة أن الـ ruleset والـ workflow صارا مختلفين في الاسم."},{"text":"في الـ workflow خطأ في صياغة YAML.","why":"الـ job المسمّى html يعمل جيدًا؛ لكنه يبلّغ باسم لا ينتظره الـ ruleset."},{"text":"ما زال الـ ruleset يشترط فحصًا اسمه check، ولم يعد أي job يبلّغ به؛ حدّث الفحص المطلوب إلى html.","why":"صحيح. الفحوص المطلوبة تُطابق بالاسم. إن أعدت تسمية أحدهما، فحدّث الآخر في الوقت نفسه."}],"answer":2}],"exercise":{"kind":"spot-bug","language":"yaml","code":"name: CI\n\non:\n pull_requests:\n branches: [main]\n\njobs:\n check:\n runs-on: ubuntu-latest\n steps:\n - run: npm ci\n - uses: actions/checkout@v7\n - uses: actions/setup-node\n with:\n node-version: 24\n cache: npm\n - run: npm test","bugLines":[4,11,13],"title":"أصلح الـ CI workflow","prompt":"كتب زميل ملف .github/workflows/ci.yml ليشغّل فحص الـ HTML في الموقع الشخصي على كل pull request إلى main. لكنه لا يظهر أبدًا على الـ pull requests، وحتى بعد إصلاح ذلك سيظل يفشل. حدّد الأسطر الثلاثة الخاطئة.
on يجب أن تكون دقيقة؛ قارنها باسم الحدث الذي رأيته في الدرس.","يبدأ الـ runner فارغًا. ما الذي يجب أن يحدث قبل أن يجد npm الملف package.json؟","كل uses: يجب أن يحدّد أيّ إصدار من الـ action يُشغَّل."],"explanation":"السطر 4: الحدث هو pull_request (بالمفرد)؛ و pull_requests ليس حدثًا يعرفه GitHub، فيصبح الـ workflow غير صالح ولا يعمل أبدًا على الـ pull requests. السطر 11: يعمل npm ci قبل actions/checkout، على runner فارغ لا يحتوي package.json؛ انقله إلى ما بعد الـ checkout والـ setup-node. السطر 13: يجب أن يتضمّن uses مرجعًا، مثل actions/setup-node@v7؛ ودون @… يفشل تحميل الـ workflow. وبعد الإصلاح تصبح الخطوات: checkout، ثم setup-node مع Node 24، ثم npm ci، ثم npm test.