갈피노트
Back to Home
iOS Development • 2025년 12월 22일

xcode cloud를 이제야 써보려고 한다.

#Xcode Cloud #iOS #Swift #CI/CD #DevOps #TestFlight #ci_scripts #앱개발 #자동배포 #Xcode

간단한 소개.


Xcode Cloud는 애플이 개발자들을 위해 만든 CI/CD(지속적 통합 및 배포) 서비스입니다.

쉽게 말해, "내 컴퓨터 대신 애플의 슈퍼 컴퓨터가 앱을 빌드하고, 테스트하고, 배포까지 해주는 비서"라고 생각하면 됩니다.

주요 특징을 간단히 정리해 드릴게요.

1. 주요 기능

  • 자동 빌드: 코드를 작성해서 저장소(Git)에 올리면(Push), Xcode Cloud가 자동으로 감지해서 앱을 빌드합니다. 내 맥북이 뜨거워질 일이 줄어듭니다.

  • 자동 테스트: 여러 기기(아이폰, 아이패드 등) 시뮬레이션 환경에서 자동으로 테스트를 돌려 오류가 없는지 확인해 줍니다.

  • 배포 자동화: 빌드와 테스트가 성공하면, 테스터들이 쓸 수 있게 TestFlight에 올리거나, App Store 심사 제출용으로 바로 보낼 수 있습니다.

2. 장점

  • Xcode와의 통합: 별도의 복잡한 프로그램(Jenkins, Fastlane 등)을 설치하거나 설정할 필요 없이, Xcode 프로그램 안에서 바로 설정하고 결과를 볼 수 있습니다.

  • 맥북 자원 절약: 빌드하는 동안 내 컴퓨터의 성능을 잡아먹지 않으니, 빌드가 돌아가는 동안 다른 작업을 쾌적하게 할 수 있습니다.

3. 가격

  • 구독형: 매달 사용할 수 있는 '컴퓨팅 시간(시간)'에 따라 요금을 냅니다.

  • 현재 애플 개발자 프로그램 멤버십이 있다면 월 25시간까지는 무료로 제공됩니다. (소규모 앱이나 개인 개발자에게는 충분한 시간입니다.)

요약하자면: 개발자가 코딩만 하면, "빌드 -> 테스트 -> 배포"로 이어지는 귀찮은 반복 작업을 애플 서버가 대신 알아서 처리해 주는 편리한 도구입니다.

설정해보기


"GitHub에 코드를 올리면 자동으로 TestFlight 배포까지 되게 하는 설정"을 기준으로 설명해 드릴게요.

🚩 시작 전 준비물

  1. Apple Developer Program 멤버십 (유료 계정 필요)

  2. Git 저장소: 프로젝트가 GitHub, GitLab, 또는 Bitbucket 같은 원격 저장소에 올라가 있어야 합니다.

1단계: 워크플로우(Workflow) 생성

Xcode 메뉴바에서 [Product] -> [Xcode Cloud] -> [Create Workflow...]를 클릭합니다.

  • Workflow란? "언제 빌드하고, 무엇을 할지" 정하는 규칙입니다. (예: main 브랜치에 코드가 올라오면 -> 빌드해서 -> TestFlight에 올려라)

2단계: 기본 설정 확인

화면에 나오는 설정 창에서 'Default'를 선택하고 Next를 누릅니다. 애플이 가장 많이 쓰는 설정을 미리 세팅해 두었습니다.

  • 설정 세부 내용 (필요하면 수정 가능):

    • Start Condition (시작 조건): 보통 Branch Changes로 되어 있습니다. (Git의 main 브랜치에 코드가 변경되면 시작한다는 뜻)

    • Actions (동작): Archive (앱을 빌드해서 포장함)가 기본입니다.

    • Post-Actions (후속 동작): TestFlight Internal Testing (내부 테스터에게 배포)이 기본으로 잡혀 있습니다.

3단계: 소스 코드 권한 허용 (가장 중요!)

