Gym (Fastlane): nó là gì, build IPA và tự động hóa trong phát triển ứng dụng

Gym (Fastlane) là gì?

Gym (Fastlane) là một thành phần của hệ sinh thái Fastlane, đảm bảo việc build ứng dụng iOS sang định dạng IPA thông qua một lệnh terminal duy nhất. Nó trừu tượng hóa quy trình phức tạp của xcodebuild với hàng chục flag và cung cấp cho nhà phát triển một giao diện đơn giản với các giá trị mặc định hợp lý.

Trong Xcode, để build IPA cần mở dự án, chọn scheme, cấu hình Archive và Export, chọn phương thức phân phối và chờ hoàn tất. Tự động hóa build qua Gym loại bỏ các bước thủ công và đảm bảo mỗi lần build được thực hiện với các tham số giống nhau — điều này rất quan trọng cho tính dự đoán của pipeline CI/CD.

Theo SwiftLee (2024), các nhóm sử dụng Gym để build dành ít hơn 40% thời gian cho việc cấu hình quy trình phát hành so với xuất thủ công qua Xcode Organizer. Gym cũng tạo log build chi tiết với từng bước xcodebuild, giúp dễ dàng gỡ lỗi các build thất bại và phân tích lỗi biên dịch.

Sử dụng Gym trong bất kỳ dự án iOS nào yêu cầu build IPA thường xuyên để kiểm thử hoặc phát hành — đây là cách duy nhất để đảm bảo cấu hình build giống nhau trên tất cả máy trong nhóm.

Cách Gym build IPA: quy trình và tham số

Quy trình build IPA qua Gym

Build IPA qua Gym bao gồm ba bước tuần tự: lưu trữ dự án qua xcodebuild, xuất kho lưu trữ thành gói nhị phân và đóng gói thành định dạng IPA có chữ ký. Gym tự động xác định loại dự án (single target hoặc workspace) và chọn phương thức build chính xác.

Ở bước lưu trữ, Gym chạy xcodebuild archive với các tham số scheme và cấu hình được chỉ định trong dự án. Sau khi tạo thành công archive .xcarchive, Gym chạy xcodebuild -exportArchive với phương thức xuất đã chọn. Xuất IPA là quá trình chuyển đổi archive .xcarchive thành tệp cài đặt .ipa bao gồm tất cả tài nguyên cần thiết và chữ ký.

Tham số xuất build

Phương thức xuất xác định loại Provisioning Profile sẽ được sử dụng để ký IPA. Gym hỗ trợ bốn phương thức: development để gỡ lỗi trên thiết bị nhà phát triển, app-store để phát hành trên App Store, ad-hoc để thử nghiệm beta trên số lượng thiết bị giới hạn và enterprise để phân phối nội bộ doanh nghiệp.

Các tham số bổ sung bao gồm chỉ định export_options_plist để tinh chỉnh xuất, loại bỏ Swift overlay để giảm kích thước IPA và quản lý bitcode. Gym cũng hỗ trợ build cho simulator qua flag --skip_package_ipa, hữu ích để kiểm tra nhanh mã mà không cần xuất đầy đủ.

# Xây dựng IPA cơ bản qua Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# Xây dựng với chỉ định phương pháp xuất
fastlane gym --export_method app-store

# Chỉ xây dựng archive không xuất IPA
fastlane gym --skip_package_ipa

Cấu hình Gym qua Gymfile

Gymfile là tệp cấu hình Fastlane lưu trữ tất cả tham số build trong định dạng Ruby có cấu trúc. Không giống như truyền flag qua dòng lệnh, Gymfile cho phép cố định cấu hình trong kho và đảm bảo tất cả nhà phát triển và CI sử dụng các tham số build giống hệt nhau.

# Gymfile — cấu hình xây dựng
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

Tham số export_method trong Gymfile tương ứng với các loại profile từ Apple Developer Portal. Đối với bản phát hành App Store, sử dụng :app-store, cho kiểm thử — :development hoặc :ad-hoc. Tham số configuration xác định cấu hình build: Release cho bản phát hành hoặc Debug cho bản gỡ lỗi.

Tham số include_bitcode kiểm soát việc bao gồm bitcode trong IPA. Apple yêu cầu bitcode cho ứng dụng watchOS và tvOS, nhưng đối với iOS, tham số này có thể tắt để giảm kích thước tệp nhị phân. include_symbols bao gồm các tệp ký hiệu gỡ lỗi .dSYM, cần thiết để biểu tượng hóa log crash từ App Store Connect hoặc các dịch vụ giám sát bên thứ ba.

Các tham số bổ sung của Gymfile bao gồm export_options_plist cho tệp plist xuất tùy chỉnh, silent để ẩn đầu ra dư thừa trong log và build_path để chỉ định thư mục tạm thời cho build. Các tham số này hữu ích khi tích hợp Gym vào các pipeline CI/CD phức tạp với yêu cầu đặc biệt về artifact.

