تتيح نشر المعاينات لكل طلب سحب عنوان URL مباشرًا خاصًا به، مبنيًا من كود ذلك الفرع، بحيث يمكن للمراجعين تصفح التغيير الفعلي بدلاً من قراءة فرق (diff) ومحاولة التخمين. يتم تحديث كل معاينة عند دفع التزام (commit) جديد، ويتم تنظيفها تلقائيًا عند إغلاق طلب السحب.
أين توجد نشر المعاينات
افتح المواقع، وانقر على الموقع، ثم افتح مجموعة Environment في القائمة اليسرى للموقع، واختر معاينة. عنوان الصفحة هو نشر المعاينات.
المعاينات منفصلة عن بيئة التجهيز (Staging). بيئة التجهيز هي نسخة واحدة طويلة الأمد من الموقع تقوم بالدفع إليها عمدًا، بينما المعاينة هي بيئة قصيرة الأمد يتم إنشاؤها لكل طلب سحب ثم التخلص منها بعد ذلك. تستخدم فرق كثيرة كلا الأمرين. راجع بيئات التجهيز للاطلاع على النصف الآخر.
قم بإعداد نشر Git أولاً
المعاينات ليست ميزة قائمة بذاتها. فهي تعيد استخدام مفتاح النشر وأمر البناء الخاصين بالموقع الإنتاجي، لذا يحتاج الموقع إلى تهيئة عاملة لنشر Git قبل أن يتسنى تفعيل المعاينات.
إذا لم يكن نشر Git مهيأً، تعرض الصفحة عبارة قم بإعداد نشر Git أولاً وتقدم زر الذهاب إلى نشر Git بدلاً من نموذج التفعيل. اتبع خطوات نشر موقع من Git، ثم عُد إلى هنا.
إذا كان نشر Git متصلاً ولكن لا يحتوي على أمر بناء، تعرض صفحة المعاينة تحذيرًا. ستفترض المعاينات أن المستودع تم بناؤه بالفعل، مع وجود الملفات الثابتة في الجذر. هذا صحيح بالنسبة لموقع HTML بسيط وخاطئ بالنسبة لأي شيء يحتاج إلى تجميع (compile)، لذا اضبط أمر بناء في صفحة نشر Git إذا كان مشروعك بحاجة إلى ذلك.
تفعيل المعاينات
- في بطاقة تفعيل نشر المعاينات، اكتب المستودع بصيغة
owner/repo. ليس عنوان URL، وليس عنوان SSH: مجرد الجزأين، على سبيل المثالacme/marketing-site. - انقر على Enable.
أي شيء لا يطابق owner/name يُرفض مع ظهور عبارة يجب أن يكون المستودع بصيغة owner/name.
فور التفعيل، يعرض KPanel سر توقيع الويبهوك في بطاقة بعنوان انسخ سر الويبهوك الخاص بك الآن، مع تحذير بأنك لن تراه مرة أخرى.
انسخ السر قبل مغادرة الصفحة. يتم إنشاؤه مرة واحدة ولا يمكن استرجاعه بعد ذلك. إذا فقدته، فالحل هو إعادة إنشائه، وهو ما يُبطل السر القديم ويعني أنك ستحتاج إلى تحديث ويبهوك مستودعك على أي حال.
إضافة الويبهوك إلى مستودعك
تعرض البطاقة المهيأة عنوان Webhook للصقه في إعدادات مستودعك، تحت قسم Webhooks. قم بتهيئته كالتالي:
- عنوان URL للحمولة: عنوان الويبهوك الموضح في الصفحة.
- السر: القيمة التي نسختها للتو.
- نوع المحتوى: JSON.
- الأحداث: أحداث طلب السحب، بالإضافة إلى عمليات الدفع (pushes)، حتى يتم إعادة بناء المعاينة عند وجود التزامات جديدة على طلب سحب مفتوح.
بمجرد تهيئة ذلك، يؤدي فتح طلب سحب إلى بناء معاينة خلال دقائق قليلة. تتحقق مهمة في الخلفية من وجود عمل معاينة جديد كل دقيقة، لذا لا حاجة للضغط على أي شيء في KPanel.
عناوين URL للمعاينة
تحصل كل معاينة على اسم مضيف خاص بها بالصيغة pr-<pull-request-number>-<site-id>.kapsulecloud.app، مغطى بشهادة واسعة النطاق (wildcard) بحيث يتم تقديمها عبر HTTPS دون أي خطوة إضافية لإصدار شهادة من جانبك.
الطريقة الموثوقة لفتح إحداها هي زر Open في صف المعاينة ضمن آخر المعاينات، والذي يحمل عنوان URL الدقيق الذي تم تخصيصه لذلك البناء. الصق هذا الرابط في طلب السحب حتى لا يضطر المراجعون للبحث عن KPanel على الإطلاق.
قراءة قائمة آخر المعاينات
يعرض قسم آخر المعاينات أحدث المعاينات، الأحدث أولاً. يُظهر كل صف رقم طلب السحب وعنوانه، والفرع، والالتزام (commit)، وحالة:
| الحالة | المعنى |
|---|---|
| BUILDING | يتم الاستنساخ والبناء الآن |
| LIVE | يُخدَّم على عنوان المعاينة الخاص به |
| FAILED | حدث خطأ في البناء، وسّع السجل لمعرفة السبب |
| DESTROYED | تم التنظيف، عادةً لأن طلب السحب أُغلق |
انقر على تبديل سجل البناء في أحد الصفوف لتوسيع مخرجات البناء ضمن الصف. هذا السجل هو أول مكان يجب النظر فيه عند فشل المعاينة، وهو نفس المخرج الذي سينتجه بناؤك محليًا.
إذا كانت القائمة فارغة، تذكر الصفحة ذلك: افتح طلب سحب على المستودع وسيتم بناء معاينة خلال دقائق.
تدوير سر الويبهوك
انقر على إعادة إنشاء السر في البطاقة المهيأة. يطلب منك KPanel التأكيد، ويوضح صراحةً أن السر الحالي يتوقف عن العمل فورًا وأنك ستحتاج إلى تحديثه في إعدادات ويبهوك مستودعك بعد ذلك.
يُعرض السر الجديد مرة واحدة، في نفس البطاقة ذات الاستخدام الواحد كما في السابق. انسخه، ثم حدّث الويبهوك في مستودعك. بين هاتين اللحظتين، تُرفض رسائل الويبهوك الواردة، لذا نفّذ الخطوتين تباعًا دون تأخير.
أعد إنشاء السر عندما يغادر شخص لديه صلاحية مسؤول على المستودع، أو إذا تم لصق السر في مكان لا ينبغي له، مثل قناة دردشة مشتركة أو تذكرة دعم.
إيقاف المعاينات
انقر على Disable. يتم إيقاف التهيئة ومسح السر المخزن. تتوقف المعاينات الحالية عن إعادة البناء.
رتّب الأمور أيضًا بحذف الويبهوك في مستودعك. سيبدأ في الفشل بدلاً من إحداث أي ضرر، لكن ويبهوك يُعيد أخطاءً إلى الأبد يُعد ضوضاء في سجل التسليم الخاص بمستودعك.
التكاليف والصيانة الدورية
تقوم المعاينات ببناء وتقديم كود حقيقي، لذا فهي تستخدم نفس موارد أي نشر آخر على الموقع. هناك عادتان تبقيان ذلك تحت السيطرة:
- أغلق طلبات السحب التي لم تعد تعمل عليها. يتم تنظيف معاينة طلب السحب المُغلق تلقائيًا.
- لا توجّه المعاينات إلى بيانات اعتماد الإنتاج. امنحها مفاتيح اختبار عبر بيئة preview في تبويب الأسرار، والتي توجد تحديدًا لكي لا يُختلط إعداد المعاينة بإعداد الإنتاج.
عنوان URL للمعاينة ليس خاصًا. إنه اسم مضيف حقيقي يمكن الوصول إليه علنًا، مزود بشهادة صالحة، ويمكن لأي شخص لديه الرابط فتحه. لا تستخدم المعاينة لمراجعة أي شيء يحتوي على بيانات عملاء حقيقية، ولا تُنشئ بيئات المعاينة من نسخة قاعدة بيانات إنتاجية.
استكشاف الأخطاء وإصلاحها
لا يتم بناء أي شيء عند فتح طلب سحب. تحقق من عمليات التسليم الأخيرة للويبهوك في مستودعك. يعني رمز 401 أو 403 أن السر غير متطابق، لذا أعد إنشاءه وحدّث كلا الطرفين. عدم وجود أي تسليم على الإطلاق يعني أن الويبهوك غير مشترك في أحداث طلب السحب.
تُبنى المعاينة ولكنها تعرض قائمة مجلد أو خطأ 404. مجلد الإخراج في صفحة نشر Git لا يتطابق مع المكان الذي يكتب فيه بناؤك فعليًا. ترث المعاينات هذا الإعداد من الإنتاج.
يفشل البناء فقط في المعاينة. السبب الأكثر شيوعًا هو اعتمادية (dependency) أو متغير بيئة موجود في الإنتاج ولكن لم تتم إضافته إلى بيئة المعاينة. تحقق من تبويب preview في صفحة الأسرار.
يتوقف عنوان URL للمعاينة عن العمل. انظر إلى الحالة في صفه. تعني DESTROYED أن طلب السحب أُغلق وأُعيدت البيئة، وهو السلوك المقصود.
إلى أين تذهب بعد ذلك
- نشر موقع من Git، وهو الإعداد المسبق المطلوب.
- تخزين أسرار التطبيق لموقع للحصول على بيانات اعتماد لكل بيئة.
- بيئات التجهيز للحصول على نسخة دائمة قبل الإنتاج.