Match (Fastlane): ano ito, pamamahala ng sertipiko at pag-configure sa pag-develop

Ano ang Match (Fastlane)?

Match (Fastlane) — ay isang bahagi ng Fastlane ecosystem, na idinisenyo para sa sentralisadong pamamahala ng mga Code Signing certificate at Provisioning Profiles para sa pag-develop ng iOS. Nito nalulutas ang problema ng pag-sync ng mga lagda sa pagitan ng mga miyembro ng team at awtomatiko ang pag-configure ng mga sertipiko sa CI/CD pipeline nang walang partisipasyon ng developer.

Kung walang Match, bawat miyembro ng team ay manu-manong bumubuo ng mga sertipiko sa pamamagitan ng Xcode o Apple Developer Portal, na humahantong sa mga salungatan kapag nagbu-build sa iba’t ibang makina. Code Signing — ay ang proseso ng digital na pagpirma ng iOS application, na nagpapatunay sa pagmamay-ari at integridad nito bago i-install sa device ng user.

Ayon sa Apple Developer Documentation (2025), ang maling pag-configure ng mga sertipiko ay isa sa mga pinakakaraniwang dahilan ng pagtanggi kapag nagpapadala ng app sa App Store. Awtomatikong sinusuri ng Match ang bisa ng mga sertipiko at nagbabala tungkol sa mga malapit nang mag-expire, na nagbabawas sa panganib ng pagtanggi ng build sa yugto ng beripikasyon ng Apple.

Gamitin ang Match sa anumang proyekto na may dalawa o higit pang developer o may CI/CD pipeline — nito mababawasan ang oras ng pag-setup ng environment para sa bagong miyembro ng team mula 30 minuto hanggang isang command sa terminal.

Paano gumagana ang Match: naka-encrypt na Git repository

Arkitektura ng Match ay binuo sa konsepto ng iisang pinagmumulan ng katotohanan para sa lahat ng sertipiko ng iOS team. Sa halip na lokal na pag-iimbak sa keychain ng bawat developer, pinag-iisa ng Match ang mga sertipiko sa isang Git repository na may pag-encrypt ng bawat file bago i-save.

Ang proseso ay binubuo ng tatlong yugto. Sa yugto ng pagsisimula, bumubuo ang Match ng lahat ng kinakailangang sertipiko at profile sa pamamagitan ng Apple Developer Portal API. Bawat file ay naka-encrypt gamit ang AES-256 algorithm na may susi na nabuo batay sa passphrase ng user. Ang mga naka-encrypt na file ay nai-save sa Git repository at naka-sync sa remote server sa pamamagitan ng standard na Git push at pull operations.

Arkitektura ng pag-encrypt ng sertipiko

Gumagamit ang Match ng kombinasyon ng OpenSSL at user passphrase para i-encrypt ang mga sertipiko at profile. Ang access key ay itinakda sa pamamagitan ng environment variable na MATCH_PASSWORD at hindi nai-save sa repository, na nag-aalis ng pagtagas kahit na makompromiso ang Git server o may pampublikong access sa repository.

Kapag humihiling ng sertipiko, nilo-load ng Match ang naka-encrypt na file mula sa repository, dini-decrypt ito nang lokal gamit ang passphrase, at ini-install ito sa Keychain ng kasalukuyang makina. Pagkatapos ng build, ang mga sertipiko ay maaaring tanggalin mula sa Keychain para sumunod sa mga patakaran sa seguridad ng corporate environment — nito pumipigil sa paggamit ng mga lumang sertipiko sa mga susunod na build.

Bawat sertipiko ay nai-save na may pangalan na naglalaman ng identifier ng application, uri ng profile, at petsa ng paggawa. Ang istrukturang ito ay nagbibigay-daan sa Match na pamahalaan ang mga bersyon ng sertipiko at, kung kinakailangan, bumalik sa dating estado sa pamamagitan ng standard na Git revert at reset command. Ito ay lalong kapaki-pakinabang sa aksidenteng pagtanggal o pag-overwrite ng profile.

Pag-setup at konfigurasyon ng Match

Ang pag-install ng Match ay ginagawa kasama ng Fastlane sa pamamagitan ng Ruby package manager: gem install fastlane. Pagkatapos ng pag-install, kinakailangan ang pagsisimula ng repository ng sertipiko sa pamamagitan ng command na fastlane match init, na lumilikha ng walang laman na Git repository at bumubuo ng Matchfile file na may template ng mga pangunahing setting.

