Match (Fastlane): ما هو، إدارة الشهادات والإعداد في التطوير

ما هو Match (Fastlane)؟

Match (Fastlane) هو مكون من نظام Fastlane البيئي مصمم للإدارة المركزية لشهادات Code Signing وملفات Provisioning Profiles لتطوير iOS. إنه يحل مشكلة مزامنة التوقيعات بين أعضاء الفريق ويؤتمت إعداد الشهادات في خطوط أنابيب CI/CD دون تدخل المطور.

بدون Match، يقوم كل عضو في الفريق يدويًا بإنشاء الشهادات عبر Xcode أو Apple Developer Portal، مما يؤدي إلى تعارضات في البناء على أجهزة مختلفة. Code Signing هي عملية التوقيع الرقمي لتطبيق iOS، والتي تؤكد تأليفه وسلامته قبل التثبيت على جهاز المستخدم.

وفقًا لـ توثيق مطوري Apple (2025)، يعد التكوين غير الصحيح للشهادات أحد أكثر أسباب الرفض شيوعًا عند إرسال تطبيق إلى App Store. يتحقق Match تلقائيًا من صلاحية الشهادات ويحذر من الشهادات المنتهية الصلاحية، مما يقلل من خطر رفض البناء خلال مرحلة التحقق من Apple.

استخدم Match في أي مشروع يضم مطورين أو أكثر أو عند وجود خط أنابيب CI/CD — فهو يقلل وقت إعداد بيئة عضو الفريق الجديد من 30 دقيقة إلى أمر واحد في الطرفية.

كيف يعمل Match: مستودع Git مشفر

بنية Match مبنية على مفهوم مصدر واحد للحقيقة لجميع شهادات فريق iOS. بدلاً من التخزين المحلي في سلسلة المفاتيح لكل مطور، يقوم Match بتجميع الشهادات في مستودع Git واحد مع تشفير كل ملف قبل التخزين.

تتكون العملية من ثلاث مراحل. في مرحلة التهيئة، يقوم Match بإنشاء جميع الشهادات والملفات الشخصية اللازمة عبر واجهة برمجة تطبيقات Apple Developer Portal. يتم تشفير كل ملف باستخدام خوارزمية AES-256 بمفتاح يتكون من عبارة مرور يحددها المستخدم. يتم حفظ الملفات المشفرة في مستودع Git ومزامنتها مع الخادم البعيد عبر عمليات Git push و pull القياسية.

بنية تشفير الشهادات

يستخدم Match مزيجًا من OpenSSL وعبارة مرور يحددها المستخدم لتشفير الشهادات والملفات الشخصية. يتم تعيين مفتاح الوصول عبر متغير البيئة MATCH_PASSWORD ولا يتم تخزينه في المستودع، مما يمنع التسرب حتى في حالة اختراق خادم Git أو الوصول العام إلى المستودع.

عند طلب شهادة، يقوم Match بتنزيل الملف المشفر من المستودع، وفك تشفيره محليًا باستخدام عبارة المرور، وتثبيته في سلسلة مفاتيح الجهاز الحالي. بعد اكتمال البناء، يمكن إزالة الشهادات من سلسلة المفاتيح للامتثال لسياسات الأمان في بيئات الشركات — وهذا يمنع استخدام الشهادات القديمة في عمليات البناء اللاحقة.

يتم حفظ كل شهادة باسم يحتوي على معرف التطبيق ونوع الملف الشخصي وتاريخ الإنشاء. يسمح هذا الهيكل لـ Match بإدارة إصدارات الشهادات، وإذا لزم الأمر، التراجع عن التغييرات إلى حالة سابقة باستخدام أوامر Git revert و reset القياسية. هذا مفيد بشكل خاص عند حذف ملف شخصي أو استبداله عن طريق الخطأ.

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

يتم تثبيت Match مع Fastlane عبر مدير حزم Ruby: gem install fastlane. بعد التثبيت، قم بتهيئة مخزن الشهادات باستخدام الأمر fastlane match init، الذي ينشئ مستودع Git فارغًا وينشئ ملف Matchfile مع قالب إعداد أساسي.

# تهيئة مستودع Match
fastlane match init

