تخطَّ إلى المحتوى
Docs Control

إنفاذ الإعدادات

سير عمل الإنفاذ في .github/workflows/enforce-repo-settings.yml هو سير عمل قابل لإعادة الاستخدام وخالي من التكرار يقارن الحالة المطلوبة للمستودع بالحالة الحالية ويصلح أي انحراف. تستدعيه المستودعات التابعة عبر سير عمل مستدعٍ. كما يشغله docs-control مباشرة عند الدفع إلى .github/config/repo-settings.json.

المشغلات

Section titled “المشغلات”
  • workflow_call — يُستدعى بواسطة مسارات العمل المستدعية التابعة (مجدول كل 6 ساعات، أو عند دفع التكوين، أو التوزيع اليدوي)
  • push — يعمل عند تغيير repo-settings.json على الفرع main في docs-control

التنفيذ الموازي

Section titled “التنفيذ الموازي”

ينقسم الإنفاذ إلى مساري عمل قابلين لإعادة الاستخدام يعملان كمهام موازية في المستدعي، كل منهما برمز الحد الأدنى من الصلاحيات الخاص به:

  • enforce-repo-settings.yml يستخدم REPO_SETTINGS_TOKEN (قراءة/كتابة الإدارة، قراءة/كتابة الصفحات، قراءة المحتويات، قراءة البيانات الوصفية)
  • sync-managed-files.yml يستخدم REPO_SYNC_TOKEN (قراءة/كتابة المحتويات، قراءة/كتابة المشكلات، قراءة/كتابة طلبات السحب، قراءة البيانات الوصفية)

تغطي هذه الصفحة سير عمل إنفاذ الإعدادات. راجع مزامنة الملفات لتعلم سير عمل الملفات المدارة.

المراحل السبع

Section titled “المراحل السبع”

كل مرحلة خالية من التكرار: تقارن الحالة المطلوبة بالحالة الحالية وتجري تغييرات فقط عند اكتشاف انحراف.

المرحلة 1: التحقق من الصحة

Section titled “المرحلة 1: التحقق من الصحة”

يجلب التكوين المركزي من docs-control عبر GitHub API (مع 5 محاولات إعادة). يتحقق من توفر jq و gh ومصادقتهما. يحسب رابط homepage تلقائياً إذا كانت قيمة التكوين فارغة.

يكتشف ما إذا كان سير العمل يعمل على المستودع المصدر نفسه بمقارنة managed_files.source_repo بـ github.repository. إذا كان يعمل على نفسه، يتم تفعيل تجاوز self_contexts للمرحلة 4.

المرحلة 2: تطبيق إعدادات المستودع

Section titled “المرحلة 2: تطبيق إعدادات المستودع”

يقارن كل مفتاح في كائن repository بالإعدادات الحالية للمستودع عبر GET /repos/{owner}/{repo}. يبني كائن إصلاح يحتوي فقط على المفاتيح التي انحرفت ويطبقه عبر PATCH /repos/{owner}/{repo}.

المرحلة 3: تطبيق صلاحيات Actions

Section titled “المرحلة 3: تطبيق صلاحيات Actions”

يقارن كائن actions_permissions (صلاحيات سير العمل الافتراضية، الموافقة على مراجعة طلب السحب) بصلاحيات سير عمل Actions الحالية عبر GET /repos/{owner}/{repo}/actions/permissions/workflow. يجدد عبر PUT إذا انحرف أي مفتاح.

المرحلة 4: تطبيق حماية الفروع

Section titled “المرحلة 4: تطبيق حماية الفروع”

يتنقل عبر مصفوفة branch_protection. لكل فرع:

  1. إذا كان يعمل على نفسه، يستبدل self_contexts بـ contexts
  2. يجرد self_contexts من الحمولة (ليس جزءاً من GitHub API)
  3. يجلب الحماية الحالية عبر GET /repos/{owner}/{repo}/branches/{branch}/protection
  4. يقارن: enforce_admins و required_status_checks (صارم + سياقات) و required_pull_request_reviews و restrictions والأعلام المنطقية (required_linear_history و allow_force_pushes e allow_deletions و block_creations و required_conversation_resolution و lock_branch و allow_fork_syncing)
  5. ينشئ أو يحدد قواعد الحماية عبر PUT إذا تم اكتشاف أي انحراف

المرحلة 5: تطبيق المواضيع

Section titled “المرحلة 5: تطبيق المواضيع”

يقارن مصفوفة topics بالمواضيع الحالية للمستودع عبر GET /repos/{owner}/{repo}/topics. يستبدلها عبر PUT إذا انحرفت.

Fase 6: تطبيق Pages

Section titled “Fase 6: تطبيق Pages”

يتحقق مما إذا كانت GitHub Pages مُمكّنة عبر GET /repos/{owner}/{repo}/pages. إذا لم يتم العثور عليها (404)، يُمكّن Pages مع build_type المكون. إذا تم العثور عليها ولكن انحرف build_type، يحدّثه عبر PUT.

المرحلة 7: التحقق

Section titled “المرحلة 7: التحقق”

يعيد قراءة كافة الإعدادات عبر GitHub API ويقارنها بالحالة المطلوبة. يتحقق من إعدادات المستودع، وصلاحيات Actions، وحماية الفروع (بما في ذلك الأعلام المنطقية)، ونوع بناء Pages. يفشل سير العمل إذا لم تتطابق أي إعدادات بعد مراحل التطبيق.

التقدم لثوابت سير العمل غير Qابلة للتغيير

Section titled “التقدم لثوابت سير العمل غير Qابلة للتغيير”

عندما تتغير مسارات العمل القابلة لإعادة الاستخدام في docs-control، يتسبب .github/workflows/update-governed-workflow-pins.yml في تشغيل scripts/update-governed-workflow-pins.sh لتحديث قيم SHA المثبتة بالالتزام عبر مسارات العمل المستدعية بشكل حتمي ودون تدخل يدوي.