Match (Fastlane): apa itu, manajemen sertifikat dan konfigurasi dalam pengembangan

Apa itu Match (Fastlane)?

Match (Fastlane) — adalah komponen ekosistem Fastlane, yang ditujukan untuk manajemen terpusat sertifikat Code Signing dan Provisioning Profiles untuk pengembangan iOS. Ini memecahkan masalah sinkronisasi tanda tangan di antara anggota tim dan mengotomatiskan konfigurasi sertifikat di pipeline CI/CD tanpa keterlibatan pengembang.

Tanpa Match, setiap anggota tim secara manual menghasilkan sertifikat melalui Xcode atau Apple Developer Portal, yang menyebabkan konflik saat membangun di mesin yang berbeda. Code Signing — adalah proses penandatanganan digital aplikasi iOS, yang mengonfirmasi kepengarangan dan integritasnya sebelum diinstal pada perangkat pengguna.

Menurut Apple Developer Documentation (2025), konfigurasi sertifikat yang salah adalah salah satu penyebab paling umum penolakan saat mengirimkan aplikasi ke App Store. Match secara otomatis memeriksa validitas sertifikat dan memperingatkan tentang masa berlaku yang akan berakhir, sehingga mengurangi risiko penolakan build pada tahap verifikasi Apple.

Gunakan Match di proyek apa pun dengan dua atau lebih pengembang atau dengan pipeline CI/CD — ini akan mengurangi waktu pengaturan lingkungan untuk anggota tim baru dari 30 menit menjadi satu perintah di terminal.

Bagaimana cara kerja Match: penyimpanan Git terenkripsi

Arsitektur Match dibangun di atas konsep sumber kebenaran tunggal untuk semua sertifikat tim iOS. Alih-alih penyimpanan lokal di keychain setiap pengembang, Match menyatukan sertifikat dalam satu repositori Git dengan enkripsi setiap file sebelum disimpan.

Prosesnya terdiri dari tiga tahap. Pada tahap inisialisasi, Match menghasilkan semua sertifikat dan profil yang diperlukan melalui Apple Developer Portal API. Setiap file dienkripsi dengan algoritma AES-256 dengan kunci yang dibentuk berdasarkan frasa sandi pengguna. File terenkripsi disimpan di repositori Git dan disinkronkan dengan server jarak jauh melalui operasi Git push dan pull standar.

Arsitektur enkripsi sertifikat

Match menggunakan kombinasi OpenSSL dan frasa sandi pengguna untuk mengenkripsi sertifikat dan profil. Kunci akses ditetapkan melalui variabel lingkungan MATCH_PASSWORD dan tidak disimpan di repositori, yang menghilangkan kebocoran bahkan saat server Git dikompromikan atau akses publik ke repositori.

Saat meminta sertifikat, Match memuat file terenkripsi dari repositori, mendekripsinya secara lokal menggunakan frasa sandi, dan menginstalnya di Keychain mesin saat ini. Setelah pembangunan selesai, sertifikat dapat dihapus dari Keychain untuk mematuhi kebijakan keamanan lingkungan perusahaan — ini mencegah penggunaan sertifikat usang di pembangunan berikutnya.

Setiap sertifikat disimpan dengan nama yang berisi pengidentifikasi aplikasi, jenis profil, dan tanggal pembuatan. Struktur ini memungkinkan Match untuk mengelola versi sertifikat dan, jika perlu, kembali ke keadaan sebelumnya melalui perintah Git revert dan reset standar. Ini sangat berguna saat penghapusan tidak sengaja atau penimpaan profil.

Pengaturan dan konfigurasi Match

Instalasi Match dilakukan bersama dengan Fastlane melalui manajer paket Ruby: gem install fastlane. Setelah instalasi, repositori sertifikat perlu diinisialisasi dengan perintah fastlane match init, yang membuat repositori Git kosong dan menghasilkan file Matchfile dengan template pengaturan dasar.

# Inisialisasi repositori Match
fastlane match init

Konfigurasi melalui Matchfile

File Matchfile berisi semua parameter koneksi ke repositori sertifikat: URL repositori Git, jenis profil default, pengidentifikasi aplikasi, dan kredensial Apple Developer. Contoh konfigurasi tipikal untuk tim yang terdiri dari lima pengembang:

# Matchfile configuration
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")

Parameter type menentukan jenis profil: :development untuk debugging pada perangkat pengembang, :appstore untuk publikasi di App Store, :adhoc untuk pengujian pada perangkat eksternal, dan :enterprise untuk distribusi perusahaan In-House di luar App Store. Setiap jenis membuat direktori terpisah di repositori, memungkinkan pengorganisasian profil berdasarkan skenario build target.

Match mendukung beberapa metode otentikasi di Apple Developer Portal: otentikasi dua faktor melalui Apple ID, App-Specific Password, dan kunci API App Store Connect API. Untuk CI/CD, disarankan menggunakan kunci API — kunci ini tidak memerlukan input kode konfirmasi interaktif dan tidak memblokir build otomatis saat perangkat pengembang berubah.

Pembuatan dan sinkronisasi profil

Setelah mengonfigurasi Matchfile, perintah fastlane match development atau fastlane match appstore dijalankan untuk membuat dan menyinkronkan profil. Match secara otomatis membuat atau memperbarui sertifikat melalui Apple Developer Portal API dan menyimpannya di repositori. Apple Developer Portal — adalah antarmuka web Apple untuk mengelola sertifikat, pengidentifikasi aplikasi, dan daftar perangkat pengembang yang diizinkan.