التكوين عبر Matchfile

يحتوي ملف Matchfile على جميع معلمات الاتصال بمخزن الشهادات: عنوان مستودع Git، ونوع الملف الشخصي الافتراضي، ومعرفات التطبيق، وبيانات اعتماد Apple Developer. مثال على تكوين نموذجي لفريق من خمسة مطورين:

# تكوين Matchfile
git_url("https://github.com/company/certificates.git")
type(:development)
app_identifier(["com.company.app", "com.company.app.extension"])
username("developer@company.com")
team_id("TEAM123456")
git_branch("main")

تحدد المعلمة type نوع الملف الشخصي: :development لتصحيح الأخطاء على أجهزة المطورين، و:appstore للنشر في App Store، و:adhoc للاختبار على الأجهزة الخارجية، و:enterprise للتوزيع الداخلي للشركات (In-House) خارج App Store. ينشئ كل نوع دليلاً منفصلاً في المستودع، مما يسمح بتنظيم الملفات الشخصية حسب سيناريوهات البناء المستهدفة.

يدعم Match عدة طرق للمصادقة على Apple Developer Portal: المصادقة الثنائية عبر Apple ID، وكلمة مرور خاصة بالتطبيق (App-Specific Password)، ومفاتيح واجهة برمجة تطبيقات App Store Connect. بالنسبة لـ CI/CD، يُنصح باستخدام مفاتيح API — فهي لا تتطلب إدخال رمز تأكيد تفاعلي ولا تمنع عمليات البناء الآلية عند تغيير جهاز المطور.

إنشاء الملفات الشخصية ومزامنتها

بعد تكوين Matchfile، قم بتشغيل الأمر fastlane match development أو fastlane match appstore لإنشاء الملفات الشخصية ومزامنتها. يقوم Match تلقائيًا بإنشاء أو تحديث الشهادات عبر واجهة برمجة تطبيقات Apple Developer Portal وحفظها في المستودع. Apple Developer Portal هي واجهة الويب من Apple لإدارة الشهادات ومعرفات التطبيقات وقوائم أجهزة المطورين المعتمدة.

عند التشغيل الأول، سيطلب Match عبارة مرور لتشفير المستودع. يجب تخزين هذه العبارة في مدير أسرار CI/CD (GitHub Actions Secrets أو GitLab CI Variables أو Jenkins Credentials) وتمريرها عبر متغير البيئة MATCH_PASSWORD. بدونها، لن يتمكن Match من فك تشفير الشهادات على الأجهزة الأخرى أو في بيئة CI.

أوامر Match الأساسية لإدارة الشهادات

واجهة Match تتكون من مجموعة أوامر لإنشاء الشهادات والملفات الشخصية وتحديثها ومزامنتها وحذفها. يتوافق كل أمر مع إجراء محدد في دورة حياة Code Signing: من الإنشاء إلى التنظيف الكامل للمستودع.

أوامر العمل اليومي

الأمر fastlane match development يقوم بتنزيل أو إنشاء شهادات وملفات شخصية للتطوير لتصحيح الأخطاء على الأجهزة المحلية. Provisioning Profile هو مستند رقمي من Apple يربط شهادة المطور بمعرف التطبيق وقائمة الأجهزة المصرح لها بالتثبيت.

للنشر في App Store، استخدم fastlane match appstore — فهو ينشئ شهادات توزيع وملفات شخصية لـ AppStore. الأمر fastlane match adhoc ينشئ ملفات شخصية للاختبار على الأجهزة الخارجية، وfastlane match enterprise للتطبيقات الداخلية للشركات (In-House).

# إنشاء ملفات شخصية Development لتصحيح الأخطاء
fastlane match development

# إنشاء ملفات شخصية AppStore للإصدار
fastlane match appstore

# استيراد الشهادات الموجودة المنشأة يدويًا
fastlane match import

الأمر fastlane match import يسمح بإضافة شهادات موجودة إلى المستودع — مفيد عند الترحيل من الإدارة اليدوية إلى Match. المعلمة --readonly تمنع أي تغييرات في المستودع، وهو أمر بالغ الأهمية لبيئات CI حيث لا يجب أن يقوم خط الأنابيب بإنشاء أو حذف الشهادات والملفات الشخصية تلقائيًا.

