Apple은 코드 서명 정체성을 인증서와 그에 대응하는 개인 키의 2개 요소로 설명합니다. Apple의 서명 인증서 동기화 안내처럼 인증서 파일만 내려받았다고 빌드 환경이 완성되는 것은 아닙니다. 따라서 새 프로젝트는 fastlane match를 바로 적용할 수 있지만, 운영 중인 앱은 기존 서명 자산을 먼저 가져오고 이중 검증해야 합니다. CI에서는 임시 키체인과 읽기 전용 동기화를 기본값으로 삼고, 발급·갱신 권한은 통제된 관리 작업에만 남겨야 합니다.

이 글은 iOS 또는 macOS 자동 서명 파이프라인을 관리하며 개인 Mac 의존성을 줄이려는 DevOps 엔지니어를 위한 안내서입니다. 인증서, 개인 키, 프로비저닝 프로파일과 배포 권한을 관리하는 서명 담당자, 장기 빌드 노드로 원격 Mac을 준비하는 개발 책임자도 대상입니다.

시작 전에 서명 자산의 범위를 고정합니다

fastlane match를 설정하기 전에 먼저 앱과 팀의 경계를 문서화해야 합니다. 다음 값은 실제 정보 대신 저장소와 설정 파일에서 확인할 수 있는 자리표시자를 사용합니다.

  • 팀 식별자: <TEAM_ID>
  • 앱 식별자: <BUNDLE_ID>
  • 서명 저장소: <SIGNING_REPOSITORY>
  • 저장소 분기: <TEAM_BRANCH>
  • 암호 해독 값: <MATCH_PASSWORD>
  • 배포 토큰: <RELEASE_TOKEN>

인증서 이름, 저장소 주소, 암호, 토큰과 로컬 경로를 문서나 예제에 실제 값으로 적으면 안 됩니다. 특히 로그에 환경 변수가 출력되지 않는지 확인해야 합니다.

새 프로젝트라면 개발, 등록 기기용 배포, 앱 스토어 배포를 분리해서 검토합니다. macOS 앱은 별도의 배포 서명 흐름이 필요할 수 있으므로 macOS 앱 배포 서명에 관한 공식 설명도 함께 대조해야 합니다.

각 항목은 다음처럼 확인합니다.

  • 주 앱의 <BUNDLE_ID>가 실제 타깃과 일치하는지 확인합니다.
  • 위젯, 확장 기능, 워치 앱 등 부속 타깃에도 별도 식별자와 프로파일이 필요한지 확인합니다.
  • 개발, 테스트 배포, 앱 스토어 배포에 필요한 서명 종류를 구분합니다.
  • 해당 팀의 발급 권한을 누가 보유하고, 암호 해독 값을 누가 관리할지 정합니다.
  • 새 원격 Mac에서 파일을 내려받은 뒤 실제로 서명된 빌드와 설치까지 가능한지 기준으로 삼습니다.

새 프로젝트는 match로 기준선을 만듭니다

새 프로젝트에는 match 저장소를 처음부터 서명 자산의 기준점으로 사용할 수 있습니다. 공식 문서는 Git과 객체 저장소를 통한 보관, 기존 인증서 가져오기, CI 읽기 전용 사용을 지원하는 방식으로 설명합니다. match 공식 문서의 현재 명령과 인증 방식을 먼저 확인한 뒤 설정해야 합니다.

초기화 흐름은 다음 순서가 안전합니다.

  1. <SIGNING_REPOSITORY>를 새 비공개 저장소 또는 승인된 객체 저장소로 만듭니다.
  2. <TEAM_ID>와 각 <BUNDLE_ID>를 구분해 Appfile과 Fastfile에 자리표시자로 기록합니다.
  3. 개발용 서명부터 생성하고, 테스트 배포와 앱 스토어 배포를 별도로 확인합니다.
  4. 암호 해독 값은 저장소 접근 자격 증명과 분리해 비밀 저장소에 넣습니다.
  5. 원격 Mac에서 동기화, 빌드, 서명 확인, 설치를 차례로 실행합니다.

