첫 iOS 빌드 파이프라인 만들기

호스트에 xcodes가 아직 설치되어 있지 않다면 팀에서 승인한 소프트웨어 설치 절차에 따라 먼저 준비하세요. 특정 버전을 설치할 때는 합법적으로 확보했으며 프로젝트 요구 사항에 맞는 로컬 Xcode 설치 패키지를 사용하세요. 아래의 XCODE_VERSION 과 XCODE_XIP 는 각각 확인된 버전 번호와 설치 패키지의 절대 경로를 나타냅니다. 설치 중 필요한 대화형 단계를 무인 빌드 작업에 넣지 마세요.

XCODE_APP 은 설치된 실제 앱 경로를 가리켜야 합니다. CI에서는 여러 작업이 시스템 전역 설정을 두고 충돌하지 않도록 작업 환경에서 DEVELOPER_DIR를 설정하는 것이 좋습니다. 시스템 기본 툴체인을 꼭 전환해야 한다면 다음 명령을 실행하세요: sudo xcode-select --switch "$XCODE_APP/Contents/Developer" 그런 다음 xcodebuild -version으로 다시 확인하세요.

선택한 Xcode를 처음 실행해 필요한 구성 요소를 준비하세요. 원격 연결로 그래픽 인터페이스를 조작할 수 있습니다. 그런 다음 Xcode의 구성 요소 설정에서 필요한 runtime을 설치하세요. xcrun simctl list devices available을 실행해 테스트 대상에 맞는 시뮬레이터를 선택하세요. 대화형으로 한 번 실행해 완전히 시작될 때까지 기다린 후 최소 테스트 작업을 실행합니다. 실제 기기용 아카이브 생성과 시뮬레이터 테스트는 서로 다른 단계입니다. runtime이 없다는 이유로 아카이브 툴체인 문제라고 잘못 판단하지 마세요.

CI 로그 앞부분에 툴체인 점검을 추가하세요. 최소한 Xcode 버전, SDK 목록, 커밋 ID를 출력해야 합니다. Xcode를 변경한 뒤에는 캐시 키를 새로 만들고 서드파티 의존성, 서명, 내보내기 절차를 검증하세요. runner 태그만 바꾸고 실제 도구 경로를 확인하지 않으면 빌드 환경의 일관성을 보장할 수 없습니다.

GitLab Runner: 태그와 실행기 함께 확인

프로젝트의 runner 설정에서 프로젝트 runner를 만들고 해당 인증 토큰을 준비한 다음, 다음 세 태그를 설정하세요: macos、arm64、ios-archive 。인스턴스 주소와 인증 토큰은 임시로 GITLAB_URL、GITLAB_RUNNER_TOKEN에 넣고 전용 빌드 사용자 계정으로 shell executor를 등록하세요. 작업을 마치면 임시 토큰 변수를 삭제합니다.

프로젝트 변수에 실제 IOS_WORKSPACE 와 IOS_SCHEME를 설정하고 다음 섹션의 서명 준비를 먼저 완료하세요. 여기서는 아카이브만 생성하며 내보내기나 업로드는 포함하지 않습니다. 산출물을 7일간 보관하는 설정은 예시이므로 팀의 보관 정책에 맞게 변경할 수 있습니다. 인증서, 개인 키 또는 임시 Keychain을 artifacts에 넣지 마세요.

GitHub Actions: runner 프로세스 하나당 작업 하나

저장소 설정에 안내된 runner 설치 단계에서 macOS ARM64용 프로그램을 받아 압축을 푼 디렉터리로 이동하세요. REPOSITORY_URL 에는 현재 저장소 주소를, RUNNER_TOKEN 에는 이번 등록에 사용할 토큰을 설정하세요. 작업이 잘못된 툴체인으로 라우팅되지 않도록 등록 설정과 워크플로 모두에 태그를 넣어야 합니다.

저장소 변수에 도구 경로, workspace, scheme을 먼저 설정하세요. 이 예시는 환경을 먼저 검증하기 쉽도록 수동 실행을 사용합니다. 서명 인증 정보가 있는 runner를 신뢰할 수 없는 외부 코드에 바로 노출하지 마세요. runner 프로세스 하나는 한 번에 한 작업만 처리하며, concurrency 는 같은 그룹의 워크플로 실행도 제한합니다. 이는 호스트 수준의 리소스 한도가 아닙니다.