Next를 계속 누르다 보면 "Grant Access to Your Source Code" 버튼이 나옵니다.

  1. 이 버튼을 누르면 웹브라우저(App Store Connect)가 열립니다.

  2. 사용 중인 Git 서비스(GitHub 등)와 연동(Link) 버튼을 누르세요.

  3. 로그인을 하고 권한을 허용해주면, Xcode Cloud가 내 코드를 가져갈 수 있게 됩니다.

4단계: 첫 빌드 시작!

연동이 끝나고 Xcode로 돌아오면 설정이 완료됩니다. "Start Build" 버튼을 눌러보세요.

  • 이제 왼쪽 네비게이터의 마지막 탭(Report Navigator)에서 구름 모양 아이콘을 누르면, 애플 서버에서 내 앱이 빌드되는 과정을 실시간으로 볼 수 있습니다.

💡 팁

  • 성공하면? 잠시 후 내 폰의 TestFlight 앱으로 "새 버전이 업데이트되었습니다"라는 알림이 옵니다.

  • 실패하면? Report Navigator에서 빨간색 아이콘을 눌러보세요. 어떤 코드 때문에 에러가 났는지 로그를 보여줍니다.

사내망에서도 가능한가?

회사 내부 서버(On-premise)에 구축된 Git이라도 Xcode Cloud와 연동할 수 있습니다.

다만, "내부망"에 있기 때문에 애플 서버가 회사 서버에 접속할 수 있도록 길을 터주는 작업이 반드시 필요합니다.

1. 지원하는 내부 서버 종류

애플은 공식적으로 다음 3가지 자체 구축형(Self-Managed) 서버를 지원합니다.

  • GitHub Enterprise

  • GitLab Self-Managed

  • Bitbucket Server

2. 필수 조건 (가장 중요 ⭐️)

회사 서버가 외부 인터넷과 완전히 차단된 폐쇄망(Intranet)에 있다면 바로 연결할 수 없습니다. 회사 보안팀(또는 인프라팀)에 요청하여 아래 조치를 취해야 합니다.

  1. 방화벽 오픈: 애플의 Xcode Cloud 서버들이 회사 Git 서버에 접근할 수 있도록 특정 IP 대역을 허용(Allowlist)해야 합니다.

    • 애플이 사용하는 IP 대역: 192.168.x.x 같은 내부 IP가 아니라, 애플이 문서에 명시한 공인 IP 대역(예: 17.58.0.0/18 등)을 열어줘야 합니다.

  2. 공인 접속 주소: 회사 Git 서버가 외부에서 접속 가능한 도메인이나 공인 IP를 가지고 있어야 합니다. (VPN을 통해서만 접속 가능한 경우에는 연결이 불가능합니다.)

3. 연결 방식

일반적인 클라우드 Git(GitHub.com 등)과 달리, 조금 더 절차가 있습니다.

  1. Xcode Cloud 설정 중: 소스 코드 권한 부여 단계에서 "GitHub Enterprise" 등을 선택하고, 회사 Git 서버의 주소(URL)를 입력합니다.

  2. 앱 등록: 회사 Git 서버 관리자 페이지에서 Xcode Cloud를 위한 'GitHub App' (또는 Application)을 생성하여 연동하는 과정이 필요합니다.

요약하자면: 기술적으로는 가능하지만, 보안팀의 협조(방화벽 해제)가 없으면 불가능합니다.

어떻게 하면 Xcode cloud를 잘 사용할 수 있을까?

Xcode Cloud를 그저 '자동 빌드 도구'가 아니라, 팀의 개발 속도를 높이고 실수를 없애는 핵심 엔진으로 활용하기 위한 5가지 핵심 전략(Best Practices)을 정리해 드립니다.

단순히 켜두는 것을 넘어 "가장 잘" 쓰기 위한 방법들입니다.

1. 워크플로우(Workflow)를 목적별로 쪼개기

