Pilot (Fastlane): المفاهيم الأساسية وTestFlight وإدارة الإصدارات للمشاريع المحمولة

ما هو Pilot (Fastlane)؟

Pilot (Fastlane) هو مكون من نظام Fastlane لأتمتة العمل مع TestFlight — منصة Apple للاختبار التجريبي للتطبيقات المحمولة. يتولى Pilot جميع العمليات الروتينية: رفع الإصدارات وإضافة المختبرين وإدارة المجموعات وتتبع حالة الإصدارات.

بدون Pilot، تبدو عملية التوزيع التجريبي كالتالي: يفتح المطور App Store Connect يدويًا، ويختار التطبيق، ويرفع IPA عبر Xcode Organizer، ويكوّن مجموعة مختبرين، ويرسل الدعوات. TestFlight هي خدمة Apple لتوزيع الإصدارات التجريبية من التطبيقات للمختبرين قبل الإصدار الرسمي في App Store.

وفقًا لمساعدة App Store Connect (2025)، يجب على المختبرين الخارجيين اجتياز عملية Beta App Review قبل أول تثبيت للإصدار — يستغرق ذلك من 1 إلى 48 ساعة. يتتبع Pilot حالة المراجعة تلقائيًا ويُبلغ الفريق عندما يكون الإصدار جاهزًا للتوزيع على مجموعات المختبرين الخارجيين.

استخدم Pilot في أي مشروع يتطلب تسليمًا منتظمًا للإصدارات التجريبية للمختبرين — إنها أداة قياسية لخطوط أنابيب CI/CD لتطبيقات iOS، تضمن عملية تسليم يمكن التنبؤ بها.

الوظائف الرئيسية لـ Pilot مع TestFlight

وظائف Pilot تغطي دورة الحياة الكاملة لإدارة الإصدارات التجريبية: من رفع ملف ثنائي إلى إخطار المختبرين بإصدار جديد. كل وظيفة منفذة كأمر منفصل بسلوك يمكن التنبؤ به وتسجيل مفصل لكل خطوة.

رفع الإصدارات إلى TestFlight

يقوم الأمر fastlane pilot upload برفع ملف IPA إلى App Store Connect وإنشاء إصدار جديد في TestFlight. يتحقق Pilot تلقائيًا من صحة الملف الثنائي وتوافق الإصدار ومعرف التطبيق. App Store Connect هي منصة Apple لإدارة التطبيقات، بما في ذلك رفع الإصدارات والبيانات الوصفية والتحليلات وتقارير المبيعات.

بعد الرفع، ينتظر Pilot معالجة Apple للملف الثنائي — تستغرق العملية من 5 إلى 30 دقيقة حسب حجم الإصدار. أثناء الانتظار، يعرض Pilot شريط تقدم بمعلومات عن حالة المعالجة الحالية: Processing أو Validating أو Ready. بعد المعالجة الناجحة، يصبح الإصدار متاحًا للتعيين لمجموعات المختبرين.

إدارة مجموعات المختبرين

يدعم Pilot إدارة كل من مجموعات المختبرين الداخليين والخارجيين. المختبرون الداخليون هم أعضاء فريق Apple Developer الخاص بك الذين يحصلون على وصول فوري إلى الإصدارات دون الحاجة لاجتياز Beta App Review. المختبرون الخارجيون هم مستخدمون مدعوون عبر البريد الإلكتروني، ويحتاجون إلى موافقة المراجعة قبل التثبيت الأول.

يضيف الأمر fastlane pilot add مختبرين جددًا إلى مجموعة عبر البريد الإلكتروني أو Apple ID. يرسل Pilot الدعوات تلقائيًا ويتحقق مما إذا كان المختبر قد قبل الدعوة. للإضافة الجماعية، يمكنك تمرير قائمة رسائل بريد إلكتروني من ملف باستخدام المعامل --testers_file_path، وهو أمر مناسب عند التكوين الأولي لمجموعة مختبرين من مئات المشاركين.

# رفع إصدار جديد إلى TestFlight
fastlane pilot upload --ipa "build/MyApp.ipa"

# إضافة مختبر إلى مجموعة
fastlane pilot add --email "tester@company.com" \
      --groups "QA Team"

إعداد وتكوين Pilot

تكوين Pilot لا يتطلب ملف تكوين منفصل — يتم تمرير الإعدادات عبر Appfile (ملف Fastlane المشترك) أو وسائط سطر الأوامر. تشمل المعاملات الرئيسية apple_id للتطبيق وapp_identifier وteam_id وبيانات الاعتماد للوصول إلى App Store Connect API.

للمصادقة، يستخدم Pilot مفتاح App Store Connect API (الطريقة الموصى بها) أو المصادقة الثنائية لـ Apple ID. مفتاح App Store Connect API هو مفتاح وصول يتم إنشاؤه في App Store Connect ويتيح التفاعل مع API دون إدخال كلمة مرور ورمز تأكيد بشكل تفاعلي.

# Appfile — التكوين العام لـ Fastlane
app_identifier("com.company.app")
apple_id("developer@company.com")
team_id("TEAM123456")

# متغيرات البيئة لـ Pilot
# APP_STORE_CONNECT_API_KEY_PATH=/path/to/key.p8

يحدد المعامل app_identifier معرف الحزمة (Bundle Identifier) للتطبيق، والذي يجب أن يتطابق مع المعرف المحدد في مشروع Xcode وApp Store Connect. يُستخدم المعامل apple_id للمصادقة في نظام العاملين، و team_id — لاختيار فريق التطوير إذا كان الحساب مرتبطًا بعدة فرق Apple Developer.