검증이 끝나면 다운로드한 프로그램에서 제공하는 서비스 스크립트로 상시 실행을 설정하고, 서비스 사용자와 수동 테스트 사용자가 같은지 확인하세요. 한 사용자 계정에서 서명을 준비하고 다른 사용자 계정으로 서비스를 실행하면 대화형 빌드는 성공하지만 CI에서 인증서나 프로비저닝 프로파일을 찾지 못하는 문제가 흔히 발생합니다.

자동화 작업에는 별도의 빌드 Keychain을 사용하고, CI의 보호된 비밀 변수로 비밀번호를 전달하세요. 인증서를 가져온 뒤 꼭 필요한 서명 도구에만 접근 권한을 부여하고 모든 앱이 개인 키에 접근하도록 허용하지 마세요. 아래 점검 명령은 현재 사용자가 유효한 서명 ID를 확인할 수 있는지 확인합니다. 프로비저닝 프로파일, 내보내기 설정, 프로젝트 설정이 모두 일치함을 보장하지는 않습니다.

Xcode 버전에 따라 프로비저닝 프로파일 경로가 다를 수 있으므로 현재 툴체인이 실제로 읽는 경로를 확인하세요. 가져온 후 유효 기간, 앱 식별자, 서명 유형을 점검합니다. 아카이브는 성공했지만 내보내기에 실패한다면 Xcode를 반복 설치하는 대신 내보내기 설정의 방식, 팀 식별자, 프로비저닝 프로파일 매핑을 중점적으로 확인하세요.

팀에서 이미 fastlane match를 사용 중이라면 기존 암호화 인증서 저장소와 접근 정책을 그대로 따르세요. 검증 단계에서는 bundle exec fastlane match appstore --readonly를 사용해 기존 서명 자료를 먼저 읽고 빌드 노드가 팀 인증서를 실수로 수정하지 않도록 하세요. 저장소 접근 자격 증명, 복호화 비밀번호, Keychain 비밀번호는 각각 별도로 관리하세요. 프로덕션 서명 변수는 보호된 브랜치 또는 제어된 수동 작업에만 공개합니다.

작업이 끝나면 임시 파일을 삭제하고 임시 Keychain을 잠그세요. 로그에는 필요한 오류 코드와 단계 결과만 남기고 개인 키 내용, 인증서 비밀번호, 등록 토큰, 비밀 변수 전체 값을 출력하지 마세요. 전용 물리 머신으로 리소스를 분리하더라도 프로젝트 자격 증명에는 최소 권한 원칙을 적용해야 합니다.

실행하세요: diskutil list 및 df -h로 용량과 마운트 지점을 확인하세요. 알 수 없는 디스크에 지우기나 파티션 명령을 실행하지 마세요. 빌드 사용자에게 쓰기 권한이 있는 캐시 디렉터리를 만들고 작은 파일로 읽기·쓰기를 테스트하세요. 재시작 후에도 마운트가 정상 작동하는지 확인한 뒤 상시 실행 runner에서 새 경로를 사용하세요.

이전하기 전에 새 작업을 받지 않도록 하고 진행 중인 아카이브와 서명 작업이 끝날 때까지 기다리세요. DerivedData는 다시 만들 수 있는 캐시이므로 쓰기 중일 수 있는 기존 캐시를 복사하기보다 새 위치에서 다시 생성하는 것이 좋습니다. 아래에서는 명시적으로 -derivedDataPath를 지정하므로 사용자 디렉터리 전체를 확장 볼륨으로 옮길 필요가 없습니다.

실행 전에 BUILD_VOLUME 을 쓰기 가능한 것으로 확인된 마운트 디렉터리로 설정하세요. CACHE_KEY 는 저장소, Xcode 버전, 빌드 구성을 구분해야 합니다. BUILD_ID 에는 현재 작업의 고유 ID를 사용해 작업 간 아카이브가 덮어쓰이지 않게 하세요. 동시에 실행되는 작업은 같은 쓰기 가능한 DerivedData 디렉터리를 공유하지 마세요.

먼저 캐시 없이 빌드를 한 번 완료한 뒤 후속 작업의 캐시 적중 여부와 디스크 증가량을 관찰하세요. 아카이브, 시뮬레이터 데이터, 의존성 캐시에 각각 보관 정책을 설정하고 삭제 전에 사용 중인 작업이 없는지 확인하세요. 빌드 산출물은 팀이 관리하는 별도 저장소에 보관해야 하며 호스트 캐시를 유일한 백업으로 삼지 마세요. 대여 기간이 끝나기 전에 내보내고 백업을 읽을 수 있는지 검증하세요.