Gym (Fastlane): apa itu, pembuatan IPA dan otomatisasi dalam pengembangan aplikasi

Apa itu Gym (Fastlane)?

Gym (Fastlane) adalah komponen dari ekosistem Fastlane yang menyediakan pembuatan aplikasi iOS ke format IPA melalui satu perintah terminal. Alat ini mengabstraksi proses kompleks pemanggilan xcodebuild dengan puluhan flag dan memberikan pengembang antarmuka sederhana dengan nilai default yang masuk akal.

Di Xcode, untuk membuat IPA diperlukan membuka proyek, memilih skema, mengonfigurasi Archive dan Export, menentukan metode distribusi dan menunggu hingga selesai. Otomatisasi pembuatan melalui Gym menghilangkan langkah-langkah manual dan menjamin bahwa setiap pembuatan dijalankan dengan parameter yang sama — ini penting untuk prediktabilitas pipeline CI/CD.

Menurut SwiftLee (2024), tim yang menggunakan Gym untuk pembuatan menghabiskan waktu 40% lebih sedikit untuk mengonfigurasi proses rilis dibandingkan dengan ekspor manual melalui Xcode Organizer. Gym juga menghasilkan log pembuatan terperinci dengan indikasi setiap langkah xcodebuild, yang menyederhanakan debugging build yang gagal dan analisis kesalahan kompilasi.

Gunakan Gym di proyek iOS mana pun yang memerlukan pembuatan IPA secara teratur untuk pengujian atau publikasi — ini adalah satu-satunya cara untuk menjamin konfigurasi pembuatan yang identik di semua mesin dalam tim.

Bagaimana Gym membangun IPA: proses dan parameter

Proses pembuatan IPA melalui Gym

Pembuatan IPA melalui Gym terdiri dari tiga tahap berurutan: pengarsipan proyek melalui xcodebuild, ekspor arsip ke paket biner dan pengemasan ke format IPA dengan tanda tangan. Gym secara otomatis menentukan jenis proyek (single target atau workspace) dan memilih metode pembuatan yang tepat.

Pada tahap pengarsipan, Gym menjalankan xcodebuild archive dengan parameter skema dan konfigurasi yang ditentukan dalam proyek. Setelah berhasil membuat arsip .xcarchive, Gym menjalankan xcodebuild -exportArchive dengan metode ekspor yang dipilih. Ekspor IPA adalah proses konversi arsip .xcarchive ke file instalasi .ipa dengan menyertakan semua sumber daya dan tanda tangan yang diperlukan.

Parameter ekspor pembuatan

Metode ekspor menentukan jenis Provisioning Profile yang akan digunakan untuk menandatangani IPA. Gym mendukung empat metode: development untuk debugging di perangkat pengembang, app-store untuk publikasi di App Store, ad-hoc untuk pengujian beta pada jumlah perangkat terbatas dan enterprise untuk distribusi perusahaan.

Parameter tambahan mencakup penentuan export_options_plist untuk konfigurasi ekspor yang tepat, penekanan Swift overlay untuk mengurangi ukuran IPA dan pengelolaan bitcode. Gym juga mendukung pembuatan untuk simulator melalui flag --skip_package_ipa, yang berguna untuk pemeriksaan kode cepat tanpa ekspor lengkap.

# Build IPA dasar melalui Gym
fastlane gym --workspace "MyApp.xcworkspace" --scheme "MyApp"

# Build dengan metode ekspor yang ditentukan
fastlane gym --export_method app-store

# Build arsip saja tanpa ekspor IPA
fastlane gym --skip_package_ipa

Konfigurasi Gym melalui Gymfile

Gymfile adalah file konfigurasi Fastlane yang menyimpan semua parameter pembuatan dalam format Ruby terstruktur. Berbeda dengan memberikan flag melalui baris perintah, Gymfile memungkinkan untuk menetapkan konfigurasi di repositori dan menjamin bahwa semua pengembang dan CI menggunakan pengaturan pembuatan yang identik.

# Gymfile — konfigurasi build
workspace("MyApp.xcworkspace")
scheme("MyApp")
export_method(:app-store)
configuration("Release")
output_directory("./build")
output_name("MyApp.ipa")
include_symbols(true)
include_bitcode(false)

Parameter export_method di Gymfile sesuai dengan jenis profil dari Apple Developer Portal. Untuk rilis App Store digunakan :app-store, untuk pengujian — :development atau :ad-hoc. Parameter configuration menentukan konfigurasi pembuatan: Release untuk rilis atau Debug untuk versi debugging.

Parameter include_bitcode mengontrol penyertaan bitcode ke dalam IPA. Apple memerlukan bitcode untuk aplikasi watchOS dan tvOS, tetapi untuk iOS parameter ini dapat dinonaktifkan untuk mengurangi ukuran file biner. include_symbols menyertakan file debugging simbolis .dSYM yang diperlukan untuk simbolisasi log crash dari App Store Connect atau layanan pemantauan pihak ketiga.

Parameter tambahan Gymfile mencakup export_options_plist untuk file plist ekspor khusus, silent untuk menekan keluaran berlebih di log dan build_path untuk menentukan direktori pembuatan sementara. Parameter ini berguna saat mengintegrasikan Gym ke dalam pipeline CI/CD yang kompleks dengan persyaratan artefak khusus.

