Pilot (Fastlane): مفاهیم کلیدی، TestFlight و مدیریت بیلدها برای پروژه‌های موبایل

Pilot (Fastlane) چیست؟

Pilot (Fastlane) — جزئی از اکوسیستم Fastlane برای خودکارسازی کار با TestFlight — پلتفرم اپل برای تست بتای برنامه‌های موبایل است. Pilot تمام عملیات روزمره را بر عهده می‌گیرد: آپلود بیلدها، افزودن تسترها، مدیریت گروه‌ها و پیگیری وضعیت بیلدها.

بدون Pilot فرآیند توزیع نسخه بتا به این صورت است: توسعه‌دهنده به صورت دستی App Store Connect را باز می‌کند، برنامه را انتخاب می‌کند، IPA را از طریق Xcode Organizer آپلود می‌کند، گروه تستر را تنظیم می‌کند و دعوت‌نامه‌ها را ارسال می‌کند. TestFlight — سرویس اپل برای توزیع نسخه‌های بتای برنامه‌ها در میان تسترها قبل از انتشار رسمی در App Store است.

طبق App Store Connect Help (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 — پلتفرم اپل برای مدیریت برنامه‌ها، شامل آپلود بیلدها، فراداده، تحلیل و گزارش‌های فروش است.

پس از آپلود، Pilot منتظر پردازش فایل باینری توسط اپل می‌ماند — فرآیند بسته به اندازه بیلد از 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 Key (روش توصیه‌شده) یا احراز هویت دو عاملی Apple ID استفاده می‌کند. App Store Connect API Key — کلید دسترسی است که در 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 برنامه را تعیین می‌کند که باید با شناسه مشخص‌شده در پروژه Xcode و App Store Connect مطابقت داشته باشد. پارامتر apple_id برای احراز هویت در طرح دو عاملی و team_id برای انتخاب تیم توسعه در صورتی که حساب به چندین تیم Apple Developer متصل باشد استفاده می‌شود.

برای کار Pilot باید App Store Connect API Key در محیط 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 — اپل در حال پردازش فایل باینری است، 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 آپلود کرده و بین گروه‌های تستر توزیع می‌کند. این به تیم‌های QA امکان می‌دهد نسخه جدید برنامه را چند دقیقه پس از commit در مخزن دریافت کنند.

یک خط لوله معمولی iOS CI/CD شامل دنباله زیر است: 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 امکان عدم انتظار برای تکمیل پردازش فایل باینری توسط اپل را در چارچوب وظیفه CI فراهم می‌کند — Pilot درخواست آپلود را ارسال می‌کند، شناسه بیلد را دریافت کرده و کار خود را پایان می‌دهد. این کار خط لوله را سرعت می‌بخشد زیرا پردازش ممکن است تا 30 دقیقه طول بکشد که صرف انتظار در runner CI نمی‌شود.

برای عملکرد صحیح Pilot در CI باید کلید API App Store Connect پیکربندی شود. فایل کلید .p8 را در ذخیره‌گاه امن سیستم CI ذخیره کرده و مسیر را از طریق متغیر محیطی APP_STORE_CONNECT_API_KEY_PATH منتقل کنید. Pilot از این کلید برای احراز هویت در API بدون احراز هویت دو عاملی استفاده می‌کند که برای سناریوهای خودکار حیاتی است.

مشکلات رایج هنگام کار با Pilot

هنگام استفاده از Pilot، توسعه‌دهندگان اغلب با خطاهای احراز هویت، پیکربندی نادرست برنامه و مشکلات پردازش فایل‌های باینری توسط اپل مواجه می‌شوند. تشخیص مشکلات 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 است. راه‌حل: قبل از فراخوانی Pilot، Match را برای بارگیری گواهی صحیح اجرا کنید. گواهی Distribution با Development متفاوت است — برای امضای بیلدهایی که از طریق TestFlight یا App Store توزیع می‌شوند استفاده می‌شود.

در خطای «Invalid Provisioning Profile» بیلد حاوی پروفایل نادرست برای روش خروج انتخابی است. راه‌حل: بررسی کنید که Gym از export_method صحیح مطابق با نوع پروفایل در Match استفاده می‌کند. اگر بیلد با پروفایل توسعه ساخته شده باشد، Pilot نمی‌تواند آن را در TestFlight آپلود کند — پروفایل app-store یا ad-hoc مورد نیاز است.