모든 커밋마다 똑같은 무거운 빌드를 돌리는 것은 비효율적입니다. 워크플로우를 3단계로 나누는 것이 정석입니다.

  • ① PR 검증용 (Pull Request):

    • 목표: 코드 리뷰 전에 기본적인 에러가 없는지 확인.

    • 설정: 빌드 + 유닛 테스트(Unit Test)만 수행. (아카이브 X, 배포 X)

    • 효과: 빠르게 피드백을 받아 수정 시간을 단축합니다.

  • ② 야간/주간 빌드 (Nightly/Main):

    • 목표: 팀 내부 QA용 버전 배포.

    • 설정: 메인 브랜치 병합 시 실행. 빌드 + UI 테스트 + TestFlight(내부 팀원) 배포.

    • 효과: 기획자나 테스터가 항상 최신 버전을 폰에 깔아볼 수 있습니다.

  • ③ 출시용 (Release):

    • 목표: 스토어 심사 제출.

    • 설정: 'Release' 태그가 달릴 때 실행. App Store Connect로 빌드 전송.

2. ci_scripts의 마법 활용하기 (핵심 ⭐️)

Xcode Cloud의 진정한 힘은 커스텀 스크립트에서 나옵니다. 프로젝트 폴더 안에 ci_scripts라는 폴더를 만들면, 특정 시점마다 내가 짠 쉘 스크립트(Shell Script)를 실행해 줍니다.

  • ci_post_clone.sh (가장 많이 씀): 애플 서버가 코드를 다운로드(Clone) 받은 직후에 실행됩니다.

    • 활용 예시 1: 회사 내부 서버의 보안 키나 API Key 파일 생성.

    • 활용 예시 2: CocoaPods나 별도의 라이브러리 설치.

    • 활용 예시 3: 개발용(Dev)과 배포용(Prod)에 따라 앱 아이콘이나 이름을 자동으로 바꿔치기.

3. 환경 변수(Environment Variables)로 보안 지키기

소스 코드에 API Key나 비밀번호를 절대 하드코딩해서 올리면 안 됩니다.

  • 방법: Xcode Cloud 설정 메뉴의 Environment 탭에 비밀 값을 저장합니다. (예: MY_API_KEY)

  • 사용: 위에서 말한 ci_scripts에서 이 값을 불러와서 앱 빌드 전에 주입합니다. 이렇게 하면 코드가 유출되어도 비밀번호는 안전합니다.

4. 테스트 병렬화 (Parallel Testing) 켜기

테스트, 특히 UI 테스트는 시간이 오래 걸립니다. Xcode Cloud는 애플의 빵빵한 서버 자원을 씁니다.

  • 설정: 테스트 액션 설정에서 "Execute in parallel" 옵션을 켜세요.

  • 효과: 여러 대의 가상 아이폰이 동시에 테스트를 나눠서 수행하여, 30분 걸릴 테스트를 10분 만에 끝낼 수 있습니다.

5. 슬랙(Slack) 연동으로 멍 때리는 시간 줄이기

빌드가 끝날 때까지 기다리지 마세요.

  • 설정: 워크플로우 설정에 Post-Actions를 추가하여 Slack이나 이메일 알림을 연결합니다.

  • 효과: "빌드 실패" 알림이 오면 그때 가서 확인하면 됩니다. 성공하면 팀원들에게 "테스트 버전 올라왔으니 확인 부탁드려요"라고 자동으로 알릴 수 있습니다.

요약하자면

Xcode Cloud를 200% 활용하는 공식은 다음과 같습니다.

"단순 빌드는 빠르게(PR) + 중요 배포는 꼼꼼하게(Main) + 비밀 정보는 스크립트로 안전하게(ci_scripts)"

개발자들이 가장 어려워하면서도, 한번 해두면 가장 편해지는 게 ci_scripts (커스텀 스크립트) 부분입니다.

가장 많이 사용하는 패턴인 **"Xcode Cloud 환경 변수에 저장된 API 키를 가져와서, 빌드 직전에 Secrets.swift라는 파일을 만들어주는 스크립트"**를 보여드릴게요.

이 방식을 쓰면 Git에는 껍데기 파일만 올리고, 실제 비밀 키는 서버에서만 주입되므로 보안상 매우 안전합니다.

