في شهر واحد وقع لفريق صغير في شركة ناشئة تبني API لمتاجر إلكترونية حادثان لا علاقة لأحدهما بالآخر. في الأول أضاف أحد المطورين ملف .env إلى ال Commit دون أن ينتبه، وفيه مفتاح وصول لحساب التخزين السحابي، ودفعه إلى مستودع الفريق على Gitea، ومن هناك وصل المفتاح إلى كل جهاز سحب المستودع، وإلى سجلات خط CI، وإلى النسخة الاحتياطية الليلية. وفي الثاني عدل مطور آخر ملف إعدادات YAML قبل نهاية الدوام، واستخدم مفتاح Tab بدلاً من المسافات في سطر واحد، فلم تقرأ الخدمة الملف عند النشر، وتوقفت ساعة كاملة في المساء حتى عرف أحدهم السبب. وفي اجتماع المراجعة سأل قائد الفريق سؤالاً بسيطاً: لماذا نكتشف هذه الأخطاء بعد أن تدخل المستودع، والكمبيوتر الذي كتبها كان يستطيع أن يقول «لا» قبل ثانية من ال Commit؟
والجواب موجود في Git نفسه منذ سنوات، ويسمى الخطافات Git Hooks: برامج صغيرة يشغلها Git بنفسه عند لحظات محددة، مثل قبل إنشاء Commit أو قبل أن يقبل السيرفر الدفع، وإذا خرج البرنامج برمز غير الصفر توقف Git ورفض العملية. وفي هذا المقال نبني للفريق ثلاث طبقات فحص على مختبر حقيقي: خطافات يكتبها المطور بيده، ثم إطار pre-commit الذي يجعل مشاركتها بين الفريق سهلة، ثم خطاف على سيرفر Gitea نفسه لا يستطيع أحد أن يتخطاه. وكل مخرج في المقال هو ما طبعته الأدوات فعلاً، ومعه ثلاث مشكلات حقيقية وقعنا فيها أثناء التجربة. وسوف نناقش في هذا المقال ما يلي:
- ما هي الخطافات، وأين تعيش، والفرق بين خطافات العميل وخطافات السيرفر.
- أول خطاف pre-commit يمنع الأسرار، ولماذا تجاهله Git في المحاولة الأولى.
- الخطاف commit-msg لفرض صيغة رسالة ال Commit، والخيار
--no-verifyالذي يتخطى كل ذلك. - لماذا لا تنسخ الخطافات مع
git clone، وكيف تشاركها مع الفريق. - إطار pre-commit: ملف الإعداد، والفحوص الجاهزة، والمشكلات التي ظهرت في التشغيل الأول.
- خطافات السيرفر في Gitea: لماذا تغلق افتراضياً، وكيف نكتب pre-receive يرفض الدفع.
- ماذا يحدث إذا دفع أحدهم السر نفسه إلى فرع جديد، والخطأ الذي سمح له بالمرور.
- أين تضع كل فحص بين الخطاف والسيرفر وخط CI، وأخطاء شائعة، وقائمة تحقق.
ما هي الخطافات Git Hooks؟
الخطاف برنامج عادي، غالباً سكربت Shell أو Python، تضعه في مكان يعرفه Git وباسم يعرفه، فيشغله Git عندما تصل عملية معينة إلى نقطة معينة. والاسم من فكرة «التعليق» على عملية موجودة: Git لا يعرف شيئاً عن الأسرار ولا عن ملفات YAML، ولكنه يعطيك نقاطاً ثابتة في عملياته تعلق عليها ما تريد. ولكل خطاف عقد واضح في توثيق githooks: متى يشغل، وما الوسائط Arguments التي يعطيها Git له، وما الذي يقرؤه من الإدخال القياسي Standard Input، وماذا يعني رمز الخروج Exit Code الذي يرجعه. والقاعدة العامة في أغلب الخطافات التي تأتي «قبل» شيء، مثل pre-commit وpre-push وpre-receive، أن الصفر يعني «استمر» وأي رقم آخر يعني «توقف وألغ العملية».
وتشبيه بسيط يساعد هنا: تخيل أن ال Commit طرد تجهزه للشحن، والخطاف موظف يقف عند باب المستودع، يفتح الطرد قبل أن يغلق، فإذا وجد فيه شيئاً ممنوعاً أرجعه إليك مع ورقة تقول السبب. والمهم في هذا التشبيه أن الموظف لا يغير طريقة الشحن نفسها، فهو يفحص فقط، وأنه يقف في مكان محدد، فما يمر من باب آخر لا يراه، وهذا بالضبط ما سوف نراه مع الخيار --no-verify بعد قليل.
أين تعيش الخطافات؟ The .git/hooks Folder
كل مستودع تنشئه أو تستنسخه يأتي معه مجلد .git/hooks، وفيه أمثلة جاهزة يضعها Git من القالب Template الافتراضي. في المختبر استنسخنا مستودعاً فارغاً من Gitea ونظرنا إليه:
ls .git/hooksوالمخرج سوف يكون كما يلي:
applypatch-msg.sample
commit-msg.sample
post-update.sample
pre-applypatch.sample
pre-commit.sample
pre-merge-commit.sample
pre-push.sample
pre-rebase.sample
pre-receive.sample
prepare-commit-msg.sample
push-to-checkout.sample
sendemail-validate.sample
update.sampleكل ملف هنا ينتهي بالامتداد .sample، ولهذا لا يشغل Git أياً منها، فهو يبحث عن ملف باسم الخطاف بالضبط، مثل pre-commit دون امتداد. والأمثلة مفيدة للقراءة، ففيها مثلاً pre-commit يرفض أسماء الملفات غير ASCII، وpre-push يرفض دفع Commits رسالتها تبدأ بكلمة WIP. ولكي تفعل واحداً منها يكفي أن تحذف الامتداد وتتأكد أنه قابل للتنفيذ. ولاحظ وجود أمثلة لخطافات تعمل على السيرفر أيضاً، مثل pre-receive.sample وupdate.sample، لأن المجلد نفسه موجود في المستودع المجرد Bare Repository على السيرفر، وهناك تصبح هذه الخطافات فعالة.
خطافات العميل مقابل السيرفر Client vs Server Hooks
الخطافات نوعان بحسب الجهاز الذي تعمل عليه، والفرق بينهما هو أهم فكرة في هذا المقال كله. خطافات العميل Client-side Hooks تعمل على جهاز المطور، عند عمليات مثل commit وmerge وpush، وهي سريعة وتعطي المطور النتيجة قبل أن يغادر مكتبه، ولكنها ملك المطور: يستطيع أن يحذفها أو يتخطاها أو لا يثبتها أصلاً. وخطافات السيرفر Server-side Hooks تعمل على السيرفر الذي يستقبل الدفع، ولا يستطيع المطور أن يتخطاها، ولكنها تحتاج صلاحية على السيرفر نفسه، وتعمل بعد أن تكون ال Commits قد أنشئت على جهاز المطور. والجدول التالي يجمع الخطافات التي سوف نستخدمها:
| الخطاف | أين يعمل | متى | ما الذي يستطيع منعه | هل يمكن تخطيه؟ |
|---|---|---|---|---|
pre-commit | جهاز المطور | قبل كتابة رسالة ال Commit | إنشاء ال Commit | نعم، --no-verify |
commit-msg | جهاز المطور | بعد كتابة الرسالة | إنشاء ال Commit بهذه الرسالة | نعم، --no-verify |
pre-push | جهاز المطور | قبل إرسال البيانات إلى السيرفر | الدفع كله | نعم، --no-verify |
pre-receive | السيرفر | بعد استلام البيانات وقبل تحديث أي فرع | كل الفروع في هذا الدفع | لا |
update | السيرفر | مرة لكل فرع | فرعاً واحداً | لا |
post-receive | السيرفر | بعد تحديث الفروع | لا شيء، للإشعارات فقط | لا يمنع شيئاً |
والصورة التالية تضع هذه الخطافات على طريق ال Commit من لوحة المفاتيح إلى السيرفر، وتبين أين يقع الباب الخلفي:

تجهيز المختبر Lab Setup
نحتاج سيرفر Gitea مع جهاز مطور يتصل به، وكلاهما في Container. وفي سيرفر Gitea نفعل الخطافات بمتغير البيئة GITEA__security__DISABLE_GIT_HOOKS=false، وسوف نشرح لماذا هي مغلقة افتراضياً في قسم السيرفر:
docker network create dv2g-net
docker run -d --name dv2g-gitea --network dv2g-net -p 3481:3000 \
-e GITEA__security__INSTALL_LOCK=true \
-e GITEA__security__DISABLE_GIT_HOOKS=false \
-e GITEA__server__ROOT_URL=http://dv2g-gitea:3000/ \
-e GITEA__database__DB_TYPE=sqlite3 \
-e GITEA__service__DISABLE_REGISTRATION=true \
-v dv2g-gitea-data:/data gitea/gitea:28.3.0
docker exec -u git dv2g-gitea gitea admin user create --admin \
--username admin1 --password 'Lab-Pass-2026!' --email [email protected] --must-change-password=false
docker exec -u git dv2g-gitea gitea admin user create \
--username dev1 --password 'Lab-Pass-2026!' --email [email protected] --must-change-password=false
docker run -d --name dv2g-client --network dv2g-net python:3.13-alpine sleep 86400
docker exec dv2g-client sh -c 'apk add --no-cache git curl jq && pip install pre-commit==4.7.0'جهاز المطور Container من python:3.13-alpine لأن إطار pre-commit مكتوب بلغة Python، وأضفنا إليه Git 2.54.0 من حزم Alpine. وأنشأنا مستخدمين: admin1 مدير الموقع، وdev1 مطور عادي، ثم أنشأ dev1 مستودعاً اسمه shop-api واستنسخه، وأضاف إليه ملف src/app.py صغيراً وملف إعدادات config/app.yaml، ودفع أول Commit. وكل أوامر المختبر موجودة في مجلد lab مع المقال. وإذا لم تكن قد ثبت Gitea من قبل فابدأ بدليل تثبيت Gitea مع Docker Compose، فالمختبر هنا نسخة مختصرة منه لا تصلح للإنتاج.
أول خطاف: pre-commit يمنع الأسرار First Hook
نبدأ بالحادث الأول. نريد خطافاً يقرأ التغييرات التي جهزها المطور للدخول في ال Commit، ويبحث فيها عن شكلين معروفين للأسرار: مفتاح وصول AWS الذي يبدأ دائماً بالحروف AKIA ثم ستة عشر حرفاً ورقماً كبيراً، وأول سطر في أي مفتاح خاص Private Key مثل BEGIN OPENSSH PRIVATE KEY. كتبنا الملف .git/hooks/pre-commit:
#!/bin/sh
# Block staged changes that look like secrets.
if git diff --cached -U0 | grep -nE '^\+.*(AKIA[0-9A-Z]{16}|BEGIN [A-Z ]*PRIVATE KEY)'; then
echo "pre-commit: this change looks like a secret, commit refused" >&2
exit 1
fiثم أعدنا ما فعله زميلنا في الحادث: ملف .env فيه المفتاح التجريبي الذي تنشره AWS نفسها في توثيقها، ثم Commit:
printf 'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\n' > .env
git add .env
git commit -m "chore: add env file"
git log --oneline -1والمخرج سوف يكون كما يلي:
hint: The '.git/hooks/pre-commit' hook was ignored because it's not set as executable.
hint: You can disable this warning with `git config set advice.ignoredHook false`.
[main 4ab4630] chore: add env file
1 file changed, 1 insertion(+)
create mode 100644 .envودخل السر إلى المستودع، تماماً كما في الحادث.
لماذا تجاهل Git الخطاف؟ Executable Bit
هذه أول مشكلة حقيقية وقعنا فيها، وهي أشهر مشكلة مع الخطافات على الإطلاق. التوثيق يقولها في سطر واحد: الخطافات التي ليس عليها صلاحية التنفيذ Executable Bit يتجاهلها Git. وكتبنا الملف بمحرر نصوص أو بالأمر cat، فنشأ بالصلاحيات الافتراضية للقراءة والكتابة فقط. والجيد أن إصدارات Git الحديثة تطبع تلميحاً hint يخبرك بذلك، ولكن التلميح سطر واحد في وسط مخرج ال Commit، ولا يوقف شيئاً، فمن السهل ألا تراه. وإذا كنت تعمل على Windows فالمشكلة تأخذ شكلاً آخر، لأن نظام الملفات لا يحمل صلاحية التنفيذ نفسها، وGit for Windows يشغل الخطاف عبر Bash الذي يأتي معه بحسب السطر الأول #!/bin/sh، فإذا كتبت السطر الأول بشكل خاطئ أو حفظت الملف بنهايات أسطر CRLF فسوف يفشل بطريقة أخرى. لذلك أول ما تفعله مع أي خطاف لا يعمل أن تنظر إلى صلاحياته وسطره الأول. أرجعنا ال Commit بالأمر git reset --soft HEAD~1 حتى يبقى الملف مجهزاً كما كان، ثم أضفنا الصلاحية وأعدنا المحاولة:
chmod +x .git/hooks/pre-commit
git commit -m "chore: add env file"; echo "exit code: $?"والمخرج سوف يكون كما يلي:
7:+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
pre-commit: this change looks like a secret, commit refused
exit code: 1في المخرج أعلاه لاحظ التالي:
- السطر الأول ما طبعه
grep -n: رقم السطر في مخرج الفرق، ثم السطر نفسه بعلامة+لأنه سطر مضاف. وطباعة السطر الذي سبب الرفض مقصودة، لأن المطور يحتاج أن يعرف ماذا يصلح، وليس فقط أن العملية رفضت. - السطر الثاني رسالتنا، وكتبناها إلى المخرج القياسي للأخطاء Standard Error بالإضافة
>&2، وهذا هو المكان الصحيح لرسائل الرفض. - رمز خروج
git commitنفسه أصبح 1، لأن الخطاف خرج بالرقم 1. وهذا مهم لمن يستخدم Git داخل سكربت: فشل الخطاف يظهر كفشل للأمر.
كيف يعرف الخطاف ما سيدخل؟ Staged Changes
قد تسأل: لماذا git diff --cached وليس git diff العادي أو فحص الملفات في المجلد؟ والسبب أن ال Commit لا يأخذ ما في مجلد العمل، وإنما يأخذ ما في منطقة التجهيز Staging Area، كما شرحنا في دليل المبتدئين. فلو فحص الخطاف ملفات المجلد، لاستطاع المطور أن يجهز ملفاً فيه سر، ثم يحذف السر من الملف دون أن يجهز الحذف، فيرى الخطاف ملفاً نظيفاً، ويدخل السر إلى ال Commit. والخيار --cached يعرض الفرق بين منطقة التجهيز وآخر Commit، أي ما سوف يدخل بالضبط. والخيار -U0 يلغي أسطر السياق حول كل تغيير، حتى لا يطابق البحث سطراً قديماً موجوداً قبل هذا ال Commit، فنحن نهتم بالأسطر المضافة فقط، وهي التي تبدأ بالعلامة +.
وهذه التفاصيل الصغيرة هي ما يجعل كتابة الخطافات بيدك أصعب مما تبدو. فالخطاف الذي كتبناه لا يعالج حالات مثل ملف ثنائي Binary، أو ملف أعيدت تسميته، أو سر مقسوم على سطرين، أو مفتاح Google أو Stripe بشكل مختلف. ولهذا توجد أدوات متخصصة في البحث عن الأسرار فيها مئات القواعد، مثل gitleaks الذي شرحناه في اكتشاف الأسرار المسربة، وسوف نرى كيف نربط أدوات من هذا النوع بالخطافات دون أن نكتبها بأنفسنا.
رسالة ال Commit: الخطاف commit-msg
الفريق اتفق أيضاً على أن تتبع رسائل ال Commits صيغة Conventional Commits، أي نوع التغيير ثم نقطتان ثم وصف قصير، مثل fix: handle empty cart، لأن هذه الصيغة تسمح بتوليد سجل التغييرات ورقم الإصدار تلقائياً كما شرحنا في الإصدارات SemVer مع سجل التغييرات. والاتفاق المكتوب في صفحة Wiki لا يطبقه أحد بعد أسبوعين، فكتبنا خطافاً يطبقه. الخطاف commit-msg يشغله Git بعد أن تكتب الرسالة، ويعطيه وسيطاً واحداً هو مسار الملف المؤقت الذي فيه الرسالة، وإذا خرج بغير الصفر لا ينشأ ال Commit:
#!/bin/sh
# $1 is the file that holds the message. Require "type: subject" (Conventional Commits).
first=$(head -n1 "$1")
if ! echo "$first" | grep -qE '^(feat|fix|docs|chore|refactor|test|ci)(\([a-z0-9-]+\))?!?: .{3,}'; then
echo "commit-msg: \"$first\" does not follow 'type: subject' (feat, fix, docs, chore, refactor, test, ci)" >&2
exit 1
fiالتعبير المنتظم Regular Expression يقبل نوعاً من القائمة، ثم نطاقاً اختيارياً بين قوسين مثل fix(cart)، ثم علامة تعجب اختيارية تعني تغييراً غير متوافق، ثم نقطتين ومسافة ووصفاً من ثلاثة أحرف على الأقل. وجربنا رسالتين لتغيير يرفع عدد ال Workers في الإعدادات:
git commit -m "updated workers"
git commit -m "perf: raise workers to 8"والمخرج سوف يكون كما يلي:
commit-msg: "updated workers" does not follow 'type: subject' (feat, fix, docs, chore, refactor, test, ci)
commit-msg: "perf: raise workers to 8" does not follow 'type: subject' (feat, fix, docs, chore, refactor, test, ci)الرسالة الأولى رفضت كما توقعنا، أما الثانية فهي المشكلة الحقيقية الثانية: perf نوع مشروع لتحسين الأداء، ويستخدمه كثير من الفرق، ولكننا نسيناه في القائمة، فرفض الخطاف رسالة صحيحة. وهذا يحدث مع كل خطاف تكتبه بيدك: القاعدة التي في رأسك أوسع من القاعدة التي كتبتها، والمطور الذي يرفض الخطاف عمله الصحيح مرتين سوف يتعلم الخيار --no-verify في المرة الثالثة. أصلحنا القائمة بإضافة perf وbuild وstyle وrevert، فنجح ال Commit:
[main 65c7c73] perf: raise workers to 8
1 file changed, 1 insertion(+)والدرس العملي: كل خطاف يرفض شيئاً يجب أن يقول في رسالته ما هو المطلوب بالضبط، وأن يكون عند الفريق مكان واحد يصلح فيه القاعدة إذا كانت خاطئة، وليس نسخة مختلفة على جهاز كل مطور. وهذا ينقلنا إلى مشكلة أكبر بعد قليل.
الباب الخلفي: الخيار no-verify Bypass
الآن نجرب ما سوف يفعله المطور المستعجل. أعدنا ملف .env بالسر نفسه، وأنشأنا Commit مع الخيار --no-verify:
git commit --no-verify -m "wip"
git log --oneline -3والمخرج سوف يكون كما يلي:
[main c5998be] wip
1 file changed, 1 insertion(+)
create mode 100644 .env
c5998be wip
65c7c73 perf: raise workers to 8
234c8b3 feat: first version of the APIلم يشغل Git الخطاف pre-commit ولا الخطاف commit-msg، فدخل السر، ودخلت رسالة «wip» التي لا تتبع أي صيغة. وهذا ليس ثغرة، وإنما سلوك موثق في توثيق git commit، وله أسباب مشروعة: خطاف معطوب لا تملك وقتاً لإصلاحه الآن، أو Commit مؤقت على فرعك الخاص ستعيد كتابته قبل المراجعة. والاختصار -n يفعل الشيء نفسه، وكذلك git push --no-verify مع الخطاف pre-push.
والنتيجة التي يجب أن تخرج بها من هذه التجربة: خطافات العميل حزام أمان وليست قفلاً. هي تمنع الخطأ غير المقصود، وهو أغلب الأخطاء، فزميلنا الذي دفع ملف .env لم يكن يريد أن يدفعه، ولو رأى رسالة الرفض لأزاله في ثانية. ولكنها لا تمنع المطور الذي قرر أن يتخطاها، ولا المطور الذي لم يثبتها أصلاً. لذلك لا تبن على خطافات العميل وحدها أي قاعدة لا تقبل أي استثناء، وسوف نضع هذه القواعد على السيرفر. ثم أرجعنا ال Commit بالأمر git reset --hard HEAD~1، لأننا لم ندفعه بعد.
الخطافات لا تنسخ مع clone: Sharing Hooks
الخطافان اللذان كتبناهما يعيشان في .git/hooks على جهاز واحد. فماذا يجد زميل جديد يستنسخ المستودع؟ استنسخناه في مجلد آخر وعددنا الخطافات التي ليست أمثلة:
git clone -q http://dev1:Lab-Pass-2026!@dv2g-gitea:3000/dev1/shop-api.git fresh && ls fresh/.git/hooks | grep -v sample; echo "non-sample hooks: $(ls fresh/.git/hooks | grep -vc sample)"والمخرج سوف يكون كما يلي:
non-sample hooks: 0صفر. فالمجلد .git كله ليس جزءاً مما يدفع أو يستنسخ، وما يصل إلى الزميل هو ال Commits فقط، ثم ينشئ Git مجلد .git/hooks جديداً من الأمثلة. وقد يبدو هذا نقصاً في Git، ولكنه قرار أمني مقصود: الخطاف برنامج يعمل بصلاحياتك على جهازك، ولو كان git clone ينسخ الخطافات ويشغلها لأصبح استنساخ أي مستودع من الإنترنت مثل تشغيل برنامج مجهول، فأول git commit بعده ينفذ كوداً كتبه شخص لا تعرفه. لذلك يجب أن يكون تفعيل الخطافات خطوة يقوم بها المطور بنفسه، مرة واحدة على الأقل.
والطريقة التي يوفرها Git لجعل هذه الخطوة سهلة هي الإعداد core.hooksPath، الذي يغير المجلد الذي يبحث فيه Git عن الخطافات، كما يذكر توثيق git config. فنضع الخطافات في مجلد عادي داخل المستودع، مثل .githooks، يدخل في ال Commits ويراجع مثل أي كود، وكل مطور ينفذ أمراً واحداً بعد الاستنساخ:
mkdir -p .githooks
cp .git/hooks/pre-commit .git/hooks/commit-msg .githooks/
git add .githooks && git commit -m "chore: share hooks in .githooks"
git config core.hooksPath .githooks
git ls-files -s .githooksوالمخرج سوف يكون كما يلي، للأمر الأخير:
100755 00aa7d7216c2017d2bce3391b4d9344e8dd86661 0 .githooks/commit-msg
100755 6d1fbf993102f632233b0f88ef11611d43e871ae 0 .githooks/pre-commitالرقم 100755 في أول كل سطر هو نمط الملف كما خزنه Git، والجزء 755 يعني أن صلاحية التنفيذ محفوظة في المستودع، فمن يستنسخ على Linux أو macOS يحصل على ملف قابل للتنفيذ، ولا يقع في مشكلة القسم السابق. وإذا كان الملف قد دخل بالنمط 100644 فأصلحه بالأمر git update-index --chmod=+x ثم Commit، وهذا مفيد خاصة لمن يعمل على Windows.
هذه الطريقة بسيطة ولا تحتاج أي أداة، وتصلح لفريق صغير ولغة واحدة. ولكن مع الوقت تظهر حدودها: كل خطاف سكربت Shell تكتبه وتصونه بنفسك، وإذا أردت أن تشغل أداة فحص لملفات Python مثل ruff، وأداة لملفات JavaScript، وأداة للأسرار، فكل أداة يجب أن تكون مثبتة على جهاز كل مطور بالإصدار نفسه، وإلا نجح الفحص عند أحدهم وفشل عند الآخر. وهذه هي المشكلة التي جاء من أجلها إطار pre-commit.
إطار pre-commit Framework
يقول موقع pre-commit في مقدمته إن الفريق الذي كتبه وجد أن مشاركة خطافات pre-commit بين المشاريع مؤلمة كلما زاد عدد المكتبات والمشاريع، فبنى أداة تحل ذلك لخطافات من لغات كثيرة. والفكرة أن الخطافات نفسها تصبح «حزماً» في مستودعات Git عامة، كل حزمة تعلن في ملف داخلها ما الخطافات التي تقدمها وبأي لغة كتبت، وأنت تكتب في مشروعك ملف إعداد واحد يقول: أريد الخطافات كذا وكذا من المستودع الفلاني عند الوسم الفلاني. ثم يتولى pre-commit الباقي: يستنسخ المستودع، وينشئ له بيئة معزولة Isolated Environment بلغته، مثل virtualenv لخطافات Python أو node_modules لخطافات JavaScript، ويخزنها في مجلد Cache على جهازك، ثم يشغلها على الملفات المجهزة فقط عند كل Commit. فالمطور لا يحتاج أن يثبت أي أداة بنفسه، ويحصل كل الفريق على الإصدار نفسه بالضبط، لأن الإصدار مكتوب في ملف داخل المستودع.
ملف الإعداد .pre-commit-config.yaml
هذا هو الملف الذي وضعناه في جذر المستودع:
default_install_hook_types: [pre-commit, commit-msg]
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v6.0.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
args: ['--maxkb=500']
- id: detect-private-key
- repo: local
hooks:
- id: no-aws-keys
name: block AWS access keys
language: pygrep
entry: 'AKIA[0-9A-Z]{16}'
- id: conventional-commit
name: 'commit message is "type: subject"'
language: pygrep
entry: '^(feat|fix|docs|chore|refactor|test|ci|perf|build|style|revert)(\([a-z0-9-]+\))?!?: .{3,}'
args: [--negate]
stages: [commit-msg]في الإعداد أعلاه لاحظ التالي:
default_install_hook_typesيحدد أي خطافات Git يثبتها الأمرpre-commit install. والافتراضي pre-commit وحده، ونحن نحتاج commit-msg أيضاً لفحص الرسالة.- المستودع الأول هو pre-commit-hooks، وهو مجموعة الفحوص الرسمية العامة التي يصونها فريق الأداة. و
revوسم ثابت، ويقول التوثيق إن الأداة تفترض أن هذه القيمة لا تتغير، أي وسم أو رقم Commit، ولا تقبل اسم فرع، لأن الفرع يتحرك بعد التثبيت فيختلف ما يشغله كل مطور. - من هذا المستودع اخترنا خمسة فحوص: حذف المسافات في آخر الأسطر، وإضافة سطر فارغ في آخر الملف إذا نقص، والتأكد أن ملفات YAML تقرأ دون خطأ، ومنع الملفات الأكبر من 500 KB، والبحث عن المفاتيح الخاصة. والقائمة الكاملة في صفحة الخطافات المعروفة.
repo: localيعني خطافات معرفة هنا في الملف نفسه دون مستودع خارجي. واللغةpygrepنوع خاص يبحث بتعبير منتظم بلغة Python في الملفات، فإذا وجد تطابقاً فشل. فالخطاف الأول يحل محل سكربت الأسرار الذي كتبناه.- الخطاف الثاني يحل محل سكربت commit-msg. ومع
--negateينعكس المعنى، فيفشل إذا لم يجد التطابق، كما يقول التوثيق «لتطلب أن تطابق كل الملفات». وstages: [commit-msg]يعني أنه يعمل عند فحص الرسالة فقط، والملف الذي يعطى له هو ملف الرسالة.
مشكلة حقيقية: Cowardly Refusing
نثبت الآن الخطافات بالأمر الذي سوف ينفذه كل مطور مرة واحدة بعد الاستنساخ:
pre-commit installوالمخرج سوف يكون كما يلي:
[ERROR] Cowardly refusing to install hooks with `core.hooksPath` set.
hint: `git config --unset-all core.hooksPath`رفضت الأداة، والسبب منطقي حين تفكر فيه: pre-commit install يكتب ملفاته في .git/hooks، ولكننا قبل قليل وجهنا Git إلى مجلد .githooks، فلو كتبت الأداة ملفاتها لما شغلها Git أبداً، ولظن المطور أن كل شيء يعمل. فبدلاً من أن تفشل بصمت، رفضت وطبعت الأمر الذي يحل المشكلة. وهذا يحدث كثيراً في الفرق التي تنتقل من طريقة core.hooksPath إلى الإطار، وأيضاً على أجهزة ضبط فيها core.hooksPath على مستوى المستخدم كله بالخيار --global لأداة أخرى. أزلنا الإعداد، وحذفنا الخطافين القديمين من .git/hooks لأن الإطار سوف يحل محلهما، ثم ثبتنا:
git config --unset core.hooksPath && rm .git/hooks/pre-commit .git/hooks/commit-msg && pre-commit install
head -n 12 .git/hooks/pre-commitوالمخرج سوف يكون كما يلي:
pre-commit installed at .git/hooks/pre-commit
pre-commit installed at .git/hooks/commit-msg
#!/usr/bin/env bash
# File generated by pre-commit: https://pre-commit.com
# ID: 138fd403232d2ddd5efb44317e38bf03
# start templated
INSTALL_PYTHON=/usr/local/bin/python3.13
ARGS=(hook-impl --config=.pre-commit-config.yaml --hook-type=pre-commit)
# end templated
HERE="$(cd "$(dirname "$0")" && pwd)"
ARGS+=(--hook-dir "$HERE" -- "$@")ثبت الإطار خطافين، كما طلبنا في default_install_hook_types. والملف الذي كتبه في .git/hooks/pre-commit ليس فحصاً، وإنما وسيط صغير Shim يستدعي pre-commit نفسه بمسار Python الذي ثبت به، ويمرر له ملف الإعداد ونوع الخطاف. لذلك إذا عدلت .pre-commit-config.yaml لا تحتاج أن تعيد التثبيت، فالوسيط يقرأ الملف في كل مرة. ولو كانت في المجلد خطافات قديمة بالاسم نفسه ولم نحذفها، لنقلها الإطار إلى ملف باسم ينتهي بالكلمة .legacy وشغلها قبل خطافاته، وهذا ما يسميه وضع الترحيل Migration Mode، ويلغيه الخيار -f.
مشكلة ثانية: env can't execute bash
وأول Commit بعد التثبيت، وهو Commit ملف الإعداد نفسه:
git add .pre-commit-config.yaml
git commit -m "ci: add pre-commit config"والمخرج سوف يكون كما يلي:
env: can't execute 'bash': No such file or directoryانظر مرة أخرى إلى السطر الأول من الوسيط: #!/usr/bin/env bash. الإطار يكتب الوسيط بلغة Bash، وجهاز المطور في مختبرنا Container من Alpine، وAlpine لا يأتي فيه Bash، وإنما Shell أصغر اسمه ash. فلم يستطع Git أن يشغل الخطاف أصلاً، وفشل ال Commit. وقد يبدو هذا خاصاً بالمختبر، ولكنه يظهر في الحياة الحقيقية في مكانين: Containers التطوير Dev Containers المبنية على Alpine، وخطوط CI التي تستخدم Image من Alpine وتشغل git commit داخلها، مثل خط يحدث ملفاً ويدفعه تلقائياً. والحل أن تثبت Bash، وهو ما فعلناه بالأمر apk add --no-cache bash، ولاحظ أن الخطأ هنا كان أفضل من البديل، فلم ينشأ Commit دون فحص، وإنما توقف كل شيء حتى أصلحنا البيئة.
التشغيل الأول First Run
أعدنا ال Commit نفسه، وقسنا الوقت:
time git commit -m "ci: add pre-commit config"والمخرج سوف يكون كما يلي:
[INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...............................................................Passed
check for added large files..............................................Passed
detect private key.......................................................Passed
block AWS access keys....................................................Passed
check yaml...........................................(no files to check)Skipped
detect private key.......................................................Passed
block AWS access keys....................................................Passed
commit message is "type: subject"........................................Passed
[main 612bf34] ci: add pre-commit config
1 file changed, 23 insertions(+)
create mode 100644 .pre-commit-config.yaml
real 0m 30.68s
user 0m 15.95s
sys 0m 4.83sفي المخرج أعلاه لاحظ التالي:
- أسطر
[INFO]الأربعة تحدث مرة واحدة فقط على كل جهاز: الإطار استنسخ مستودع pre-commit-hooks عند الوسم v6.0.0، وأنشأ له virtualenv وثبت فيه الحزمة. ولهذا أخذ ال Commit نحو ثلاثين ثانية. وبعد ذلك تستخدم البيئة نفسها، وحجم المجلد~/.cache/pre-commitبعد التجربة كلها كان 14.2 MB. - كل سطر فحص ينتهي بالكلمة Passed أو Failed أو Skipped. والفحص الذي لا توجد ملفات من نوعه يطبع
(no files to check)Skipped، فالإطار يعرف نوع كل ملف ويعطي كل فحص الملفات التي تخصه فقط. - وانظر إلى الأسطر بعد السطر السادس: check yaml وdetect private key وblock AWS access keys ظهرت مرة ثانية، ثم فحص الرسالة. وهذه مشكلتنا الثالثة، وسوف نعود إليها بعد قسم واحد.
pre-commit install يحتاج اتصالاً بالإنترنت ليستنسخ مستودعات الخطافات. فإذا كان فريقك يعمل في شبكة مغلقة، فانسخ هذه المستودعات إلى سيرفر Gitea الداخلي، واكتب عنوانها الداخلي في repo:، فالإطار يقبل أي عنوان Git.عندما تفشل الفحوص Failing Hooks
الآن نعيد الحادثين معاً في Commit واحد: ملف YAML فيه Tab ومسافات زائدة في آخر سطر، وملف deploy_key فيه مفتاح SSH خاص، وملف Python فيه مسافات زائدة وأسطر فارغة في آخره:
git add -A
git commit -m "feat: deploy settings"
git status --short
git diff --statوالمخرج سوف يكون كما يلي:
trim trailing whitespace.................................................Failed
- hook id: trailing-whitespace
- exit code: 1
- files were modified by this hook
Fixing config/app.yaml
Fixing src/app.py
fix end of files.........................................................Failed
- hook id: end-of-file-fixer
- exit code: 1
- files were modified by this hook
Fixing src/app.py
check yaml...............................................................Failed
- hook id: check-yaml
- exit code: 1
while scanning for the next token
found character '\t' that cannot start any token
in "config/app.yaml", line 3, column 1
check for added large files..............................................Passed
detect private key.......................................................Failed
- hook id: detect-private-key
- exit code: 1
Private key found: deploy_key
block AWS access keys....................................................Passed
MM config/app.yaml
A deploy_key
MM src/app.py
config/app.yaml | 2 +-
src/app.py | 4 +---
2 files changed, 2 insertions(+), 4 deletions(-)هذا المخرج يستحق أن نقرأه بهدوء، لأن فيه نوعين مختلفين من الفحوص:
- الفحصان الأولان من نوع المصلح Fixer: وجدا مشكلة فأصلحاها في الملف مباشرة، ثم فشلا مع السطر
files were modified by this hook. فلماذا يفشل فحص أصلح المشكلة؟ لأن الإصلاح حدث في مجلد العمل، وال Commit يأخذ منطقة التجهيز، فلو استمر ال Commit لدخلت النسخة غير المصلحة. لذلك يتوقف، ويتركك تراجع ما تغير. - وهذا ما يبينه
git status --short: الحرفانMMيعنيان أن الملف معدل في منطقة التجهيز، ومعدل مرة أخرى في مجلد العمل بعدها، أي إصلاحات الفحص. وgit diff --statيعرض هذه الإصلاحات وحدها: سطر في الإعدادات وأربعة أسطر في ملف Python. - الفحص الثالث من نوع المدقق Checker: وجد Tab في السطر الثالث من ملف YAML ولا يستطيع أن يصلحه، لأنه لا يعرف هل تريد مسافتين أم أربعاً، فأعطاك مكان الخطأ بالضبط. وهذا هو خطأ الحادث الثاني الذي أوقف الخدمة ساعة، ولم يأخذ هنا أكثر من ثانية.
- والرابع وجد المفتاح الخاص في
deploy_key، وهو ما كان سيمنع الحادث الأول. - والإطار شغل كل الفحوص حتى بعد أن فشل الأول، حتى ترى كل المشكلات مرة واحدة، ولا تصلح واحدة ثم تكتشف الثانية في المحاولة التالية.
أصلحنا الباقي بأنفسنا: أخرجنا deploy_key من التجهيز وأضفناه إلى .gitignore، واستبدلنا Tab بمسافتين، ثم جهزنا كل شيء من جديد بالأمر git add -A، الذي يجهز أيضاً إصلاحات المصلحات. والصورة التالية تلخص كيف يعمل الإطار من ملف الإعداد إلى النتيجة:

فحص الرسالة مع pygrep Commit Message Stage
بعد الإصلاح جربنا رسالة لا تتبع الصيغة، ثم الرسالة الصحيحة:
git commit -m "Deploy settings"
git commit -m "feat: deploy settings"والمخرج سوف يكون كما يلي:
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...............................................................Passed
check for added large files..............................................Passed
detect private key.......................................................Passed
block AWS access keys....................................................Passed
check yaml...........................................(no files to check)Skipped
detect private key.......................................................Passed
block AWS access keys....................................................Passed
commit message is "type: subject"........................................Failed
- hook id: conventional-commit
- exit code: 1
.git/COMMIT_EDITMSG
trim trailing whitespace.................................................Passed
...
commit message is "type: subject"........................................Passed
[main 1108ca5] feat: deploy settings
2 files changed, 1 insertion(+), 1 deletion(-)
create mode 100644 .gitignoreنجح الرفض، ولكن لاحظ أمرين. الأول أن رسالة الفشل لا تقول ما المشكلة، وإنما تطبع اسم الملف .git/COMMIT_EDITMSG فقط، لأن pygrep مع --negate يطبع أسماء الملفات التي لم تطابق، ولهذا اخترنا للخطاف اسماً يشرح القاعدة نفسها، فالاسم هو كل ما سوف يراه المطور. والثاني هو المشكلة الثالثة التي رأيناها في التشغيل الأول: ثلاثة فحوص ظهرت مرتين. ويشرح التوثيق السبب: الخطاف الذي لا تحدد له stages يعمل في كل المراحل، ونحن ثبتنا مرحلتين، فعند مرحلة commit-msg شغل الإطار هذه الفحوص مرة ثانية على ملف الرسالة نفسه، فبحث عن مفتاح خاص وعن مفتاح AWS داخل رسالة ال Commit. وهذا ليس خطيراً، ولكنه وقت ضائع في كل Commit، وقد يرفض رسالة فيها نص يشبه مفتاحاً. والحل سطر واحد في أول الملف:
default_install_hook_types: [pre-commit, commit-msg]
default_stages: [pre-commit]
repos:default_stages يحدد المرحلة الافتراضية لكل خطاف لم يحدد مراحله، فتعمل الفحوص على الملفات قبل ال Commit فقط، ويبقى فحص الرسالة في مرحلته لأننا كتبنا له stages صراحة. وال Commit التالي أظهر الفرق:
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...............................................................Passed
check for added large files..............................................Passed
detect private key.......................................................Passed
block AWS access keys....................................................Passed
commit message is "type: subject"........................................Passed
[main 36d6684] ci: run file hooks only before the commit
1 file changed, 1 insertion(+)سبعة أسطر بدلاً من عشرة، وكل فحص في مكانه.
كل الملفات مع الخيار SKIP: All Files
عند كل Commit يفحص الإطار الملفات المجهزة فقط، وهذا ما يجعله سريعاً. ولكن عندما تضيف الإطار إلى مشروع قديم، أو تضيف فحصاً جديداً، فالملفات القديمة لم يفحصها أحد. والأمر التالي يشغل كل الفحوص على كل ملفات المستودع:
pre-commit run --all-filesوالمخرج سوف يكون كما يلي:
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...............................................................Passed
check for added large files..............................................Passed
detect private key.......................................................Passed
block AWS access keys....................................................Passedوفي مشروع حقيقي قديم سوف يكون المخرج الأول طويلاً، وسوف تعدل المصلحات عشرات الملفات. لذلك اجعل هذا التشغيل الأول Commit مستقلاً لا يحمل أي تغيير آخر، حتى لا يختلط إصلاح المسافات في مئة ملف مع تغيير حقيقي في مراجعة الكود. وينصح التوثيق أيضاً بأن تضيف هذا الأمر نفسه خطوة في خط CI، فيفحص كل شيء عند كل دفع حتى لو تخطى أحدهم الخطافات على جهازه، وسوف نعود إلى هذه الفكرة عند ترتيب الطبقات.
وأحياناً تحتاج أن تتخطى فحصاً واحداً دون الباقي، مثل ملف YAML معطوب عن قصد في اختبار. وبدلاً من --no-verify الذي يتخطى كل شيء، يقبل الإطار متغير البيئة SKIP بقائمة معرفات الفحوص مفصولة بفواصل:
SKIP=check-yaml git commit -m "test: broken yaml on purpose"والمخرج سوف يكون كما يلي:
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml..............................................................Skipped
check for added large files..............................................Passed
detect private key.......................................................Passed
block AWS access keys....................................................Passed
commit message is "type: subject"........................................Passed
[main 365db54] test: broken yaml on purpose
1 file changed, 1 insertion(+)
create mode 100644 config/broken.yamlتخطى الإطار فحص YAML وحده، وبقي فحص الأسرار والرسالة يعمل. وهذا الفرق مهم في ثقافة الفريق: المطور الذي يحتاج أن يتخطى فحصاً واحداً لسبب واضح لا يجب أن يطفئ كل شيء. ثم أرجعنا هذا ال Commit لأنه كان تجربة.
تحديث إصدارات الفحوص Autoupdate
القيمة rev: v6.0.0 ثابتة عن قصد، فلن تتغير الفحوص تحت قدميك يوم الخميس دون أن يعرف أحد. ولكن هذا يعني أن تحديثها مسؤوليتك. والأمر pre-commit autoupdate يغير كل rev في الملف إلى آخر وسم في المستودع، كما يذكر توثيقه، فتنفذه مرة في الشهر مثلاً، وتشغل بعده pre-commit run --all-files، وتدخل النتيجة في طلب دمج Pull Request يراجعه زميل مثل أي تغيير آخر. وتذكر أن مستودعات الخطافات كود يعمل على أجهزة كل الفريق، فاختر مستودعات معروفة، واقرأ ما تغير قبل أن ترفع الإصدار، تماماً كما تفعل مع أي مكتبة.
ماذا تضع في الخطافات؟ What Belongs in a Hook
بعد أن رأيت سهولة إضافة الفحوص، سوف تغريك فكرة أن تضع كل شيء في pre-commit: الاختبارات، والبناء، وفحص الأنواع على المشروع كله. ولا تقم بذلك. والسبب أن pre-commit يعمل عشرات المرات في اليوم لكل مطور، وكل ثانية فيه تتضاعف، والمطور الذي ينتظر دقيقة عند كل Commit سوف يبدأ بجمع تغييراته في Commits كبيرة حتى ينتظر مرة واحدة، أو يتعلم --no-verify. والقاعدة العملية التي تعمل في أغلب الفرق ثلاث نقاط:
- في pre-commit: الفحوص السريعة التي تعمل على الملفات المجهزة وحدها وتنتهي في ثوان: التنسيق Formatting، وأدوات Lint السريعة، وصحة ملفات YAML وJSON، والأسرار، والملفات الكبيرة.
- في pre-push: ما يأخذ وقتاً أطول قليلاً وله معنى قبل أن يرى الفريق عملك، مثل الاختبارات السريعة للوحدات Unit Tests التي تلمس ما غيرته. وتضيفه بكتابة
stages: [pre-push]للفحص، وpre-pushفيdefault_install_hook_types. - في خط CI: كل ما هو بطيء أو يحتاج بيئة كاملة: الاختبارات كلها، والبناء، واختبارات التكامل، والفحص الأمني للمكتبات. وكذلك
pre-commit run --all-filesنفسه، لأنه الضمان الوحيد أن الفحوص عملت فعلاً.
وفي فريقنا كان أسوأ ما يمكن أن يحدث أن يصبح الإطار مصدر إزعاج فيطفئه الناس، لذلك أضفنا فحصاً واحداً فقط في كل مرة، وشرحنا للفريق لماذا أضفناه، وأي حادث كان سيمنعه. وكل فحص يرفض كوداً صحيحاً، مثل خطاف perf في بداية المقال، نصلحه في اليوم نفسه.
خطافات السيرفر Server-side Hooks
رأينا أن كل ما بنيناه حتى الآن يتخطاه سطر واحد. فإذا كانت عندك قاعدة لا تقبل أي استثناء، مثل «لا يدخل مفتاح وصول إلى أي فرع على السيرفر»، فمكانها السيرفر. وعندما يستقبل السيرفر دفعاً، يشغل الخطاف pre-receive مرة واحدة قبل أن يحدث أي فرع، ويعطيه في الإدخال القياسي سطراً لكل فرع أو وسم يدفع بالصيغة old-oid new-oid ref-name، أي رقم ال Commit الذي كان الفرع يشير إليه، والرقم الجديد، واسم الفرع. فإذا خرج بغير الصفر لا يتحدث أي فرع في هذا الدفع، كما يقول التوثيق، وكل ما يطبعه يصل إلى المطور الذي يدفع. وبعده يعمل الخطاف update مرة لكل فرع، ويستطيع أن يرفض فرعاً واحداً ويقبل الباقي، ثم post-receive بعد أن يتحدث كل شيء، وهو لا يرفض شيئاً، ويستخدم للإشعارات وبدء العمليات.
لماذا يغلقها Gitea افتراضياً؟ DISABLE_GIT_HOOKS
في Gitea تستطيع أن تكتب خطافات السيرفر لكل مستودع من صفحة إعداداته، ولكن هذه الصفحة لا تظهر افتراضياً، لأن الإعداد DISABLE_GIT_HOOKS في القسم [security] قيمته الافتراضية true. والسبب مكتوب بوضوح في دليل إعدادات Gitea، في تحذير يستحق أن تقرأه كاملاً: الخطافات المخصصة تسمح بتنفيذ أي كود على نظام التشغيل الذي يعمل عليه Gitea، وبالتالي من يكتبها يستطيع أن يقرأ ملف الإعدادات ويعدل قاعدة البيانات ويوقف الخدمة، ومن يعدل قاعدة البيانات يستطيع أن يجعل نفسه مدير الموقع، ويستطيع أن يصل إلى أي شيء يصل إليه مستخدم نظام التشغيل الذي يشغل Gitea. أي أن صلاحية كتابة خطاف تساوي عملياً صلاحية مدير السيرفر كله. ويذكر التحذير أيضاً أن إرجاع الإعداد إلى true لا يحذف الخطافات الموجودة في المستودعات، فإذا فعلتها ثم ندمت فعليك أن تنظفها بنفسك.
لذلك القرار هنا ليس تقنياً فقط. في سيرفر Gitea يديره شخص واحد أو فريق صغير يثق كل أفراده ببعض، تفعيل الخطافات للمدير وحده مقبول. أما في سيرفر يستخدمه أكثر من فريق، أو فيه مستخدمون من خارج الشركة، فلا تفعلها، واستخدم بدلاً منها حماية الفروع وخطوط CI كما سوف نرى. وفي المختبر لم يحصل على هذه الصلاحية إلا المدير، ويمكن أن تعطى لمستخدم عادي من لوحة الإدارة بخيار «يمكنه إنشاء Git Hooks»، وهذا ما يحذر منه التحذير نفسه.
كتابة pre-receive عبر Gitea API
كتبنا أول نسخة من الخطاف، وهي تقرأ كل سطر من الإدخال، وتعرض كل التغييرات الجديدة في الفرع، وتبحث فيها بالتعبير نفسه الذي استخدمناه على الجهاز:
#!/bin/sh
# Server-side check, version 1: reject pushes whose new commits add an AWS key or a private key.
status=0
while read old new ref; do
if git log -p "$old..$new" | grep -nE '^\+.*(AKIA[0-9A-Z]{16}|BEGIN [A-Z ]*PRIVATE KEY)'; then
echo "pre-receive: $ref adds something that looks like a secret, push refused" >&2
status=1
fi
done
exit $statusوالصيغة $old..$new تعني كل ال Commits التي يصل إليها الرقم الجديد ولا يصل إليها القديم، أي ما يضيفه هذا الدفع. والمتغير status يجمع النتيجة حتى نفحص كل الفروع ونطبع كل المشكلات قبل أن نخرج. ويمكن أن تلصق الخطاف في صفحة إعدادات المستودع، ولكننا استخدمنا Gitea API حتى يكون المختبر قابلاً للتكرار. أولاً سألنا عن الخطافات بصفتين:
curl -s -u dev1:Lab-Pass-2026! http://dv2g-gitea:3000/api/v1/repos/dev1/shop-api/hooks/git
curl -s -u admin1:Lab-Pass-2026! http://dv2g-gitea:3000/api/v1/repos/dev1/shop-api/hooks/gitوالمخرج سوف يكون كما يلي:
{"message":"must be allowed to edit Git hooks","url":"http://dv2g-gitea:3000/api/swagger"}
[{"name":"pre-receive","is_active":false},{"name":"update","is_active":false},{"name":"post-receive","is_active":false}]dev1 صاحب المستودع، ومع ذلك رفض Gitea طلبه برسالة واضحة، لأن ملكية المستودع لا تعطي صلاحية الخطافات كما شرحنا. أما المدير فرأى الخطافات الثلاثة التي يسمح Gitea بكتابتها، وكلها غير فعالة. ثم أرسل المدير محتوى الملف:
jq -Rs '{content: .}' /lab/pre-receive-v1.sh | curl -s -u admin1:Lab-Pass-2026! -X PATCH \
-H 'Content-Type: application/json' -d @- \
http://dv2g-gitea:3000/api/v1/repos/dev1/shop-api/hooks/git/pre-receive | jq '{name, is_active}'والمخرج سوف يكون كما يلي:
{
"name": "pre-receive",
"is_active": true
}الأمر jq -Rs يقرأ الملف كله كنص واحد ويضعه في حقل content بصيغة JSON صحيحة، فلا نقلق من علامات التنصيص والأسطر الجديدة داخل السكربت. وأصبح الخطاف فعالاً.
الدفع الذي رفضه السيرفر Rejected Push
الآن نعيد الحادث الأول بأسوأ شكل: المطور يتخطى كل خطافات جهازه، ثم يدفع إلى main مباشرة:
printf 'AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE\n' > .env
git add -f .env
git commit --no-verify -qm "chore: local settings" && git push origin main
git log --oneline -2 origin/mainوالمخرج سوف يكون كما يلي، دون سطر warning: redirecting الذي يطبعه Git في هذا المختبر:
remote: 13:+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
remote: pre-receive: refs/heads/main adds something that looks like a secret, push refused
To http://dv2g-gitea:3000/dev1/shop-api.git
! [remote rejected] main -> main (pre-receive hook declined)
error: failed to push some refs to 'http://dv2g-gitea:3000/dev1/shop-api.git'
36d6684 ci: run file hooks only before the commit
1108ca5 feat: deploy settingsفي المخرج أعلاه لاحظ التالي:
- كل سطر يبدأ بالكلمة
remote:طبعه الخطاف على السيرفر، ونقله Git إلى المطور. فالمطور يرى السطر الذي فيه السر ورسالة الرفض، كأن الخطاف يعمل على جهازه. - السطر
[remote rejected] ... (pre-receive hook declined)هو حكم السيرفر: الفرع main لم يتحدث. - والتأكيد في آخر سطرين:
origin/mainما زال على 36d6684، أي أن ال Commit الذي فيه السر بقي على جهاز المطور فقط، ولم يره أحد غيره. وهذا هو الفرق الكبير بين المنع والاكتشاف: السر الذي لم يصل إلى السيرفر لا يحتاج أن تغير المفتاح.
كيف يرتب Gitea خطافاته؟ Hook Layout
قد تسأل: Gitea نفسه يحتاج pre-receive ليطبق حماية الفروع ويتحقق من الصلاحيات، فأين ذهب خطافه عندما كتبنا خطافنا؟ نظرنا داخل المستودع على السيرفر:
docker exec dv2g-gitea ls /data/git/repositories/dev1/shop-api.git/hooks/pre-receive.d
docker exec dv2g-gitea cat /data/git/repositories/dev1/shop-api.git/hooks/pre-receiveوالمخرج سوف يكون كما يلي:
gitea
pre-receive
#!/usr/bin/env bash
# AUTO GENERATED BY GITEA, DO NOT MODIFY
data=$(cat)
exitcodes=""
hookname=$(basename $0)
GIT_DIR=${GIT_DIR:-$(dirname $0)/..}
for hook in ${GIT_DIR}/hooks/${hookname}.d/*; do
test -x "${hook}" && test -f "${hook}" || continue
echo "${data}" | "${hook}"
exitcodes="${exitcodes} $?"
done
for i in ${exitcodes}; do
[ ${i} -eq 0 ] || exit ${i}
doneالخطاف الحقيقي الذي يشغله Git موزع صغير كتبه Gitea: يقرأ الإدخال مرة واحدة، ثم يمرره إلى كل ملف قابل للتنفيذ في المجلد pre-receive.d، ويجمع رموز الخروج، فإذا فشل أي واحد منها فشل الدفع. وفي المجلد ملفان: gitea وهو خطاف Gitea نفسه الذي يستدعي gitea hook، وpre-receive وهو خطافنا. ولاحظ أن الموزع لا يتوقف عند أول فشل، فكل الخطافات تعمل دائماً، ولهذا لا يستطيع خطافنا أن يعطل فحوص Gitea، ولا العكس. والصورة التالية تبين هذا الترتيب مع المسار كاملاً:

ماذا لو كان الفرع جديداً؟ What If: Zero OID
الخطاف يعمل على main. فماذا لو دفع المطور ال Commit نفسه، بالسر نفسه، إلى فرع جديد بدلاً من main؟ هذا ما يفعله أي مطور يفتح طلب دمج، لذلك جربناه:
git switch -q -c feature/settings && git push origin feature/settings
git ls-remote originوالمخرج سوف يكون كما يلي:
remote: fatal: Invalid revision range 0000000000000000000000000000000000000000..796ee7fa71b3d881518f31a38596f9b46771bc5f
remote:
remote: Create a new pull request for 'feature/settings':
remote: http://dv2g-gitea:3000/dev1/shop-api/pulls/new/feature/settings
remote:
To http://dv2g-gitea:3000/dev1/shop-api.git
* [new branch] feature/settings -> feature/settings
36d66842390b3fcb881171b16837bf6709f8af8f HEAD
796ee7fa71b3d881518f31a38596f9b46771bc5f refs/heads/feature/settings
36d66842390b3fcb881171b16837bf6709f8af8f refs/heads/mainدخل السر إلى السيرفر. وهذا أخطر خطأ في المقال، لأن كل شيء بدا يعمل في التجربة الأولى. والسبب في السطر الأول: عندما يكون الفرع جديداً لا يوجد رقم قديم، فيضع Git مكانه أربعين صفراً، كما يقول التوثيق «عند إنشاء مرجع جديد يكون old-oid اسم الكائن المكون من أصفار». وخطافنا بنى المدى 0000...0000..796ee7f، ولا يوجد Commit بهذا الرقم، فخرج git log بخطأ fatal دون أي مخرج. والأنبوب Pipe أعطى grep نصاً فارغاً، فلم يجد شيئاً، فاعتبر الشرط غير متحقق، وخرج الخطاف بالصفر. أي أن خطأ في الأداة فسر على أنه «نظيف»، وهذا هو النمط الذي يجب أن تبحث عنه في أي فحص أمني: ماذا يحدث عندما يفشل الفحص نفسه؟ والجواب الصحيح دائماً أن يرفض، أي Fail Closed، وليس أن يقبل.
والنسخة الثانية تعالج الحالتين الخاصتين: فرع جديد، وفرع محذوف حيث يكون الرقم الجديد هو الأصفار:
#!/bin/sh
# Server-side check, version 2: also handles new branches (old = 40 zeros) and deleted refs (new = 40 zeros).
zero=0000000000000000000000000000000000000000
status=0
while read old new ref; do
[ "$new" = "$zero" ] && continue # branch deleted: nothing to scan
if [ "$old" = "$zero" ]; then range="$new --not --all" # new branch: only commits the server does not have yet
else range="$old..$new"; fi
if git log -p $range | grep -nE '^\+.*(AKIA[0-9A-Z]{16}|BEGIN [A-Z ]*PRIVATE KEY)'; then
echo "pre-receive: $ref adds something that looks like a secret, push refused" >&2
status=1
fi
done
exit $statusوالجزء المهم $new --not --all: كل ال Commits التي يصل إليها الرقم الجديد، ما عدا التي يصل إليها أي فرع موجود على السيرفر. وأثناء pre-receive لم يتحدث أي فرع بعد، فهذه هي بالضبط ال Commits الجديدة التي يحملها الدفع، ولا نفحص تاريخ main كله من جديد مع كل فرع. ثبتنا النسخة الثانية بالأمر نفسه، وحذفنا الفرع الذي تسرب، ودفعناه مرة أخرى:
git push origin --delete feature/settings
git push origin feature/settingsوالمخرج سوف يكون كما يلي:
To http://dv2g-gitea:3000/dev1/shop-api.git
- [deleted] feature/settings
remote: 13:+AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
remote: pre-receive: refs/heads/feature/settings adds something that looks like a secret, push refused
To http://dv2g-gitea:3000/dev1/shop-api.git
! [remote rejected] feature/settings -> feature/settings (pre-receive hook declined)
error: failed to push some refs to 'http://dv2g-gitea:3000/dev1/shop-api.git'الحذف مر لأن الخطاف يتخطى الفروع المحذوفة، والفرع الجديد رفض هذه المرة. ثم تأكدنا أن الخطاف لا يرفض العمل العادي: Commit نظيف إلى main مر بالرقمين 36d6684..4083915، وفرع جديد feature/docs فيه README فقط مر أيضاً مع رسالة Gitea التي تقترح فتح طلب دمج. والصورة التالية تقارن النسختين:

وفي خطاف حقيقي للإنتاج أضف أيضاً set -o pipefail إذا كتبته بلغة Bash، حتى يفشل الأنبوب كله إذا فشل git log، وأضف حداً لعدد ال Commits أو للوقت، لأن دفع فرع فيه آلاف ال Commits إلى مستودع كبير يعني أن الخطاف يقرأ فروقها كلها، والمطور ينتظر أمام شاشة لا تتحرك.
السر وصل فعلاً: Leaked Secret
في الحالة التي مر فيها السر إلى فرع جديد، حذفنا الفرع، ولكن هل اختفى السر؟ لا. فال Commit ربما ما زال في المستودع على السيرفر حتى يحذفه التنظيف الدوري Garbage Collection، وربما سحبه زميل أو خط CI قبل أن تحذفه، وربما ظهر في إشعار بريد أو في سجل Webhook. لذلك القاعدة الأولى عند تسرب أي سر هي أن تعتبره مكشوفاً، وأن تلغيه وتصدر بديلاً منه من لوحة المزود قبل أي شيء آخر، ثم تنظف التاريخ إذا احتجت. وقد شرحنا خطوات التنظيف وحدودها في التراجع عن الأخطاء في Git، والبحث عن الأسرار القديمة في التاريخ كله في اكتشاف الأسرار المسربة. والخطافات لا تغني عن أي من ذلك، هي فقط تجعل هذا اليوم السيئ نادراً.
أين تضع كل فحص؟ Defense Layers
جمعنا الآن ثلاث طبقات، ولكل طبقة مكان. والسؤال العملي ليس «أي طبقة أفضل»، وإنما «ما الذي يجب أن يكون في كل طبقة»، والجدول التالي هو الذي استقر عليه فريقنا:
| الطبقة | من يتحكم فيها | السرعة | هل تتخطى؟ | ماذا تضع فيها |
|---|---|---|---|---|
| خطافات الجهاز مع pre-commit | المطور، بملف في المستودع | ثوان، قبل ال Commit | نعم | التنسيق، Lint، YAML، الأسرار، الملفات الكبيرة، صيغة الرسالة |
| pre-receive على Gitea | مدير السيرفر | ثوان، عند الدفع | لا | قواعد قليلة لا تقبل استثناء: الأسرار، الملفات الضخمة، أسماء الفروع |
| خط CI مع حماية الفروع | الفريق، بملف في المستودع | دقائق، بعد الدفع | لا يدمج طلب دون نجاحه | الاختبارات، البناء، pre-commit run --all-files، فحص المكتبات |
ولاحظ أن الطبقة الثالثة لا تمنع الكود من الوصول إلى السيرفر، فهو يصل إلى فرع جانبي، ولكنها تمنعه من الدخول إلى main، لأن حماية الفرع Branch Protection في Gitea تستطيع أن تطلب نجاح فحوص الحالة Status Checks قبل الدمج، كما في توثيق حماية الفروع. وهذا كاف لأغلب القواعد، لأن ما يهمك غالباً هو ما يدخل main وما ينشر، وليس ما يكتبه المطور في فرعه. أما الأسرار فاستثناء، لأن السر الذي وصل إلى أي فرع على السيرفر قد تسرب فعلاً، ولهذا وضعناها في الطبقة الثانية. وإذا لم تستطع أن تفعل خطافات السيرفر، كما في سيرفر Gitea مشترك، فاجعل فحص الأسرار أول خطوة في خط CI، واقبل أن السر سوف يكتشف بعد دقيقة من وصوله بدلاً من أن يمنع. وقد شرحنا حماية الفرع مع طلبات الدمج في مراجعة الكود Code Review، وتشغيل خطوط CI على سيرفرك في Gitea Actions.

وكيف تفعل هذا في المنصات المستضافة؟ GitHub.com وGitLab.com لا يسمحان بكتابة خطافات سيرفر مخصصة على خدماتهما المشتركة، للسبب الأمني نفسه الذي رأيناه في Gitea، ولكن كلاً منهما يقدم فحوصاً جاهزة في مكانها، مثل Push Protection في GitHub الذي يرفض الدفع إذا وجد سراً معروفاً. أما النسخ التي تستضيفها بنفسك فتسمح بها: GitHub Enterprise Server يدعم خطافات pre-receive، وGitLab يسميها Server Hooks ويضعها المدير على السيرفر. فالفكرة واحدة في كل مكان: من يدير السيرفر هو من يكتب خطافاته.
أخطاء شائعة Common Mistakes
- خطاف دون صلاحية التنفيذ: يتجاهله Git ويطبع تلميحاً سهل التجاهل. تأكد بالأمر
ls -l، وفي المستودع بالنمط100755. - فحص مجلد العمل بدلاً من منطقة التجهيز: ال Commit يأخذ ما جهزته، فافحص
git diff --cachedأو اترك الإطار يعطيك الملفات الصحيحة. - قاعدة أضيق من اتفاق الفريق: مثل نسيان النوع perf، فيرفض الخطاف عملاً صحيحاً ويتعلم الفريق
--no-verify. - الاعتماد على خطافات الجهاز لقاعدة إلزامية: تتخطى بسطر واحد، ولا تنسخ مع clone. القواعد الإلزامية مكانها السيرفر أو خط CI.
- اسم فرع في
rev: لا يقبله الإطار، والوسم الثابت هو ما يجعل كل الفريق يشغل الفحص نفسه. - فحوص بطيئة في pre-commit: الاختبارات الكاملة والبناء مكانها pre-push أو CI.
- نسيان
default_stages: فتعمل فحوص الملفات مرة ثانية على ملف الرسالة. - خطاف سيرفر لا يعالج الفرع الجديد: الرقم القديم أربعون صفراً، و
git logيفشل، والخطاف يقبل. اجعل الفحص يرفض عندما يفشل هو نفسه. - تفعيل خطافات Gitea لمستخدمين لا تثق بهم: كتابة الخطاف تساوي صلاحية مدير السيرفر.
- اعتبار السر آمناً لأن الفرع حذف: ألغ السر أولاً، ثم نظف.
قائمة تحقق Checklist
- ملف
.pre-commit-config.yamlفي جذر كل مستودع، بإصدارات ثابتة فيrev، وdefault_stages: [pre-commit]. - سطر في README يقول للمطور الجديد:
pip install pre-commitثمpre-commit install، ويفضل أن يكون جزءاً من سكربت تجهيز بيئة التطوير. - Commit مستقل لأول
pre-commit run --all-filesعلى المشروع القديم. - فحص للأسرار في pre-commit، وفي خط CI، وعلى السيرفر إذا كنت تملكه.
- خطوة
pre-commit run --all-filesفي خط CI، وحماية الفرع main تطلب نجاحها. pre-commit autoupdateمرة في الشهر في طلب دمج يراجع.- على Gitea:
DISABLE_GIT_HOOKSمغلق إلا إذا كان المدير وحده من يكتب الخطافات، وكل خطاف سيرفر مجرب على فرع جديد وفرع محذوف ودفع كبير. - خطة مكتوبة لما تفعله عند تسرب سر: إلغاؤه أولاً، ثم التنظيف.
ماذا تقرأ بعد ذلك؟ Next Steps
دليلمراجعة الكود Code Review: كيف تراجع Pull Request بفائدةكيف تفتح طلب دمج يسهل على زميلك مراجعته، وكيف تراجع طلب غيرك بتعليقات تحسن الكود دون أن تتحول إلى موافقة شكلية أو جدال، مع حماية الفرع main في Gitea.
دليلSecrets Scanning: كيف تكتشف الأسرار المسربة في الكودكيف يخرج المفتاح من جهازك إلى تاريخ Git وخط CI، وكيف تكتشفه قبل غيرك، وماذا تفعل في الساعة الأولى بعد تسربه.
دليلGitea Actions: تشغيل CI/CD وبناء Docker Images على سيرفركاجعل سيرفرك يختبر الكود ويبني Docker Images تلقائياً مع كل push، دون أن يخرج كودك أو أسرارك إلى خدمة CI خارجية.
دليلالتراجع عن الأخطاء في Git: revert أم reset أم restore؟لكل خطأ في Git أمر تراجع يناسب المكان الذي وصل إليه، وهنا تتعلم أن تختاره بسؤال واحد، وأن تسترجع عملاً ظننت أنه ضاع.الخطوة التالية بعد الفحوص أن تعرف من كتب الكود فعلاً، فاسم الكاتب في ال Commit يكتبه أي شخص بالأمر git config، وهذا ما يحله توقيع ال Commits. وإذا أردت أن تنقل فحوصك إلى خط CI يعمل على سيرفرك فاقرأ Gitea Actions، ومفهوم CI/CD نفسه في مفهوم CI/CD للمبتدئين. والخريطة الكاملة لمقالات Git في Git في العمل اليومي.
الخلاصة Summary
- الخطاف برنامج يشغله Git عند لحظة محددة، وإذا خرج بغير الصفر قبل العملية توقفت. ويجب أن يكون قابلاً للتنفيذ وإلا تجاهله Git.
- خطافات الجهاز مثل pre-commit وcommit-msg سريعة وتمنع الخطأ غير المقصود، ولكن
--no-verifyيتخطاها، ولا تنسخ معgit cloneلأسباب أمنية. - إطار pre-commit يجعل الفحوص ملفاً واحداً في المستودع بإصدارات ثابتة، ويثبت كل أداة في بيئة معزولة، ويعطي كل فحص الملفات المجهزة التي تخصه.
- المصلحات تعدل الملف وتفشل حتى تجهز التعديل، والمدققات تعطيك مكان الخطأ. و
SKIPيتخطى فحصاً واحداً بدلاً من كل شيء. - خطافات السيرفر مثل pre-receive لا يتخطاها أحد، وفي Gitea تغلق افتراضياً لأن كتابتها تساوي صلاحية مدير السيرفر.
- خطاف السيرفر يجب أن يعالج الفرع الجديد الذي رقمه القديم أصفار، وأن يرفض عندما يفشل الفحص نفسه.
- ضع الفحص السريع على الجهاز، والقاعدة التي لا تقبل استثناء على السيرفر، والبطيء في خط CI مع حماية الفرع main.
سجل التحديثات Changelog
- نوفمبر 2026: كتابة المقال، وتنفيذ كل الأمثلة على git 2.54.0 وpre-commit 4.7.0 مع pre-commit-hooks v6.0.0 داخل Container من python:3.13-alpine، وخطاف pre-receive على Gitea 28.3.0.