انتقل إلى المحتوى

Protected branches

الـ protected branch قاعدة تحمي branch مهمًّا مثل main: تمنع الـ push المباشر إليه، وتمنع الـ force push، وتشترط عددًا من الـ approvals قبل الـ merge، وتربطه بنجاح الفحوص الآلية. وتسري القاعدة على كل الطرق: Git عبر HTTPS و SSH، ومحرّر الويب، وواجهة API، والمهام الخلفية مثل auto-merge.

إدارة هذه القواعد تحتاج أن تكون owner الـ repository أو ذا صلاحية admin؛ راجع Permissions. وإن كان الـ repository مؤرشفًا فصفحة الـ branches للقراءة فقط.

إنشاء قاعدة أو تعديلها

  1. افتح الـ repository ثم Settings ← Branches.
  2. اضغط Add new rule أو Edit بجانب قاعدة موجودة.
  3. املأ Protected branch name pattern واضبط الخيارات المشروحة أدناه.
  4. اضغط Save rule.

تسري القاعدة فورًا على كل الـ branches المطابقة، حتى ما سيُنشأ منها لاحقًا.

مطابقة الأنماط وأولويتها

  • حقل Protected branch name pattern يقبل تعابير glob ويطابق اسم الـ branch كاملًا، مع التمييز بين الحروف الكبيرة والصغيرة. أمّا الاسم البسيط بلا رموز خاصة مثل main فيطابق ذلك الـ branch بعينه دون تمييز الحروف.
  • إن طابقت أكثر من قاعدة الـ branch نفسه فلا تُطبَّق إلا القاعدة الأولى. أعد ترتيب القواعد بالسحب من مقبض الترتيب؛ القاعدة الأولى (أولوية 1) هي الأعلى، فضع الأنماط المحدّدة مثل main أو release/* قبل الأنماط العامة مثل *.

أمثلة:

النمط يطابق
main الـ branch main فقط
release/* release/v1.0، release/april
hotfix/** الـ branches المتداخلة مثل hotfix/security/CVE
* كل الـ branches (استخدمه قاعدةً احتياطية)

أنماط الملفات

  • Protected file patterns تمنع تعديل ملفات حسّاسة (مثل .drone.yml أو /docs/**/*.txt)؛ أي commit أو merge يمسّ أحدها يُرفض. الأنماط لا تميّز الحروف الكبيرة من الصغيرة، وتُفصل بفاصلة منقوطة ;.
  • Unprotected file patterns تفعل العكس: إن كان الـ push ممنوعًا، يستطيع من له صلاحية write أن ينفّذ push لـ commits تعدّل هذه الملفات وحدها؛ مفيد لتحديث صفحات الدليل مباشرة مع إبقاء الكود خلف الـ pull requests.

الحقلان يستخدمان صياغة glob نفسها، والمسارات نسبية إلى جذر الـ repository.

التحكّم بالـ push المباشر

قسم Push يتحكّم بالـ push المباشر إلى الـ branch (بما فيه محرّر الويب وواجهة API):

  • Disable push: الـ branch للقراءة فقط، ولا تدخل التغييرات إلا عبر pull requests.
  • Enable push: ينفّذ push كل من له صلاحية write (الـ force push يبقى ممنوعًا ما لم تسمح به صراحة).
  • Allowlist restricted push: لا ينفّذ push إلا من في القائمة: مستخدمون، وفي repositories الـ organization teams، و deploy keys ذات صلاحية write.

عند منع الـ push يرفض الخادم التحديث ويعرض سبب الرفض في الطرفية.

الـ force push

للـ force push خيارات مستقلة:

  • Disable force push: يمنع إعادة كتابة تاريخ الـ branch نهائيًا.
  • Enable force push: كل من يستطيع الـ push يستطيع الـ force push.
  • Allowlist restricted force push: قائمة منفصلة، ويشترط أن يكون للشخص صلاحية push عادية أصلًا.