Perintah Gym untuk pembuatan aplikasi

Antarmuka perintah Gym mencakup parameter dasar untuk skenario pembuatan tipikal dan flag lanjutan untuk konfigurasi perilaku yang tepat. Sebagian besar parameter dapat diberikan baik melalui baris perintah maupun melalui Gymfile, dengan argumen baris perintah memiliki prioritas di atas file konfigurasi.

Perintah fastlane gym tanpa parameter menggunakan pengaturan dari Gymfile atau secara otomatis menentukan proyek di direktori saat ini. Untuk proyek dengan beberapa target, perlu menentukan --scheme dan --workspace untuk pemilihan konfigurasi pembuatan target yang tepat.

Perintah pembuatan tipikal

Untuk pembuatan debug cepat digunakan fastlane gym --export_method development — ini membuat IPA dengan profil Development untuk instalasi di perangkat pengembang. Pembuatan IPA untuk App Store memerlukan flag --export_method app-store dan penggunaan sertifikat Distribution yang harus dikonfigurasi sebelumnya di Match atau Keychain.

# Build untuk App Store dengan nama kustom
fastlane gym --export_method app-store --output_name "Release_1.0.ipa"

# Build dengan pembersihan sebelum pengarsipan
fastlane gym --clean --configuration Debug

# Build untuk simulator tanpa IPA
fastlane gym --skip_package_ipa --destination "generic/platform=iOS Simulator"

Flag --clean menghapus file sementara dari pembuatan sebelumnya sebelum dijalankan, yang mencegah penggunaan cache usang dan menjamin pembuatan yang bersih. Flag --destination memungkinkan untuk menentukan platform target untuk pembuatan: iOS Simulator, iOS Device atau macOS Catalyst.

Integrasi Gym ke dalam pipeline CI/CD

Integrasi Gym dengan CI/CD adalah praktik standar untuk tim pengembang iOS yang berusaha mencapai pengiriman berkelanjutan. Gym dijalankan dalam pipeline GitHub Actions, GitLab CI, Bitrise atau Jenkins setelah tahap pengujian dan sebelum pengiriman ke TestFlight atau App Store.

Pipeline iOS CI/CD tipikal mencakup: kloning repositori, instalasi dependensi melalui CocoaPods atau SPM, konfigurasi sertifikat melalui Match, pembuatan IPA melalui Gym dan pengunggahan melalui Pilot atau Deliver. GitLab CI adalah sistem integrasi berkelanjutan dari GitLab yang memungkinkan memulai pembuatan pada setiap push ke repositori.

# Contoh langkah build di GitLab CI
fastlane gym --scheme "MyApp" \
      --export_method app-store \
      --output_directory "$CI_PROJECT_DIR/build"
      
# Menyimpan IPA sebagai artefak build
cp "build/MyApp.ipa" "$CI_PROJECT_DIR/artifacts/"

Untuk kerja Gym yang benar di CI, perlu mengonfigurasi akses xcodebuild ke Keychain dengan sertifikat. Ini dilakukan melalui perintah security unlock-keychain sebelum menjalankan Gym. Jika menggunakan Match, sertifikat diinstal secara otomatis dan konfigurasi Keychain terpisah tidak diperlukan — Match sendiri membuat keychain sementara untuk pembuatan.

Setelah pembuatan berhasil, IPA dapat diteruskan ke langkah pipeline berikutnya: pengunggahan ke TestFlight melalui Pilot atau pengiriman ke App Store Connect melalui Deliver. Konfigurasikan variabel lingkungan sistem CI untuk menyimpan kredensial Apple Developer, termasuk FASTLANE_APPLE_API_KEY dan MATCH_PASSWORD, agar semua tahap pipeline berfungsi tanpa input interaktif.

Kesalahan umum pembuatan Gym

Saat menggunakan Gym, pengembang sering menghadapi kesalahan terkait konfigurasi xcodebuild yang salah, kurangnya sertifikat atau ketidakcocokan versi Xcode. Diagnostik kesalahan Gym dimulai dengan analisis log pembuatan lengkap yang ditampilkan di konsol setelah setiap perintah selesai.

Kesalahan «error: No matching provisioning profiles found» menunjukkan tidak adanya Provisioning Profile yang cocok untuk metode ekspor yang dipilih. Solusi: pastikan Match atau Keychain berisi profil yang benar untuk export_method yang ditentukan. Provisioning Profile harus sesuai dengan pengidentifikasi aplikasi dan jenis sertifikat (Development atau Distribution) untuk penandatanganan IPA yang berhasil.

Kesalahan «error: Signing for requires a development team» terjadi ketika tim pengembangan tidak ditentukan dalam proyek. Solusi: tambahkan DEVELOPMENT_TEAM ke konfigurasi pembuatan proyek atau tentukan team_id di Gymfile melalui parameter export_team_id. Ini sangat penting untuk proyek yang bekerja dengan beberapa akun Apple Developer.

Pada kesalahan «error: Multiple commands produce...» terjadi konflik file keluaran antara target yang berbeda di workspace. Solusi: konfigurasikan jalur keluaran unik untuk setiap target di Build Settings proyek Xcode atau gunakan sistem build baru yang diaktifkan secara default di Xcode 14 dan yang lebih baru. Gym mendukung kedua varian melalui flag --use_legacy_build_system.