# Pagsisimula ng Match repository
fastlane match init

Konfigurasyon sa pamamagitan ng Matchfile

Ang file na Matchfile ay naglalaman ng lahat ng parameter ng koneksyon sa repository ng sertipiko: URL ng Git repository, default na uri ng profile, mga identifier ng application, at mga kredensyal ng Apple Developer. Halimbawa ng tipikal na konfigurasyon para sa isang team ng limang developer:

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

Ang parameter na type ay tumutukoy sa uri ng profile: :development para sa pag-debug sa mga device ng developer, :appstore para sa pag-publish sa App Store, :adhoc para sa pagsubok sa mga panlabas na device, at :enterprise para sa corporate In-House distribution sa labas ng App Store. Bawat uri ay lumilikha ng hiwalay na direktoryo sa repository, na nagbibigay-daan sa organisasyon ng mga profile ayon sa target na build scenario.

Sinusuportahan ng Match ang maraming paraan ng pag-authenticate sa Apple Developer Portal: dalawang-factor na pag-authenticate sa pamamagitan ng Apple ID, App-Specific Password, at API keys ng App Store Connect API. Para sa CI/CD, inirerekomenda ang paggamit ng API keys — hindi ito nangangailangan ng interactive na pag-input ng confirmation code at hindi humaharang sa mga awtomatikong build kapag nagbago ang device ng developer.

Pagbuo at pag-sync ng mga profile

Pagkatapos i-configure ang Matchfile, ang command na fastlane match development o fastlane match appstore ay isinasagawa para sa pagbuo at pag-sync ng mga profile. Awtomatikong gumagawa o nag-a-update ang Match ng mga sertipiko sa pamamagitan ng Apple Developer Portal API at nai-save ang mga ito sa repository. Apple Developer Portal — ay ang web interface ng Apple para sa pamamahala ng mga sertipiko, mga identifier ng application, at listahan ng mga pinapayagang device ng developer.

Sa unang pagtakbo, hihingi ang Match ng passphrase para i-encrypt ang repository. Ang passphrase na ito ay dapat na naka-save sa CI/CD secret manager (GitHub Actions Secrets, GitLab CI Variables o Jenkins Credentials) at ipinapasa sa pamamagitan ng environment variable na MATCH_PASSWORD. Kung wala ito, hindi maaaring i-decrypt ng Match ang mga sertipiko sa ibang mga makina o sa CI environment.

Mga pangunahing command ng Match para sa pamamahala ng sertipiko

Interface ng Match ay binubuo ng isang hanay ng mga command para sa paggawa, pag-update, pag-sync, at pagtanggal ng mga sertipiko at profile. Bawat command ay tumutugma sa isang partikular na aksyon sa lifecycle ng Code Signing: mula sa pagbuo hanggang sa kumpletong paglilinis ng repository.

Mga command para sa araw-araw na trabaho

Ang command na fastlane match development ay naglo-load o gumagawa ng Development certificate at profile para sa pag-debug sa mga lokal na device. Provisioning Profile — ay isang digital na dokumento ng Apple na nag-uugnay sa sertipiko ng developer sa identifier ng application at listahan ng mga device na pinapayagan para sa pag-install.

Para sa pag-publish sa App Store, ginagamit ang fastlane match appstore — nito bumubuo ng Distribution certificate at AppStore profile. Ang command na fastlane match adhoc ay gumagawa ng mga profile para sa pagsubok sa mga panlabas na device, at fastlane match enterprise — para sa mga corporate In-House application.

# Pagbuo ng Development profile para sa pag-debug
fastlane match development

# Pagbuo ng AppStore profile para sa pag-release
fastlane match appstore

# Pag-import ng mga umiiral na manual na ginawang sertipiko
fastlane match import

Ang command na fastlane match import ay nagbibigay-daan sa pagdagdag ng mga umiiral na sertipiko sa repository — kapaki-pakinabang sa paglipat mula sa manu-manong pamamahala patungo sa Match. Ang parameter na --readonly ay humaharang sa lahat ng pagbabago sa repository, na kritikal para sa CI environment, kung saan ang pipeline ay hindi dapat gumawa o magtanggal ng mga sertipiko at profile nang awtomatiko.

