Match (Fastlane): керування сертифікатами та налаштування в розробці iOS

Що таке Match (Fastlane)?

Match (Fastlane) — це компонент екосистеми Fastlane, призначений для централізованого керування сертифікатами Code Signing і Provisioning Profiles для iOS-розробки. Він вирішує проблему синхронізації підписів між учасниками команди та автоматизує налаштування сертифікатів у CI/CD пайплайнах без участі розробника.

Без Match кожен учасник команди вручну генерує сертифікати через Xcode або Apple Developer Portal, що призводить до конфліктів при збірці на різних машинах. Code Signing — це процес цифрового підпису iOS-додатку, який підтверджує його авторство та цілісність перед встановленням на пристрій користувача.

За даними Apple Developer Documentation (2025), невірне налаштування сертифікатів — одна з найчастіших причин відмови при надсиланні додатку в App Store. Match автоматично перевіряє дійсність сертифікатів і попереджає про терміни закінчення, що знижує ризик відхилення збірки на етапі верифікації Apple.

Використовуйте Match у будь-якому проєкті з двома та більше розробниками або за наявності CI/CD пайплайну — це скоротить час на налаштування середовища нового учасника команди з 30 хвилин до однієї команди в терміналі.

Як працює Match: зашифроване Git-сховище

Архітектура Match побудована на концепції єдиного джерела істини для всіх сертифікатів iOS-команди. Замість локального зберігання у зв'язці ключів кожного розробника Match об'єднує сертифікати в одному Git-репозиторію з шифруванням кожного файлу перед збереженням.

Процес складається з трьох етапів. На етапі ініціалізації Match генерує всі необхідні сертифікати та профілі через Apple Developer Portal API. Кожен файл шифрується алгоритмом AES-256 з ключем, який формується на основі користувацької парольної фрази. Зашифровані файли зберігаються в Git-репозиторій і синхронізуються з віддаленим сервером через стандартні Git-операції push та pull.

Архітектура шифрування сертифікатів

Match використовує комбінацію OpenSSL та користувацької парольної фрази для шифрування сертифікатів і профілів. Ключ доступу задається через змінну середовища MATCH_PASSWORD і не зберігається в репозиторію, що виключає витік навіть при компрометації Git-сервера або публічному доступі до репозиторію.

При запиті сертифіката Match завантажує зашифрований файл з репозиторію, розшифровує його локально з використанням парольної фрази та встановлює в Keychain поточної машини. Після завершення збірки сертифікати можуть бути видалені з Keychain для дотримання політик безпеки корпоративного середовища — це запобігає використанню застарілих сертифікатів у наступних збірках.

Кожен сертифікат зберігається з іменем, що містить ідентифікатор додатку, тип профілю та дату створення. Така структура дозволяє Match керувати версіями сертифікатів і при необхідності відкочувати зміни до попереднього стану через стандартні Git-команди revert та reset. Це особливо корисно при випадковому видаленні або перезаписі профілю.

Налаштування та конфігурація Match

Встановлення Match виконується разом з Fastlane через менеджер пакетів Ruby: gem install fastlane. Після встановлення необхідно ініціалізувати сховище сертифікатів командою fastlane match init, яка створює порожній Git-репозиторій і генерує файл Matchfile з шаблоном базових налаштувань.

# Ініціалізація репозиторію Match
fastlane match init

Конфігурація через Matchfile

Файл Matchfile містить всі параметри підключення до сховища сертифікатів: URL Git-репозиторію, тип профілів за замовчуванням, ідентифікатори додатків та облікові дані Apple 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")

Параметр type визначає тип профілів: :development для налагодження на пристроях розробників, :appstore для публікації в App Store, :adhoc для тестування на зовнішніх пристроях та :enterprise для корпоративного розповсюдження In-House поза App Store. Кожен тип створює окрему директорію в репозиторію, що дозволяє організувати профілі за цільовими сценаріями збірки.

Match підтримує декілька способів автентифікації в Apple Developer Portal: двофакторна автентифікація через Apple ID, пароль для конкретного додатку (App-Specific Password) та API-ключі App Store Connect API. Для CI/CD рекомендується використовувати API-ключі — вони не вимагають інтерактивного введення коду підтвердження та не блокують автоматичні збірки при зміні пристрою розробника.

Генерація та синхронізація профілів

Після налаштування Matchfile виконується команда fastlane match development або fastlane match appstore для генерації та синхронізації профілів. Match автоматично створює або оновлює сертифікати через Apple Developer Portal API та зберігає їх у репозиторій. Apple Developer Portal — це веб-інтерфейс Apple для керування сертифікатами, ідентифікаторами додатків та списком дозволених пристроїв розробників.