완료 기준은 인증서나 프로파일의 다운로드 성공이 아닙니다. 동일한 커밋으로 원격 Mac에서 아카이브를 만들고, 서명된 결과물을 대상 기기 또는 승인된 배포 경로에서 검증해야 합니다. Xcode 프로젝트의 자동 서명 설정이 남아 있으면 match가 관리하는 자산과 충돌할 수 있으므로 타깃별 설정도 함께 확인합니다.

기존 서명은 가져온 뒤 이중 검증합니다

운영 중인 앱에서 fastlane match로 이전할 때는 match nuke부터 실행하면 안 됩니다. 기존 인증서를 철회하면 다른 빌드 노드와 배포 작업까지 영향을 받을 수 있습니다. Apple은 인증서와 개인 키가 함께 있어야 서명 정체성이 구성된다고 설명하므로, 기존 Mac에 인증서만 있는지 개인 키까지 있는지 먼저 확인해야 합니다.

기존 자산 목록에는 다음 내용을 포함합니다.

  • 현재 사용 중인 개발 및 배포 인증서
  • 각 인증서에 대응하는 개인 키
  • 주 앱과 부속 타깃의 프로비저닝 프로파일
  • 현재 아카이브와 배포를 담당하는 계정 및 작업
  • 인증서 만료 시점과 갱신 책임자
  • 기존 릴리스로 되돌아갈 수 있는 저장소, 아카이브와 배포 경로

그다음 별도의 저장소 분기 또는 격리된 저장소에서 match import를 시험합니다. 기존 인증서 가져오기 절차에 맞춰 인증서와 개인 키를 함께 보관하고, 원격 Mac에서 새로 내려받은 자산으로 같은 커밋을 빌드합니다.

이전 기간에는 다음 두 경로를 동시에 보존합니다.

  • 기존 개인 Mac 또는 기존 빌드 노드에서 수행하는 배포 경로
  • 새 원격 Mac에서 수행하는 match 기반 경로

두 경로의 아카이브, 서명 결과와 설치 또는 배포 결과를 비교한 뒤에만 운영 전환을 결정합니다. 기존 경로가 더 이상 필요 없다는 판단이 서고 백업과 복구 입구가 확인된 경우에만 파괴적 정리 작업을 검토합니다. 철회, 삭제와 저장소 재설정은 영향 범위와 되돌리기 방법이 문서화되지 않았다면 실행하지 않습니다.

여러 앱과 팀은 저장소와 분기를 분리합니다

하나의 팀 안에서는 인증서를 여러 앱에서 재사용할 수 있는 범위가 있지만, 프로비저닝 프로파일은 앱 식별자와 타깃에 따라 따로 관리해야 합니다. 주 앱의 성공만으로는 CI 코드 서명이 완료되지 않습니다. 확장 기능이나 위젯이 실패하면 전체 아카이브가 배포 단계에서 중단될 수 있습니다.

다음 기준으로 분리합니다.

  • 같은 Apple 팀의 여러 앱: 공통 인증서 재사용 가능 여부를 확인하되, 앱별 프로파일과 부속 타깃은 별도로 검증합니다.
  • 서로 다른 Apple 팀: <TEAM_BRANCH_A>, <TEAM_BRANCH_B>처럼 독립 분기 또는 독립 저장소를 사용합니다.
  • 서로 다른 보안 책임자: 저장소 접근 권한과 암호 해독 값을 분리합니다.
  • 개발과 정식 배포: 작업 계정, 작업 공간과 키체인을 나눕니다.

팀 설정은 Appfile에 실제 계정 정보를 넣기보다 자리표시자로 관리합니다. Appfile의 팀 설정 문서를 기준으로 팀 식별자를 확인하고, 로그에 다른 팀의 앱 식별자나 저장소 경로가 노출되지 않는지 점검합니다.

fastlane match 원격 Mac CI는 임시 키체인으로 격리합니다

원격 Mac CI에서 setup_ci를 사용하는 이유는 빌드 작업이 로그인 사용자의 기본 키체인과 무관하게 실행되도록 만들기 위해서입니다. 공식 문서의 setup_ci 동작과 CI 설정에 따라 임시 키체인을 만들고, 인증 자산을 동기화한 뒤 빌드가 그 키체인을 사용하도록 연결합니다.

