Match (Fastlane): iOS 인증서 관리 및 개발 환경 설정

Match (Fastlane)이란?

Match (Fastlane)은 iOS 개발을 위한 Code Signing 인증서와 Provisioning Profiles를 중앙에서 관리하는 Fastlane 에코시스템의 구성 요소입니다. 팀원 간 서명 동기화 문제를 해결하고 개발자 개입 없이 CI/CD 파이프라인에서 인증서 설정을 자동화합니다.

Match가 없으면 각 팀원이 Xcode 또는 Apple Developer Portal을 통해 수동으로 인증서를 생성해야 하며, 이는 여러 머신에서 빌드 시 충돌을 유발합니다. Code Signing은 iOS 앱에 디지털 서명하여 사용자 기기에 설치되기 전에 앱의 작성자와 무결성을 확인하는 프로세스입니다.

Apple Developer Documentation(2025)에 따르면 잘못된 인증서 설정은 App Store에 앱을 제출할 때 거부되는 가장 흔한 원인 중 하나입니다. Match는 인증서 유효성을 자동으로 확인하고 만료 기한을 경고하여 Apple 검증 단계에서 빌드가 거부될 위험을 줄입니다.

두 명 이상의 개발자가 있거나 CI/CD 파이프라인이 있는 모든 프로젝트에서 Match를 사용하세요. 새 팀원의 환경 설정 시간을 30분에서 터미널 명령어 한 줄로 단축할 수 있습니다.

Match 작동 방식: 암호화된 Git 저장소

Match 아키텍처는 iOS 팀의 모든 인증서에 대한 단일 진실 공급원(Single Source of Truth) 개념을 기반으로 합니다. 각 개발자의 키체인에 로컬로 저장하는 대신 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 설치는 Ruby 패키지 관리자를 통해 Fastlane과 함께 수행됩니다: gem install fastlane. 설치 후 fastlane match init 명령어로 인증서 저장소를 초기화하면 빈 Git 저장소가 생성되고 기본 설정 템플릿이 포함된 Matchfile이 생성됩니다.

# Match 저장소 초기화
fastlane match init

Matchfile을 통한 구성

Matchfile에는 Git 저장소 URL, 기본 프로필 유형, 앱 식별자 및 Apple Developer 자격 증명 등 인증서 저장소 연결에 필요한 모든 매개변수가 포함됩니다. 5인 개발팀을 위한 일반적인 구성 예시입니다:

# 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는 App Store 외부의 In-House 기업 배포용입니다. 각 유형은 저장소에 별도의 디렉터리를 생성하므로 빌드 대상 시나리오별로 프로필을 구성할 수 있습니다.

Match는 Apple Developer Portal에 대한 여러 인증 방식을 지원합니다: Apple ID를 통한 2단계 인증, 앱별 비밀번호(App-Specific Password) 및 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 계정으로 이전할 때만 사용합니다.

CI/CD 파이프라인에 Match 통합

CI/CD 통합은 Match의 주요 장점 중 하나입니다. GitHub Actions, GitLab CI, Bitrise 또는 Jenkins 파이프라인에서 Match는 개발자 개입 없이 올바른 인증서를 자동으로 다운로드하고 설치합니다. 이를 통해 커밋부터 완성된 IPA까지 iOS 앱의 완전 자동화된 빌드 및 서명을 구현할 수 있습니다.

GitHub Actions의 일반적인 구성에는 Fastlane 설치, MATCH_PASSWORD 환경 변수 설정 및 --readonly 플래그로 Match 실행이 포함됩니다. GitHub Actions는 GitHub의 CI/CD 플랫폼으로, 저장소의 이벤트를 기반으로 코드 빌드, 테스트 및 게시를 자동화합니다.

# CI 환경에 Fastlane 설치
gem install fastlane --no-document

# 변경 권한 없이 읽기 전용 모드로 Match 실행
fastlane match development --readonly

CI에서 Match를 실행하기 전에 인증서 저장소에 대한 접근을 설정해야 합니다. Fastlane은 Matchfile의 git_url 매개변수를 기반으로 저장소를 자동으로 복제합니다. 저장소 접근은 CI 시스템의 시크릿에 추가된 SSH 키 또는 personal access token을 통해 구성됩니다. 이를 통해 공개 접근을 통한 인증서 유출을 방지할 수 있습니다.

CI 제공업체의 시크릿에 MATCH_PASSWORD 및 FASTLANE_APPLE_API_KEY 환경 변수를 설정하세요. App Store Connect API 키를 사용하면 Match가 2단계 인증 없이 Apple Developer Portal에 인증할 수 있으므로 자동 빌드에서 대화형 요청이 필요 없고 파이프라인 차단을 방지할 수 있습니다.

Match 사용 시 일반적인 오류

Match를 올바르게 설정했더라도 인증서 만료, 프로필 충돌 또는 잘못된 환경 구성과 관련된 오류가 발생할 수 있습니다. 문제 진단은 명령어 로그 분석과 인증서 Git 저장소의 최신 상태 확인을 기반으로 합니다.

가장 흔한 오류인 “You need to provide a password for Match”는 머신이나 CI 환경에 MATCH_PASSWORD 환경 변수가 설정되지 않은 경우 발생합니다. 해결 방법: MATCH_PASSWORD를 시스템 환경 변수에 추가하거나 Match 명령어 실행 시 --keychain_password 매개변수로 암호를 전달합니다.

두 번째로 흔한 문제는 AdHoc 프로필에 새 기기를 추가할 때 발생하는 인증서 충돌입니다. fastlane match adhoc --force 명령어로 새 기기를 반영하여 프로필을 다시 생성하면 해결됩니다. Apple Developer 인증서는 1년 동안 유효하며, 이후 해당 인증서로 빌드하면 App Store Connect에서 거부됩니다. Match는 만료 30일 전에 경고합니다.

“Multiple matches found for...” 오류는 저장소에 동일한 인증서의 여러 버전이 있는 경우 발생합니다. fastlane match nuke 명령어를 사용하여 저장소를 완전히 정리하고 Apple Developer Portal에서 모든 인증서를 삭제하세요. 정리 후 처음부터 다시 생성하면 중복이나 충돌 버전 없이 일관된 프로필 상태가 보장됩니다.