1단계: 폴더 및 파일 만들기

먼저 프로젝트 루트 폴더( .xcodeproj 파일이 있는 곳과 같은 레벨)에 ci_scripts라는 이름의 폴더를 만들고, 그 안에 ci_post_clone.sh 파일을 만듭니다.

Plaintext

MyProject/
├── MyProject.xcodeproj
├── MyProject/ (소스 코드 폴더)
│   ├── AppDelegate.swift
│   └── ...
└── ci_scripts/  <-- 폴더 생성
    └── ci_post_clone.sh  <-- 파일 생성

2단계: Xcode Cloud에서 변수 설정

Xcode Cloud 워크플로우 설정 화면의 Environment 탭으로 가서 변수를 추가합니다.

  • Name: MY_API_KEY

  • Value: a1b2c3d4... (실제 API 키 값)

  • Secret: 체크 (체크하면 화면에서 가려집니다)

3단계: 스크립트 작성 (ci_post_clone.sh)

이제 ci_post_clone.sh 파일을 열고 아래 코드를 복사해서 넣으세요. 이 스크립트는 소스 코드가 다운로드(Clone)된 직후 실행되어, 가짜 파일이 있던 자리에 진짜 키가 담긴 파일을 덮어씁니다.

Bash

#!/bin/sh


설명을 위한 주석:


이 스크립트는 Xcode Cloud가 저장소를 Clone 한 직후 실행됩니다.


환경 변수에 저장된 $MY_API_KEY 값을 읽어서 Secrets.swift 파일을 생성합니다.


1. 소스 코드가 있는 위치로 이동 (CI_PRIMARY_REPOSITORY_PATH는 Xcode Cloud 기본 경로 변수)


cd "$CI_PRIMARY_REPOSITORY_PATH"


2. 파일이 생성될 위치 지정 (프로젝트 구조에 맞게 수정 필요)


예: MyProject 폴더 안에 Secrets.swift를 생성


TARGET_FILE_PATH="./MyProject/Secrets.swift"


echo "📍 Secrets.swift 파일 생성을 시작합니다..."


3. Swift 파일 내용 작성 (cat 명령어로 파일 덮어쓰기)


EOM 사이의 내용이 파일로 저장됩니다.


cat > "$TARGET_FILE_PATH" << EOM
import Foundation


struct Secrets {
    static let apiKey = "$MY_API_KEY"
}
EOM


echo "✅ Secrets.swift 파일 생성이 완료되었습니다."
echo "내용 확인 (보안상 키 일부만 노출): $(cat "$TARGET_FILE_PATH" | grep "apiKey")"

4단계: 실행 권한 부여 (필수 ⭐️)

스크립트 파일은 만들었지만, 실행 권한이 없으면 Xcode Cloud에서 에러가 납니다. 터미널을 열고 ci_scripts 폴더로 이동해서 아래 명령어를 한 번 입력해 주세요.

Bash

chmod +x ci_post_clone.sh

(이 상태로 Git에 Push 하면 됩니다.)

5단계: 앱 코드에서 사용하기

이제 앱 코드(Swift)에서는 아주 평범하게 사용하면 됩니다.

Swift

// ViewController.swift


func fetchData() {
    // Xcode Cloud가 만들어준 Secrets 구조체에서 키를 꺼내 씀
    let key = Secrets.apiKey
    print("API Key 사용: (key)")
}

💡 주의할 점 (로컬 개발 환경)

위 스크립트는 Xcode Cloud 서버에서만 작동합니다. 내 컴퓨터(로컬)에서 개발할 때는 Secrets.swift 파일이 없어서 에러가 나겠죠?

그래서 로컬용으로 가짜(Dummy) Secrets.swift 파일을 하나 만들어서 Git에 올려두는 것이 좋습니다. (실제 키 대신 "DEV_KEY" 같은 걸 넣어서요.) Xcode Cloud가 돌 때만 이 파일이 진짜 키가 든 파일로 교체되는 원리입니다.

Comments