클라우드 Mac 팀 서명 인증서 관리:fastlane match와 헤드리스 Keychain 잠금 해제

새벽 2시, 팀에서 세 번째 사람이 같은 클라우드 Mac에서 fastlane build를 실행했는데 CI가 곧바로 오류를 냈다. 인증서가 유효하지 않다는 것이었다. 세 사람 모두 각자 로컬에서 match를 실행한 적이 있었지만, 아무도 자신의 그 한 번의 작업이 다른 사람이 방금 가져온 서명 인증서를 시스템 기본 Keychain에서 밀어냈다는 사실을 눈치채지 못했다. 여러 사람이 클라우드 Mac 한 대를 공유해 빌드를 출력하는 환경에서는 이런 사고가 거의 필연적으로 발생한다. 이 글은 fastlane match로 인증서를 통합 관리하는 방법과, 헤드리스 원격 세션에서 Keychain이 계속 비밀번호를 요구하는 문제를 어떻게 해결했는지를 정리한 기록이다.

문제: 클라우드 Mac을 공유하면 왜 인증서가 계속 꼬이는가

로컬 개발 환경에서는 Mac 한 대가 보통 한 사람만 사용하기 때문에 기본 Keychain에 인증서를 넣어도 서로 충돌할 일이 없다. 하지만 일 단위로 대여하는 클라우드 Mac은 흔히 팀이 공유해서 쓴다. 오늘은 당신이 접속해서 빌드를 만들고, 내일은 동료가 원격으로 로그인해 설정을 바꾸고 다시 빌드를 돌리는 식이다. 만약 모두가 각자 fastlane match development를 실행하거나 수동으로 p12를 가져온다면, 기본 Keychain 안의 인증서 항목은 계속 덮어씌워지고 삭제되고 다시 만들어지며, 결국 "인증서는 존재하지만 서명 시 개인 키를 찾을 수 없다"는 전형적인 오류가 발생한다.

근본 원인은 원래 분리되어야 할 두 가지 일이 뒤섞여 있다는 데 있다. 인증서의 저장과 배포, 그리고 로컬 Keychain에서의 일시적인 인증서 사용 승인이다. 전자는 중앙에서 관리해야 하고, 후자는 세션 단위로 격리해야 한다.

fastlane match의 핵심 개념

match는 개발용 인증서, 배포용 인증서와 그에 대응하는 프로비저닝 프로파일을 암호화해서 별도의 Git 저장소에 통합 저장한다. 팀의 모든 구성원(그리고 클라우드 Mac의 자동화 계정)은 각자 Apple Developer 콘솔에서 새로 생성하는 게 아니라 이 저장소에서 동일한 인증서를 가져온다. 이렇게 하면 동일한 Bundle ID가 어떤 머신에서든 동일한 서명 결과를 갖도록 보장할 수 있고, "인증서 수가 Apple 한도를 초과한다"는 오래된 문제도 피할 수 있다.

match의 가치는 "인증서를 자동으로 생성해 준다"는 데 있지 않고, "더 이상 각자 인증서를 생성할 필요가 없어진다"는 데 있다—이 한 문장이 match를 어떻게 써야 하는지를 결정한다. 쓰기(write) 작업은 오직 한 사람(또는 한 번의 CI 초기화 작업)만 실행해야 하고, 그 외 모든 상황에서는 읽기 전용 모드로 가져와야 한다.

클라우드 Mac에서 인증서 저장소 초기화하기

클라우드 Mac의 프로젝트 디렉터리에서, 먼저 Matchfile이 공개 주소가 아니라 프라이빗 저장소를 가리키는지 확인한다.

git_url("git@github.com:your-org/certs-private.git")
storage_mode("git")
type("appstore")

최초 초기화는 신뢰할 수 있는 머신 한 대에서 단 한 번만 실행한다.

fastlane match appstore --readonly false

이후 모든 클라우드 Mac에서 실행하는 가져오기 작업에는 --readonly true를 붙여서, 기존 인증서만 읽어오고 새로 생성하려 하지 않도록 한다.

fastlane match appstore --readonly true

배포용 계정에는 팀원 개인의 SSH 키를 클라우드 Mac에 잔뜩 넣는 대신, 읽기 전용 Git 배포 키(deploy key)를 따로 발급한다. 이렇게 하면 권한 경계가 명확해지고, 인원이 바뀌어도 개별적으로 취소하기만 하면 된다.

헤드리스 원격 세션에서 Keychain 비밀번호 없이 잠금 해제하기

클라우드 Mac은 대부분 SSH나 VNC로 원격 로그인하며, 본인이 실제로 화면 앞에 앉아 비밀번호를 입력하는 상황이 아니다. 그래서 시스템 기본 로그인 Keychain은 세션 사이에 자주 잠긴 상태가 되고, codesign을 실행하면 인증 대화상자가 튀어나온다—이는 무인으로 동작하는 CI 트리거 시나리오에서 그대로 멈춰버리는 결과를 낳는다.