للتنظيف الكامل للمستودع، استخدم الأمر fastlane match nuke. يقوم بإزالة جميع الشهادات من تخزين Git ومن Apple Developer Portal ومن الجهاز المحلي — إعادة تعيين كاملة لحالة Code Signing للمشروع. يستخدم الأمر فقط في حالات النزاعات الحرجة أو عند الترحيل إلى حساب Apple Developer جديد.

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

دمج CI/CD لـ Match هو إحدى المزايا الرئيسية للأداة. في خطوط أنابيب GitHub Actions وGitLab CI وBitrise أو Jenkins، يقوم Match تلقائيًا بتنزيل وتثبيت الشهادات الصحيحة دون تدخل المطور. وهذا يتيح بناء وتوقيع تطبيقات iOS مؤتمت بالكامل من الالتزام (commit) إلى ملف IPA جاهز.

يتضمن تكوين GitHub Actions النموذجي تثبيت Fastlane وإعداد متغير MATCH_PASSWORD وتشغيل Match مع العلم --readonly. GitHub Actions هي منصة CI/CD من GitHub التي تؤتمت بناء واختبار ونشر الكود بناءً على أحداث المستودع.

# تثبيت Fastlane في بيئة CI
gem install fastlane --no-document

# تشغيل Match في وضع القراءة فقط بدون حقوق تعديل
fastlane match development --readonly

قبل تشغيل Match في CI، قم بتكوين الوصول إلى مستودع الشهادات. يقوم Fastlane باستنساخه تلقائيًا بناءً على المعلمة git_url من Matchfile. يتم تكوين الوصول إلى المستودع عبر مفتاح SSH أو رمز وصول شخصي، يتم إضافتهما إلى أسرار نظام CI — وهذا يضمن عدم تعرض الشهادات للاختراق عبر الوصول العام.

قم بتعيين متغيرات البيئة MATCH_PASSWORD وFASTLANE_APPLE_API_KEY في أسرار مزود CI الخاص بك. يسمح مفتاح واجهة برمجة تطبيقات App Store Connect لـ Match بالمصادقة على Apple Developer Portal بدون مصادقة ثنائية، مما يلغي الطلبات التفاعلية في عمليات البناء الآلية ويمنع حظر خط الأنابيب.

الأخطاء الشائعة عند العمل مع Match

حتى مع التكوين الصحيح لـ Match، قد تحدث أخطاء تتعلق بانتهاء صلاحية الشهادات أو تعارض الملفات الشخصية أو تكوين بيئة غير صحيح. تشخيص مشكلات Match يعتمد على تحليل سجلات الأوامر والتحقق من حالة مستودع Git لملاءمة الشهادات.

الخطأ الأكثر شيوعًا — «You need to provide a password for Match» — يحدث عندما لا يتم تعيين متغير البيئة MATCH_PASSWORD على الجهاز أو في بيئة CI. الحل: أضف MATCH_PASSWORD إلى متغيرات بيئة النظام أو مرر كلمة المرور عبر المعلمة --keychain_password عند تشغيل أمر Match.

المشكلة الثانية الأكثر شيوعًا هي تعارض الشهادات عند إضافة جهاز جديد إلى ملف شخصي AdHoc. يتم حلها باستخدام الأمر fastlane match adhoc --force، الذي يعيد إنشاء الملفات الشخصية مع مراعاة الأجهزة الجديدة. شهادات Apple Developer صالحة لمدة عام واحد، وبعد ذلك يتم رفض عمليات البناء التي تستخدمها من قبل App Store Connect. يحذر Match من انتهاء الصلاحية قبل 30 يومًا من نهاية فترة الصلاحية.

عند ظهور الخطأ «Multiple matches found for...»، توجد إصدارات متعددة من نفس الشهادة في المستودع. استخدم الأمر fastlane match nuke لتنظيف المستودع بالكامل وإزالة جميع الشهادات من Apple Developer Portal. بعد التنظيف، قم بإنشاء جديد من الصفر — وهذا يضمن حالة متسقة للملفات الشخصية بدون تكرار أو إصدارات متعارضة.