لكي يعمل Pilot، تحتاج إلى تكوين مفتاح App Store Connect API في بيئة CI/CD. يتم إنشاء المفتاح في App Store Connect ← Users and Access ← Keys ← Generate API Key. احفظ ملف .p8 في أسرار نظام CI وحدد المسار إليه عبر متغير البيئة APP_STORE_CONNECT_API_KEY_PATH أو المعامل --api_key_path في أوامر Pilot.

أوامر Pilot لإدارة الإصدارات

مجموعة أوامر Pilot تغطي جميع سيناريوهات TestFlight: رفع الإصدارات وإدارة المختبرين وعرض الحالات وتتبع البيانات الوصفية. كل أمر يُرجع مخرجات JSON منظمة لمزيد من المعالجة في سكريبتات CI/CD.

عرض حالات الإصدارات

يعرض الأمر fastlane pilot builds قائمة بجميع إصدارات التطبيق مع الإصدار وحالة المعالجة وتاريخ الرفع. حالة الإصدار يمكن أن تكون واحدة من: Processing — Apple تعالج الملف الثنائي، Ready — الإصدار متاح للتوزيع، Rejected — تم رفض الإصدار بسبب أخطاء التحقق.

# عرض قائمة جميع الإصدارات في TestFlight
fastlane pilot builds

# تعيين إصدار لمجموعة مختبرين
fastlane pilot distribute --build_number 42 \
      --groups "QA Team" --notify

# عرض معلومات عن إصدار محدد
fastlane pilot build_info --build_number 42

يقوم الأمر fastlane pilot distribute بتعيين الإصدار لمجموعات مختبرين محددة وإرسال الإشعارات. المعامل --notify يُفعّل إرسال إشعارات البريد الإلكتروني للمختبرين عن إصدار جديد متاح — وهذا أمر بالغ الأهمية لإشراك المختبرين التجريبيين في عملية الاختبار وتسريع التغذية الراجعة.

لإدارة البيانات الوصفية للإصدار، يُستخدم المعامل --changelog، الذي يحدد نص وصف التغييرات في الإصدار الجديد. يُعرض هذا النص للمختبرين في دعوة الاختبار في تطبيق TestFlight. يُوصى بتحديد التغييرات الرئيسية والأخطاء المُصلحة والميزات الجديدة في كل إصدار.

دمج Pilot في خط أنابيب CI/CD

Pilot في CI/CD هو المرحلة النهائية من خط أنابيب تسليم تطبيقات iOS. بعد أن يقوم Gym ببناء IPA واجتياز الاختبارات، يقوم Pilot برفع الإصدار إلى TestFlight وتوزيعه على مجموعات المختبرين. يتيح ذلك لفرق ضمان الجودة الحصول على إصدار التطبيق الجديد في غضون دقائق بعد الالتزام في المستودع.

يتضمن خط أنابيب CI/CD النموذجي لتطبيقات iOS التسلسل: Match (الشهادات) وGym (بناء IPA) وPilot (الرفع إلى TestFlight والتوزيع). كل مرحلة تعتمد على السابقة، مما يضمن تسليم الإصدارات الصالحة والموقعة فقط للمختبرين.

# خط أنابيب كامل في Fastfile
lane :beta do
    match(type: :appstore)
    gym(scheme: "MyApp", export_method: "app-store")
    pilot("build/MyApp.ipa", groups: ["QA", "PM"])
end

المعامل skip_waiting في أمر upload يسمح بعدم انتظار اكتمال معالجة Apple للملف الثنائي ضمن مهمة CI — يرسل Pilot طلب الرفع ويستلم معرف الإصدار وينهي عمله. هذا يُسرّع خط الأنابيب حيث أن المعالجة قد تستغرق حتى 30 دقيقة لا تُهدر في الانتظار في مشغل CI.

لكي يعمل Pilot بشكل صحيح في CI، تحتاج إلى تكوين مفتاح App Store Connect API. احفظ ملف المفتاح .p8 في التخزين الآمن لنظام CI ومرر المسار عبر متغير البيئة APP_STORE_CONNECT_API_KEY_PATH. يستخدم Pilot هذا المفتاح للمصادقة في API دون مصادقة ثنائية، وهو أمر بالغ الأهمية للسيناريوهات الآلية.

المشاكل الشائعة عند العمل مع Pilot

عند استخدام Pilot، يواجه المطورون في أغلب الأحيان أخطاء المصادقة وتكوين التطبيق غير الصحيح ومشاكل في معالجة الملفات الثنائية من جانب Apple. تشخيص مشاكل Pilot يبدأ بالتحقق من حالة الإصدار في App Store Connect عبر أمر pilot builds.

الخطأ “Your app is not available for testing in TestFlight” يحدث عندما لا يكون التطبيق مهيأً للاختبار في App Store Connect. الحل: افتح قسم TestFlight في App Store Connect وفعّل الاختبار للتطبيق وتأكد من أن Export Compliance مكتمل بشكل صحيح لنوع التشفير الخاص بك.

الخطأ “Missing iOS Distribution signing identity” يشير إلى عدم وجود شهادة Distribution في Keychain. الحل: قم بتشغيل Match لتنزيل الشهادة الصحيحة قبل استدعاء Pilot. شهادة Distribution تختلف عن شهادة Development — تُستخدم لتوقيع الإصدارات المخصصة للتوزيع عبر TestFlight أو App Store.

مع خطأ “Invalid Provisioning Profile”، يحتوي الإصدار على ملف تعريف غير صحيح لطريقة التصدير المحددة. الحل: تحقق من أن Gym يستخدم export_method الصحيح الذي يطابق نوع الملف التعريفي في Match. إذا تم بناء الإصدار مع ملف تعريف development، لن يتمكن Pilot من رفعه إلى TestFlight — مطلوب ملف تعريف app-store أو ad-hoc.