권장 순서는 다음과 같습니다.

  1. CI 작업 전용 계정과 작업 공간을 준비합니다.
  2. setup_ci로 임시 키체인을 생성합니다.
  3. 저장소 접근 자격 증명을 주입합니다.
  4. <MATCH_PASSWORD>를 별도로 주입합니다.
  5. match로 인증서와 프로파일을 읽기 전용으로 동기화합니다.
  6. Xcode 빌드와 아카이브를 실행합니다.
  7. 로그에서 키체인 확인 창, 이중 인증 대기, 그래픽 대화 상자를 확인합니다.
  8. 작업 종료 뒤 임시 키체인과 작업 공간에 자산이 남지 않았는지 확인합니다.

서명 저장소 자격 증명, 암호 해독 값, Apple 서비스 인증과 배포 토큰은 하나의 고권한 키로 합치지 않습니다. readonly 모드는 기존 자산을 사용하는 빌드와 테스트, 아카이브 작업에 적용합니다. 인증서 발급이나 프로파일 갱신이 필요한 작업만 승인된 관리 흐름에서 별도로 실행합니다.

readonly를 켜야 하는 작업과 예외

읽기 전용 모드는 다음 작업에 적합합니다.

  • 모든 풀 리퀘스트 검증 빌드
  • 동일한 커밋의 테스트 아카이브
  • 정식 배포 직전의 재현 빌드
  • 여러 작업자가 공유하는 원격 Mac의 일반 CI 작업

반대로 새 프로젝트의 최초 자산 생성이나 승인된 인증서 갱신 작업에서는 쓰기 권한이 필요할 수 있습니다. 이 작업을 일반 빌드에 섞으면 병렬 작업이 저장소 상태를 바꾸거나, 만료된 프로파일을 예기치 않게 교체할 수 있습니다.

공유 노드는 두 개의 격리 작업으로 검증합니다

장기 원격 Mac은 재시작, 사용자 세션 변경과 병렬 작업을 고려해야 합니다. 임시 키체인이 특정 로그인 세션에만 연결되어 있거나, 이전 작업의 프로파일이 작업 공간에 남아 있으면 다음 작업이 잘못된 서명 자산을 사용할 수 있습니다.

운영 전에는 최소한 다음 시험을 수행합니다.

  • 개발용 앱과 테스트용 앱을 서로 다른 작업 공간에서 실행합니다.
  • 두 작업을 동시에 실행하거나 한 작업이 끝난 직후 다른 작업을 실행합니다.
  • 각 작업이 예상한 <BUNDLE_ID>와 <TEAM_ID>를 사용했는지 로그에서 확인합니다.
  • 한 작업의 키체인, 프로파일과 환경 변수가 다른 작업에서 보이지 않는지 확인합니다.
  • 원격 Mac을 재시작한 뒤 다시 동기화하고 아카이브를 만듭니다.
  • 작업 종료 후 임시 키체인, 파생 데이터와 비밀 환경 변수가 남지 않았는지 확인합니다.

이 과정에서 개인 Mac에서는 성공하지만 원격 Mac에서는 개인 키를 찾지 못하는 상황이 자주 드러납니다. 원인은 인증서 파일만 복사했거나, 다른 사용자 세션의 키체인을 참조하거나, CI가 그래픽 확인을 기다리는 경우일 수 있습니다. 따라서 macOS Keychain 상태를 파일 존재 여부가 아니라 실제 서명 작업으로 확인해야 합니다.

운영 전 서명 이전 판정 체크리스트

아래 항목을 모두 확인한 뒤 결론을 선택합니다.

  • [ ] 기존 인증서와 대응하는 개인 키를 모두 식별했습니다.
  • [ ] 주 앱, 위젯, 확장 기능과 워치 앱의 <BUNDLE_ID>를 분리해 확인했습니다.
  • [ ] 개발, 테스트 배포와 정식 배포에 필요한 서명 종류를 구분했습니다.
  • [ ] 기존 서명 경로의 백업 아카이브와 복구 방법을 보관했습니다.
  • [ ] match import를 격리된 저장소 또는 분기에서 시험했습니다.
  • [ ] 원격 Mac에서 setup_ci와 임시 키체인을 사용했습니다.
  • [ ] 일반 CI 작업에서 readonly 동기화를 적용했습니다.
  • [ ] 저장소 자격 증명, 암호 해독 값과 배포 토큰을 서로 분리했습니다.
  • [ ] 재시작 후에도 동기화, 아카이브와 서명 검증이 재현됩니다.
  • [ ] 병렬 또는 연속 작업에서 다른 앱의 자산이 섞이지 않습니다.
  • [ ] 동일한 커밋으로 기존 경로와 원격 경로의 결과를 비교했습니다.
  • [ ] 키체인 확인 창이나 이중 인증 대기 없이 비대화형 작업이 끝납니다.