해결 방법은 로그인 Keychain과 분리된 서명 전용 Keychain을 새로 만드는 것이다.

security create-keychain -p "$KEYCHAIN_PWD" signing.keychain
security set-keychain-settings -lut 21600 signing.keychain
security unlock-keychain -p "$KEYCHAIN_PWD" signing.keychain
security import cert.p12 -k signing.keychain -P "$P12_PWD" -T /usr/bin/codesign
security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PWD" signing.keychain
list=$(security list-keychains -d user | tr -d '"')
security list-keychains -d user -s signing.keychain $list

이 중 set-key-partition-list 단계는 빠뜨리기 쉽다. 이 단계를 빠뜨리면 Keychain이 이미 잠금 해제된 상태여도 codesign은 여전히 승인을 요구하는 대화상자를 띄운다. 이 전용 Keychain에는 서명에 필요한 인증서만 담아두고 일상적인 비밀번호와 섞어두지 않는 것이 좋다. 대여를 종료하거나 프로젝트를 넘길 때는 이 파일 하나만 삭제하면 되므로, 기본 Keychain을 정리하는 것보다 훨씬 깔끔하다.

CI 트리거 이후 인증서 가져오기와 정리

자동화 흐름은 다음 순서로 실행하는 것을 권장한다. 각 단계가 실패하면 파이프라인이 그대로 멈춰야 하며, 계속 다음 단계로 진행해서는 안 된다.

클라우드 Mac이 일 단위로 대여되어 사용 후 다른 작업으로 넘겨지거나 기간 만료로 회수되는 방식이라면, 마지막 정리 단계가 특히 중요하다. 전용 서명 Keychain, 임시로 다운로드한 p12, ~/Library/MobileDevice/Provisioning Profiles 안의 프로비저닝 프로파일은 작업 종료 시 함께 삭제하는 것을 권장한다. 다음 대여 기간에 자동으로 깨끗한 환경이 이어질 것이라고 기대해서는 안 된다. 구체적인 기종과 노드가 팀의 병렬 빌드 요구를 충족하는지는 콘솔에서 현재 선택 가능한 구성을 확인한 뒤 일정을 잡는 것을 권장한다. 칩 종류에 따른 컴파일 속도 차이는 여러 사람이 순서를 기다리는 시간에 직접적인 영향을 준다.

팀 협업과 권한 경계

역할을 명확히 나누어 두면 이후 문제 해결에 드는 시간을 크게 줄일 수 있다.

• 인증서 쓰기 권한: 오직 한 사람이나 하나의 초기화 파이프라인에만 부여한다. 일상적인 팀원과 클라우드 Mac의 자동화 계정은 모두 --readonly true를 사용한다.
• 저장소 접근 권한: 인증서 저장소는 개인 계정 키가 아니라 배포 키를 사용해서, 사람 단위·머신 단위로 개별 폐기할 수 있게 한다.
• 로컬 Keychain 격리: 사용자별, 또는 병렬 빌드 라인별로 독립된 Keychain 파일과 독립된 빌드 디렉터리를 배정해, 기본 Keychain을 서로 덮어쓰지 않도록 한다.
• 비밀번호와 토큰 보관: KEYCHAIN_PWD, P12_PWD, Git 배포 키는 모두 환경 변수나 CI의 암호화 변수를 통해 주입하고, 스크립트 파일 자체에는 적어두지 않는다.

배포 전 체크리스트

• [ ] Matchfile이 프라이빗 저장소를 가리키고 있으며, 팀 내 누구도 공개 저장소에 인증서 이력을 남긴 적이 없는지 확인
• [ ] 클라우드 Mac에서 실행하는 모든 match 명령에 --readonly true가 붙어 있는지 확인
• [ ] 전용 서명 Keychain에 set-key-partition-list를 실행했고, codesign이 더 이상 대화상자를 띄우지 않는지 확인
• [ ] 병렬로 작업하는 사용자/빌드 라인마다 독립된 Keychain 파일과 빌드 디렉터리가 있는지 확인
• [ ] 작업 또는 대여 기간 종료 전에 전용 Keychain과 임시 프로비저닝 프로파일을 삭제하는 정리 스크립트가 있는지 확인

인증서 관리와 Keychain 잠금 해제라는 두 가지 일을 분리해서 처리하면, 팀이 같은 클라우드 Mac에서 교대로 빌드를 만들어도 서로 발을 밟는 사고는 기본적으로 사라진다. 새 팀원이 프로젝트에 합류할 때도 저장소를 한 번 가져와서 읽기 전용 명령을 한 번 실행하면 되고, 인증서를 새로 신청할 필요가 없다.

자주 묻는 질문