При першому запуску Match запитає парольну фразу для шифрування репозиторію. Ця фраза повинна бути збережена в менеджері секретів CI/CD (GitHub Actions Secrets, GitLab CI Variables або Jenkins Credentials) та передана через змінну середовища MATCH_PASSWORD. Без неї Match не зможе розшифрувати сертифікати на інших машинах або в CI-середовищі.

Основні команди Match для керування сертифікатами

Інтерфейс Match складається з набору команд для створення, оновлення, синхронізації та видалення сертифікатів і профілів. Кожна команда відповідає певній дії в життєвому циклі Code Signing: від генерації до повного очищення репозиторію.

Команди для щоденної роботи

Команда fastlane match development завантажує або створює Development-сертифікати та профілі для налагодження на локальних пристроях. Provisioning Profile — це цифровий документ Apple, який пов'язує сертифікат розробника з ідентифікатором додатку та списком дозволених для встановлення пристроїв.

Для публікації в App Store використовується fastlane match appstore — вона генерує Distribution-сертифікати та AppStore-профілі. Команда fastlane match adhoc створює профілі для тестування на зовнішніх пристроях, а fastlane match enterprise — для корпоративних додатків In-House.

# Створення Development профілів для налагодження
fastlane match development

# Створення AppStore профілів для релізу
fastlane match appstore

# Імпорт існуючих вручну сертифікатів
fastlane match import

Команда fastlane match import дозволяє додати в репозиторій вже існуючі сертифікати — корисно при міграції з ручного керування на Match. Параметр --readonly блокує будь-які зміни в репозиторію, що критично для CI-середовища, де пайплайн не повинен створювати або видаляти сертифікати та профілі автоматично.

Для повного очищення репозиторію використовується команда fastlane match nuke. Вона видаляє всі сертифікати з Git-сховища, з Apple Developer Portal та з локальної машини — це повне скидання стану Code Signing для проєкту. Команда застосовується тільки при критичних конфліктах або при переході на новий обліковий запис Apple Developer.

Інтеграція Match у CI/CD пайплайн

CI/CD інтеграція Match — одна з ключових переваг інструменту. У пайплайні GitHub Actions, GitLab CI, Bitrise або Jenkins Match автоматично завантажує та встановлює правильні сертифікати без участі розробника. Це дозволяє реалізувати повністю автоматизовану збірку та підпис iOS-додатку від коміту до готового IPA.

Типова конфігурація для GitHub Actions включає встановлення Fastlane, налаштування змінної MATCH_PASSWORD та запуск Match з прапорцем --readonly. GitHub Actions — це платформа CI/CD від GitHub, яка автоматизує збірку, тестування та публікацію коду на основі подій у репозиторію.

# Встановлення Fastlane в CI-середовищі
gem install fastlane --no-document

# Запуск Match у режимі лише для читання без права змін
fastlane match development --readonly

Перед запуском Match у CI необхідно налаштувати доступ до репозиторію сертифікатів. Fastlane автоматично клонує його на основі параметра git_url з Matchfile. Доступ до репозиторію налаштовується через SSH-ключ або personal access token, які додаються в секрети CI-системи — це гарантує, що сертифікати не будуть скомпрометовані через відкритий доступ.

Налаштуйте змінні середовища MATCH_PASSWORD та FASTLANE_APPLE_API_KEY у секретах вашого CI-провайдера. API-ключ App Store Connect дозволяє Match автентифікуватися в Apple Developer Portal без двофакторної автентифікації, що виключає інтерактивні запити в автоматичних збірках і запобігає блокуванню пайплайну.

Типові помилки при роботі з Match

Навіть при правильному налаштуванні Match можуть виникати помилки, пов'язані із закінченням терміну дії сертифікатів, конфліктами профілів або невірною конфігурацією середовища. Діагностика проблем Match будується на аналізі логів команди та перевірці стану Git-репозиторію сертифікатів на актуальність.

Найчастіша помилка — «You need to provide a password for Match» — виникає, коли змінна середовища MATCH_PASSWORD не встановлена на машині або в CI-середовищі. Рішення: додати MATCH_PASSWORD у змінні середовища системи або передати пароль через параметр --keychain_password при запуску команди Match.

Друга за частотою проблема — конфлікт сертифікатів при додаванні нового пристрою в AdHoc профіль. Вирішується командою fastlane match adhoc --force, яка перестворює профілі з урахуванням нових пристроїв. Apple Developer сертифікати діють один рік, після чого збірка з їх використанням відхиляється App Store Connect. Match попереджає про закінчення за 30 днів до завершення терміну.

При помилці «Multiple matches found for...» у репозиторію присутні декілька версій одного сертифіката. Використовуйте команду fastlane match nuke для повного очищення репозиторію та видалення всіх сертифікатів з Apple Developer Portal. Після очищення виконайте генерацію з нуля — це гарантує консистентний стан профілів без дублікатів та конфліктуючих версій.