판정은 다음 조건으로 나눕니다.

  • 모든 항목이 확인되면 직접 전환을 선택합니다.
  • 주 앱은 통과했지만 부속 타깃이나 복구 시험이 남아 있으면 이중 운영 유지를 선택합니다.
  • 개인 키가 없거나 권한이 합쳐져 있거나 비대화형 작업이 멈추면 전환 보류를 선택합니다.

운영 전환은 세 가지 결론 중 하나로 결정합니다

프로덕션 승인은 단일 빌드 성공으로 끝내지 않습니다. Apple의 배포 및 프로비저닝 절차와 프로파일 변경·재생성 기준을 함께 확인해야 합니다.

다음 선택 목록을 사용하면 전환 결정을 분명하게 만들 수 있습니다.

  • 직접 전환: 새 원격 Mac이 모든 타깃을 아카이브하고, 서명 검증과 설치 또는 배포 검증을 통과했으며, 재시작 후에도 복구되고, 기존 경로의 백업과 회귀 절차가 준비된 경우입니다.
  • 이중 운영 유지: 주 앱은 통과했지만 위젯, 확장 기능, 워치 앱 또는 배포 토큰 중 하나라도 재현되지 않는 경우입니다. 기존 경로를 유지한 채 실패 원인을 분리합니다.
  • 전환 보류: 개인 키를 복구할 수 없거나, 저장소 접근과 암호 관리가 분리되지 않았거나, 비대화형 작업이 확인 창에서 멈추는 경우입니다. 먼저 자산 복구와 권한 재설계를 완료합니다.

인증서 만료, 프로파일 변경, 암호 교체, 원격 노드 교체와 저장소 장애마다 담당자를 지정해야 합니다. 새 노드에 자산을 다시 내려받는 절차뿐 아니라, 저장소가 잠시 unavailable한 상황에서 기존 배포를 중단할지 결정하는 기준도 문서에 포함해야 합니다.

원격 Mac을 운영 노드로 선택할 때의 조건

서명 자산을 정리한 뒤에는 원격 Mac이 실제 운영 조건을 충족하는지 별도로 확인해야 합니다. 장기 빌드나 배포 작업에는 재시작 후 복구, 완전한 관리 권한, 작업 계정 분리와 로그 수집이 필요합니다. 이런 조건을 먼저 시험하려면 RUVCLOUD의 한국어 원격 Mac 이용 안내에서 접근 방식과 관리 범위를 확인한 뒤, 비생산 인증서로 동기화와 아카이브를 재현하는 편이 안전합니다.

기존 개인 Mac은 즉시 확인하기 쉽지만, 한 사람의 로그인 세션과 키체인에 의존하고 재현 가능한 복구 절차가 부족할 수 있습니다. 사내 장비를 별도 서버로 운영하는 방식은 하드웨어 구매, 유지 관리와 원격 장애 대응 책임이 추가됩니다. 반면 RUVCLOUD의 원격 Mac은 임시 CI 노드나 테스트용 서명 환경을 먼저 구성하고, 재시작과 권한 격리를 검증한 뒤 정식 배포로 확대할 수 있습니다.

다만 장기간 동일한 고강도 작업을 계속 실행하거나 물리적인 기기 연결이 필수인 경우에는 자체 장비가 더 적합할 수 있습니다. 원격 Mac은 모든 상황의 대체재가 아니라, 개인 Mac 의존성을 줄이고 실제 macOS 환경에서 CI 서명과 복구 절차를 시험해야 할 때 선택하는 운영 수단입니다. 일반 빌드 작업은 읽기 전용으로 유지하고, RUVCLOUD의 원격 Mac 신청 경로에서 필요한 관리 권한과 접속 조건을 확인한 뒤 비생산 환경부터 시작하는 방식이 안정적입니다.