Saat pertama kali dijalankan, Match akan meminta frasa sandi untuk mengenkripsi repositori. Frasa ini harus disimpan di manajer rahasia CI/CD (GitHub Actions Secrets, GitLab CI Variables, atau Jenkins Credentials) dan diteruskan melalui variabel lingkungan MATCH_PASSWORD. Tanpanya, Match tidak akan dapat mendekripsi sertifikat di mesin lain atau di lingkungan CI.

Perintah dasar Match untuk manajemen sertifikat

Antarmuka Match terdiri dari serangkaian perintah untuk membuat, memperbarui, menyinkronkan, dan menghapus sertifikat dan profil. Setiap perintah sesuai dengan tindakan tertentu dalam siklus hidup Code Signing: dari pembuatan hingga pembersihan total repositori.

Perintah untuk pekerjaan sehari-hari

Perintah fastlane match development memuat atau membuat sertifikat dan profil Development untuk debugging pada perangkat lokal. Provisioning Profile — adalah dokumen digital Apple yang menghubungkan sertifikat pengembang dengan pengidentifikasi aplikasi dan daftar perangkat yang diizinkan untuk instalasi.

Untuk publikasi di App Store, digunakan fastlane match appstore — yang menghasilkan sertifikat Distribution dan profil AppStore. Perintah fastlane match adhoc membuat profil untuk pengujian pada perangkat eksternal, dan fastlane match enterprise — untuk aplikasi perusahaan In-House.

# Membuat profil Development untuk debugging
fastlane match development

# Membuat profil AppStore untuk rilis
fastlane match appstore

# Mengimpor sertifikat yang sudah ada secara manual
fastlane match import

Perintah fastlane match import memungkinkan penambahan sertifikat yang sudah ada ke repositori — berguna saat migrasi dari manajemen manual ke Match. Parameter --readonly memblokir semua perubahan di repositori, yang sangat penting untuk lingkungan CI, di mana pipeline tidak boleh membuat atau menghapus sertifikat dan profil secara otomatis.

Untuk pembersihan total repositori, digunakan perintah fastlane match nuke. Perintah ini menghapus semua sertifikat dari repositori Git, Apple Developer Portal, dan mesin lokal — pengaturan ulang total status Code Signing untuk proyek. Perintah hanya diterapkan pada konflik kritis atau saat pindah ke akun Apple Developer baru.

Integrasi Match ke dalam pipeline CI/CD

Integrasi CI/CD Match — salah satu keuntungan utama alat ini. Di pipeline GitHub Actions, GitLab CI, Bitrise, atau Jenkins, Match secara otomatis memuat dan menginstal sertifikat yang benar tanpa keterlibatan pengembang. Ini memungkinkan pembangunan dan penandatanganan aplikasi iOS yang sepenuhnya otomatis dari commit hingga IPA akhir.

Konfigurasi tipikal untuk GitHub Actions mencakup instalasi Fastlane, pengaturan variabel MATCH_PASSWORD, dan menjalankan Match dengan bendera --readonly. GitHub Actions — adalah platform CI/CD dari GitHub yang mengotomatiskan pembangunan, pengujian, dan publikasi kode berdasarkan peristiwa di repositori.

# Menginstal Fastlane di lingkungan CI
gem install fastlane --no-document

# Menjalankan Match dalam mode read-only tanpa hak perubahan
fastlane match development --readonly

Sebelum menjalankan Match di CI, akses ke repositori sertifikat perlu dikonfigurasi. Fastlane secara otomatis mengkloning repositori berdasarkan parameter git_url dari Matchfile. Akses ke repositori dikonfigurasi melalui kunci SSH atau personal access token, yang ditambahkan ke rahasia sistem CI — ini menjamin bahwa sertifikat tidak akan dikompromikan melalui akses publik.

Konfigurasikan variabel lingkungan MATCH_PASSWORD dan FASTLANE_APPLE_API_KEY di rahasia penyedia CI Anda. Kunci API App Store Connect memungkinkan Match untuk mengautentikasi di Apple Developer Portal tanpa otentikasi dua faktor, yang menghilangkan permintaan interaktif dalam build otomatis dan mencegah pemblokiran pipeline.

Kesalahan umum saat bekerja dengan Match

Bahkan dengan konfigurasi Match yang benar, kesalahan dapat terjadi terkait dengan kedaluwarsa sertifikat, konflik profil, atau konfigurasi lingkungan yang salah. Diagnostik masalah Match didasarkan pada analisis log perintah dan pemeriksaan repositori Git sertifikat untuk keaktualan.

Kesalahan paling umum — «You need to provide a password for Match» — terjadi ketika variabel lingkungan MATCH_PASSWORD tidak disetel di mesin atau di lingkungan CI. Solusi: tambahkan MATCH_PASSWORD ke variabel lingkungan sistem atau berikan kata sandi melalui parameter --keychain_password saat menjalankan perintah Match.

Masalah kedua yang paling sering terjadi adalah konflik sertifikat saat menambahkan perangkat baru ke profil AdHoc. Diselesaikan dengan perintah fastlane match adhoc --force, yang membuat ulang profil dengan mempertimbangkan perangkat baru. Apple Developer sertifikat berlaku selama satu tahun, setelah itu build yang menggunakannya ditolak oleh App Store Connect. Match memperingatkan tentang kedaluwarsa 30 hari sebelum akhir masa berlaku.

Pada kesalahan «Multiple matches found for...» di repositori terdapat beberapa versi dari sertifikat yang sama. Gunakan perintah fastlane match nuke untuk pembersihan total repositori dan penghapusan semua sertifikat dari Apple Developer Portal. Setelah pembersihan, lakukan pembuatan dari awal — ini menjamin keadaan profil yang konsisten tanpa duplikat dan versi yang bertentangan.