Para sa kumpletong paglilinis ng repository, ginagamit ang command na fastlane match nuke. Nito tinatanggal ang lahat ng sertipiko mula sa Git repository, Apple Developer Portal, at lokal na makina — isang kumpletong pag-reset ng estado ng Code Signing para sa proyekto. Ang command ay inilalapat lamang sa mga kritikal na salungatan o kapag lumipat sa bagong Apple Developer account.

Pagsasama ng Match sa CI/CD pipeline

Pagsasama ng CI/CD ng Match — isa sa mga pangunahing bentahe ng tool. Sa pipeline ng GitHub Actions, GitLab CI, Bitrise o Jenkins, awtomatikong naglo-load at nag-install ang Match ng tamang mga sertipiko nang walang partisipasyon ng developer. Nito nagbibigay-daan sa ganap na awtomatikong pagbuo at pagpirma ng iOS application mula sa commit hanggang sa huling IPA.

Ang tipikal na konfigurasyon para sa GitHub Actions ay kinabibilangan ng pag-install ng Fastlane, pag-set ng MATCH_PASSWORD variable, at pagpapatakbo ng Match na may bandila na --readonly. GitHub Actions — ay isang CI/CD platform mula sa GitHub na nag-automate ng pagbuo, pagsubok, at pag-publish ng code batay sa mga pangyayari sa repository.

# Pag-install ng Fastlane sa CI environment
gem install fastlane --no-document

# Pagpapatakbo ng Match sa read-only mode nang walang karapatang magbago
fastlane match development --readonly

Bago patakbuhin ang Match sa CI, kailangan i-configure ang access sa repository ng sertipiko. Awtomatikong kino-clone ng Fastlane ang repository batay sa parameter na git_url mula sa Matchfile. Ang access sa repository ay naka-configure sa pamamagitan ng SSH key o personal access token, na idinagdag sa mga sikreto ng CI system — nito ginagarantiyahan na ang mga sertipiko ay hindi makompromiso sa pamamagitan ng pampublikong access.

I-configure ang mga environment variable na MATCH_PASSWORD at FASTLANE_APPLE_API_KEY sa mga sikreto ng iyong CI provider. Ang API key ng App Store Connect ay nagbibigay-daan sa Match na mag-authenticate sa Apple Developer Portal nang walang dalawang-factor na pag-authenticate, na nag-aalis ng mga interactive na kahilingan sa mga awtomatikong build at pumipigil sa pag-block ng pipeline.

Mga karaniwang error kapag nagtatrabaho sa Match

Kahit na may tamang konfigurasyon ng Match, maaaring magkaroon ng mga error na nauugnay sa pag-expire ng sertipiko, salungatan ng profile, o maling konfigurasyon ng environment. Diagnosis ng problema ng Match ay batay sa pagsusuri ng mga log ng command at pag-check ng Git repository ng mga sertipiko para sa pagiging napapanahon.

Ang pinakakaraniwang error — «You need to provide a password for Match» — ay nangyayari kapag ang environment variable na MATCH_PASSWORD ay hindi naka-set sa makina o sa CI environment. Solusyon: idagdag ang MATCH_PASSWORD sa mga environment variable ng system o ipasa ang password sa pamamagitan ng parameter na --keychain_password kapag pinapatakbo ang Match command.

Ang pangalawang pinakamadalas na problema ay salungatan ng sertipiko kapag nagdadagdag ng bagong device sa AdHoc profile. Nalulutas sa pamamagitan ng command na fastlane match adhoc --force, na muling gumagawa ng mga profile na isinasaalang-alang ang mga bagong device. Apple Developer ang mga sertipiko ay may bisa ng isang taon, pagkatapos nito ang build na gumagamit ng mga ito ay tinatanggihan ng App Store Connect. Nagbabala ang Match tungkol sa pag-expire 30 araw bago ang katapusan ng termino.

Sa error na «Multiple matches found for...» sa repository ay mayroong maraming bersyon ng parehong sertipiko. Gamitin ang command na fastlane match nuke para sa kumpletong paglilinis ng repository at pagtanggal ng lahat ng sertipiko mula sa Apple Developer Portal. Pagkatapos ng paglilinis, isagawa ang pagbuo mula sa simula — nito ginagarantiyahan ang consistent na estado ng mga profile nang walang mga duplicate at nagkakasalungat na bersyon.