الـ merge والـ approvals

  • Merge allowlist: افتراضيًا ينفّذ الـ merge كل من له صلاحية write؛ فعّلها لتحصر الـ merge بمستخدمين أو teams محدّدين.
  • Required approvals: عدد الـ approvals اللازمة قبل الـ merge. تُحتسب reviews كل من له صلاحية write، إلا إن فعّلت Restrict approvals to allowlisted users or teams.
  • Dismiss stale approvals: يُلغي الـ approvals كلّما جرى push لـ commits جديدة تغيّر محتوى الـ pull request.
  • Ignore stale approvals: يُبقي الـ approvals لكنه لا يحتسب الـ reviews التي جرت على commits أقدم؛ معطّل ما دام الخيار السابق مفعّلًا.
  • Block merge on rejected reviews: ما دام reviewer رسمي طالبًا بتعديلات، لا merge.
  • Block merge on official review requests: لا merge ما دامت هناك طلبات review معلّقة (مثلًا حين يشترط ملف CODEOWNERS مراجعة).
  • Block merge if the pull request is outdated: يجب أن يكون branch الطلب محدَّثًا بآخر تغييرات الـ branch الهدف قبل الـ merge.
  • Administrators must follow branch protection rules: يزيل زر Force merge الذي يتجاوز به المديرون القواعد.

الـ protected file patterns تسري على الـ pull requests أيضًا: إن غيّر طلبٌ ملفًا محميًا ظهرت المسارات المتأثرة في شريط الطلب وبقي الـ merge معطّلًا.

الـ status checks

فعّل الـ status checks لتشترط نجاح مهمة واحدة أو أكثر من التكامل المستمر (CI) قبل الـ merge:

  1. علّم Enable status check.
  2. اكتب نمطًا في كل سطر داخل Status check patterns؛ كل نمط تعبير glob يطابق اسم السياق الذي تبلّغ عنه Actions أو أي أداة فحص أخرى، مثل actions/test-*.
  3. تحقّق من الأسماء عبر جدول المهام التي بلّغت عن نتائج خلال الأسبوع الماضي.

يشترط ليڤانت غيت عندها أن يبلّغ سياق مطابق لكل نمط بالنجاح على آخر commit في الـ pull request. لا تُقبل قائمة فارغة؛ استخدم * لاشتراط نجاح آخر commit أيًّا كان اسم السياق.

الـ signed commits وضمانات أخرى

  • Require signed commits: يرفض أي push يحوي commits غير موقّعة أو يتعذّر التحقق من توقيعها (التوقيع بـ GPG)، قبل قبول الـ push على الخادم.
  • Protected file patterns وUnprotected file patterns (أعلاه) تكملان الحماية على مستوى الملفات.

نصيحة

إعداد بسيط يكفي أغلب المشاريع: قاعدة على main مع Disable push و approval واحد مطلوب، فتمرّ كل التغييرات عبر pull requests.

أسئلة شائعة

كيف أحمي branch الـ main من الـ push المباشر؟

افتح الـ repository ثم Settings ← Branches، واضغط Add new rule، واكتب main في حقل النمط، واختر Disable push، ثم احفظ القاعدة. بعدها لا يدخل أي تغيير إلى main إلا عبر pull request مدموج. تحتاج لهذا صلاحية admin على الـ repository أو أن تكون owner له.

هل يستطيع مدير الـ repository تجاوز حماية الـ branch؟

نعم افتراضيًا؛ يظهر لمن يملك صلاحية admin زر Force merge يتجاوز به القواعد عند الحاجة. لإلغاء هذا الاستثناء فعّل الخيار Administrators must follow branch protection rules في القاعدة نفسها، فتسري عليه كما تسري على غيره ويختفي الزر من صفحة الـ pull request.

كيف أشترط عدد approvals قبل الـ merge؟

اكتب العدد المطلوب في حقل Required approvals داخل قاعدة الحماية. تُحتسب reviews كل من له صلاحية write، إلا إن حصرتها بقائمة مسموح بها. وتستطيع إلغاء الـ approvals القديمة عند كل push جديد بخيار Dismiss stale approvals، ومنع الـ merge ما دام هناك طلب تعديلات قائم.

ما الفرق بين protected branch و protected tag؟

الـ protected branch يقيّد الـ push والـ force push والـ merge على branches تطابق نمطًا، ويضيف شروط review وفحوص آلية قبل الدمج. أمّا الـ protected tag فيقيّد من يستطيع إنشاء tags تطابق نمطًا أو تعديلها أو حذفها، ويُستعمل عادةً لحماية tags الإصدارات. القاعدتان مستقلتان وتُضبطان من صفحتين مختلفتين.

ماذا بعد؟

هذه الصفحة مبنية على وثائق Gitea (رخصة MIT) بعد ترجمتها وتبسيطها.