Lệnh Gym để build ứng dụng

Giao diện lệnh Gym bao gồm các tham số cơ bản cho các kịch bản build điển hình và các flag nâng cao để tinh chỉnh hành vi. Hầu hết các tham số có thể được truyền qua dòng lệnh hoặc Gymfile, trong đó tham số dòng lệnh được ưu tiên hơn tệp cấu hình.

Lệnh fastlane gym không có tham số sẽ sử dụng cài đặt từ Gymfile hoặc tự động phát hiện dự án trong thư mục hiện tại. Đối với các dự án có nhiều target, cần chỉ định --scheme và --workspace để chọn đúng cấu hình build mục tiêu.

Lệnh build điển hình

Để build gỡ lỗi nhanh, sử dụng fastlane gym --export_method development — nó build IPA với profile Development để cài đặt trên thiết bị nhà phát triển. Build IPA cho App Store yêu cầu flag --export_method app-store và sử dụng chứng chỉ Distribution, phải được cấu hình trước trong Match hoặc Keychain.

# Xây dựng cho App Store với tên tùy chỉnh
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# Xây dựng với làm sạch trước khi archive
fastlane gym --clean --configuration Debug

# Xây dựng cho simulator không có IPA
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

Flag --clean xóa các tệp tạm của lần build trước trước khi chạy, ngăn chặn việc sử dụng cache lỗi thời và đảm bảo build sạch. Flag --destination cho phép chỉ định nền tảng mục tiêu cho build: iOS Simulator, iOS Device hoặc macOS Catalyst.

Tích hợp Gym vào CI/CD pipeline

Tích hợp Gym với CI/CD là thực hành tiêu chuẩn cho các nhóm phát triển iOS hướng tới phân phối liên tục. Gym được chạy trong pipeline GitHub Actions, GitLab CI, Bitrise hoặc Jenkins sau bước kiểm thử và trước khi gửi lên TestFlight hoặc App Store.

Một pipeline CI/CD iOS điển hình bao gồm: clone kho, cài đặt phụ thuộc qua CocoaPods hoặc SPM, cấu hình chứng chỉ qua Match, build IPA qua Gym và tải lên qua Pilot hoặc Deliver. GitLab CI là hệ thống tích hợp liên tục từ GitLab, cho phép chạy build sau mỗi lần push vào kho.

# Ví dụ bước xây dựng trong GitLab CI
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# Lưu IPA như artifact của bản dựng
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

Để Gym hoạt động chính xác trong CI, cần cấu hình quyền truy cập xcodebuild vào Keychain chứa chứng chỉ. Điều này được thực hiện qua lệnh security unlock-keychain trước khi chạy Gym. Nếu sử dụng Match, chứng chỉ được cài tự động và không cần cấu hình Keychain riêng — Match tự tạo một chuỗi khóa tạm thời cho build.

Sau khi build IPA thành công, nó có thể được chuyển đến các bước tiếp theo của pipeline: tải lên TestFlight qua Pilot hoặc gửi đến App Store Connect qua Deliver. Cấu hình biến môi trường của hệ thống CI để lưu trữ thông tin đăng nhập Apple Developer, bao gồm FASTLANE_APPLE_API_KEY và MATCH_PASSWORD, để tất cả các bước pipeline hoạt động mà không cần nhập tương tác.

Lỗi build Gym thường gặp

Khi sử dụng Gym, nhà phát triển thường gặp các lỗi liên quan đến cấu hình xcodebuild không chính xác, thiếu chứng chỉ hoặc không tương thích phiên bản Xcode. Chẩn đoán lỗi Gym bắt đầu bằng phân tích log build đầy đủ, được xuất ra console sau mỗi lệnh.

Lỗi « error: No matching provisioning profiles found » cho thấy không có Provisioning Profile phù hợp cho phương thức xuất đã chọn. Giải pháp: đảm bảo Match hoặc Keychain chứa profile chính xác cho export_method đã chỉ định. Provisioning Profile phải khớp với mã định danh ứng dụng và loại chứng chỉ (Development hoặc Distribution) để ký IPA thành công.

Lỗi « error: Signing for requires a development team » xảy ra khi không có nhóm phát triển nào được chỉ định trong dự án. Giải pháp: thêm DEVELOPMENT_TEAM vào cấu hình build của dự án hoặc chỉ định team_id trong Gymfile qua tham số export_team_id. Điều này đặc biệt quan trọng đối với các dự án làm việc với nhiều tài khoản Apple Developer.

Khi lỗi « error: Multiple commands produce... » xảy ra, có xung đột tệp đầu ra giữa các target khác nhau trong workspace. Giải pháp: cấu hình đường dẫn đầu ra duy nhất cho mỗi target trong Build Settings của dự án Xcode hoặc sử dụng hệ thống build mới, được bật mặc định trong Xcode 14 trở lên. Gym hỗ trợ cả hai tùy chọn qua flag --use_legacy_build_system.