Buildkite Agent 원격 Mac은 어떻게 배포하나요? 2026 Xcode 27 CI 가이드

Buildkite Agent 원격 Mac 배포는 가능합니다. 다만 Xcode 27 베타 노드는 공식 요구 조건을 만족하는 Apple Silicon Mac에 격리하고, 명령줄 빌드부터 Simulator, 서명, 재시작 복구 순서로 실제 작업을 검증해야 합니다. 에이전트가 온라인으로 보이는 것만으로는 배포 완료가 아닙니다.

이 글은 다음 독자를 위한 안내입니다.

• 로컬 컴퓨터의 iOS 또는 macOS 빌드를 Buildkite로 옮기려는 개발자
• 원격 접속과 장기 실행이 필요한 macOS CI 노드를 관리하는 DevOps 엔지니어
• Xcode 27 베타를 격리 검증하면서 안정 버전 생산 환경을 유지하려는 플랫폼 담당자

먼저 확인할 사항: Apple이 공개한 Xcode 27 자료는 베타 도구 체인을 전제로 합니다. 따라서 안정 버전 빌드 노드를 즉시 교체하지 말고, 별도 원격 Mac과 별도 대기열에서 검증해야 합니다. Xcode 27 베타 릴리스 노트와 Xcode 시스템 요구 사항을 먼저 확인하세요.

SECTION 01 배포 당일 전에 노드의 역할을 분리합니다

원격 Mac은 단순한 명령 실행기가 아닙니다. Buildkite 제어 영역이 작업을 예약하고, Agent 프로세스가 작업을 받아 실행하며, 실제 Mac이 Xcode와 키체인, Simulator를 제공합니다. 이 세 요소를 한 덩어리로 관리하면 장애 원인을 찾기 어렵습니다.

Buildkite Agent는 외부 연결을 통해 작업을 받는 구조이므로, Agent를 위해 원격 Mac에 임의의 인바운드 포트를 추가로 열 필요가 없습니다. Buildkite의 자체 호스팅 Agent 동작 방식을 기준으로 네트워크 정책을 먼저 정하고, SSH나 화면 공유는 관리 목적에 한정합니다.

배포를 시작하기 전에 아래 세 가지 작업을 분류합니다.

• 명령줄 빌드: 의존성 복원, 컴파일, 단위 테스트, 결과 파일 생성
• 그래픽 작업: iOS Simulator 부팅과 UI 테스트
• 배포 작업: 인증서, 개인 키, 프로비저닝 프로파일을 이용한 서명과 업로드

첫 번째 노드는 명령줄 빌드만으로 시작하는 편이 안전합니다. Simulator와 서명은 사용자 세션과 보안 자산이라는 추가 조건이 있으므로, 첫 작업이 통과한 뒤 단계적으로 연결합니다.

SECTION 02 첫 시간에는 전용 계정과 대기열을 고정합니다

macOS 관리자 계정으로 Agent를 실행하면 저장소 작업이 서명 자산과 같은 권한 경계에 놓일 수 있습니다. Agent 전용 계정을 만들고, 일반 개발 작업에는 관리자 권한을 주지 않습니다. 설치 방법과 실행 계정은 macOS용 Buildkite Agent 설치 문서의 현재 절차를 따르세요.

설정 파일, 로그, 작업 디렉터리의 실제 위치는 설치 후 직접 확인해야 합니다. 운영체제나 설치 방식에 따라 경로를 추정해 고정하지 말고, Agent가 실행 중인 계정으로 확인합니다.

예시의 민감한 값은 모두 자리표시자입니다.

export BUILDKITE_AGENT_TOKEN="<AGENT_TOKEN>"
export BUILDKITE_AGENT_NAME="<REMOTE_MAC_NAME>"
export BUILDKITE_AGENT_QUEUE="<XCODE_27_QUEUE>"

토큰을 셸 기록, 파이프라인 로그, 저장소에 남기지 마세요. Agent를 등록할 때는 목표 Cluster와 Queue를 명시하고, 태그에는 실제 하드웨어와 도구 체인을 구분할 수 있는 정보만 넣습니다. Queue 라우팅 공식 문서를 참고하면 다른 macOS 노드로 작업이 잘못 전달되는 문제를 줄일 수 있습니다.

등록 직후에는 다음과 같은 최소 작업을 실행합니다.

set -e
uname -m
sw_vers
xcode-select -p
xcodebuild -version

이 작업의 목적은 성능 측정이 아닙니다. 아키텍처, macOS 버전, 개발 도구 경로, Xcode 버전이 의도한 원격 Mac에서 출력되는지 확인하는 것입니다. 출력 결과에 비밀 값이 포함되지 않는지도 함께 점검합니다.

SECTION 03 첫 프로젝트로 Xcode 27 빌드 경로를 검증합니다

이제 실제 저장소를 연결합니다. 읽기 전용 접근이 가능한 머신용 자격 증명이나 비밀 관리 기능을 우선 사용하고, 개인 개발자의 장기 토큰을 Agent 계정에 복사하지 않는 편이 좋습니다. Buildkite의 코드 접근 방식을 기준으로 저장소별 최소 권한을 설계합니다.

파이프라인에서는 대화형 셸의 환경 변수에 기대지 말고 Xcode 경로를 명시합니다.

set -euo pipefail

sudo xcode-select -s "<XCODE_27_PATH>"
xcodebuild -version

xcodebuild \
  -workspace "<WORKSPACE_PATH>" \
  -scheme "<SCHEME_NAME>" \
  -configuration Release \
  -destination "generic/platform=iOS" \
  clean build

위 명령은 예시이므로 프로젝트의 워크스페이스와 스킴에 맞게 바꿔야 합니다. 서명 없는 빌드라면 서명 설정을 분리하고, 처음부터 배포용 키체인을 연결하지 않습니다.

검증 순서는 다음과 같이 기록합니다.

1. 의존성 복원이 성공했는지 확인합니다.
2. 컴파일 단계의 종료 코드를 저장합니다.
3. 단위 테스트 결과 파일의 생성 위치를 확인합니다.
4. 빌드 로그와 산출물 경로를 Buildkite 결과에 남깁니다.
5. 동일한 커밋을 다시 실행해 환경 변수 없이 재현되는지 확인합니다.

Xcode 27이 설치되어 있다는 사실보다 중요한 것은 동일한 프로젝트가 같은 실행 계정과 같은 경로에서 반복되는지입니다. 빌드가 실패하면 Simulator나 서명 단계로 넘어가지 말고, 먼저 Xcode 선택 경로와 의존성 캐시를 고정합니다.

SECTION 04 마일스톤별 통과 기준을 표로 고정합니다

다음 표는 기능 소개가 아니라 배포 순서를 정하는 판단 도구입니다. 한 단계라도 관찰 가능한 증거가 없으면 다음 단계로 진행하지 않습니다.

Xcode 27의 베타 상태와 시스템 조건은 Apple의 공식 요구 사항으로 확인합니다. 공식 문서에 없는 빌드 시간, 동시 작업 수, 안정성은 일반적인 수치로 단정하지 마세요. 해당 값은 사용하는 프로젝트와 원격 Mac의 실제 검증 결과로만 판단해야 합니다.

SECTION 05 그래픽 작업은 필요한 경우에만 추가합니다

순수 컴파일 노드라면 로그인 화면과 Simulator를 무조건 구성할 이유가 없습니다. 그래픽 세션을 추가하면 로그인 상태, 화면 잠금, Simulator 런타임, 사용자별 장치 목록이라는 새로운 장애 지점이 생깁니다.

UI 테스트가 필요할 때는 Agent가 실행되는 사용자 세션에서 Simulator가 보이는지 확인합니다. 최소 작업은 다음 순서로 구성합니다.

1. 대상 Simulator 런타임이 설치되어 있는지 확인합니다.
2. 지정한 장치가 목록에 표시되는지 확인합니다.
3. Simulator를 부팅하고 준비 상태를 기다립니다.
4. 테스트를 실행하고 결과 파일을 수집합니다.
5. 작업 종료 후 장치와 임시 파일을 정리합니다.

Simulator 테스트 성공은 실제 iPhone 또는 iPad 테스트 성공을 의미하지 않습니다. 물리 장치 연결, 푸시 알림, 카메라, 네트워크 조건, 배포 서명은 별도 검증 항목입니다. 그래픽 세션이 자동으로 복구되지 않으면 명령줄 전용 Queue로 작업을 되돌리는 것이 맞습니다.

SECTION 06 서명 작업은 별도 경계에서 마지막에 엽니다

일반 풀 리퀘스트가 생산용 인증서에 접근하면 코드 검토가 끝나기 전에 배포 자산이 노출될 수 있습니다. 따라서 빌드 Queue와 서명 Queue를 분리하고, 가능하면 실행 계정도 나눕니다.

다음 항목을 비대화형 세션에서 확인합니다.

• 키체인이 Agent 계정에서 필요한 시점에만 잠금 해제되는지
• 개인 키 접근 승인 상태가 재시작 뒤에도 예상대로 동작하는지
• 프로비저닝 프로파일과 대상 스킴이 정확히 연결되는지
• 인증서 이름과 팀 식별자가 로그에 노출되지 않는지
• 서명 실패 시 작업 공간과 임시 키체인이 정리되는지

Apple의 코드 서명 관련 공식 안내와 논의 자료를 참고하되, 포럼의 사례를 모든 프로젝트에 적용되는 보장으로 해석하지 마세요. 인증서, 팀 식별자, 비밀번호, 저장소 주소는 예시와 로그에서 모두 자리표시자로 처리합니다.

동시 실행도 보수적으로 시작합니다. 동일한 DerivedData, Simulator 장치, 키체인을 여러 작업이 공유한다는 증거가 없다면 단일 작업으로 제한합니다. Agent 프로세스를 늘리는 것이 곧 처리량 증가를 뜻하지는 않습니다. 작업 공간과 보안 자산을 분리한 뒤에만 병렬화를 시험해야 합니다.

SECTION 07 재시작 뒤에는 프로세스가 아니라 작업을 확인합니다

운영 투입 전 마지막 단계는 통제된 재시작입니다. launchd 상주 설정은 Apple의 launchd 작업 생성 문서를 기준으로 구성하되, 기존 서비스 파일을 덮어쓰기 전에 원본과 복구 방법을 보관합니다.

재시작 후에는 다음 순서로 확인합니다.

• 원격 접속이 복구되는지 확인합니다.
• Agent 실행 계정과 사용자 세션 상태를 확인합니다.
• launchd가 Agent를 다시 시작했는지 확인합니다.
• Buildkite Queue에서 노드가 올바른 태그로 온라인인지 확인합니다.
• 진단 작업이 아니라 실제 Xcode 작업을 제출합니다.
• 로그 회전, 작업 공간 정리, 디스크 증가를 확인합니다.

Agent가 온라인으로 표시되지만 실제 작업을 받지 못하면 배포 성공으로 기록하지 않습니다. 토큰, Queue, 실행 계정, 네트워크 연결, 작업 디렉터리 권한을 순서대로 되짚고, 원인 확인 전에는 생산 Queue에 다시 넣지 않습니다.

SECTION 08 출시 전 체크리스트로 사용 범위를 결정합니다

• [ ] Xcode 27 베타 상태와 macOS 요구 조건을 Apple 공식 자료에서 확인했습니다.
• [ ] Apple Silicon 원격 Mac을 안정 버전 노드와 분리했습니다.
• [ ] Agent 전용 계정과 최소 저장소 권한을 만들었습니다.
• [ ] Token, Cluster, Queue, 태그를 자리표시자 없이 실제 설정과 대조했습니다.
• [ ] 명령줄 빌드와 단위 테스트의 종료 코드와 결과 파일을 보관했습니다.
• [ ] Simulator가 필요한지 결정하고 최소 테스트와 정리를 검증했습니다.
• [ ] 서명 자산을 일반 빌드 Queue와 분리했습니다.
• [ ] 통제된 재시작 뒤 실제 Xcode 작업을 다시 실행했습니다.
• [ ] 로그 회전, 작업 공간 정리, Xcode 버전 고정과 롤백 경로를 정했습니다.

이 목록에서 명령줄 빌드만 통과했다면 해당 노드는 컴파일 전용으로만 운영할 수 있습니다. Simulator와 서명까지 통과했을 때만 각각의 작업을 열고, 재시작 복구가 실패하면 안정 노드로 되돌립니다.

SECTION 09 FAQ

Buildkite Agent를 원격 Mac에 설치해도 되나요?

가능합니다. Buildkite는 macOS에서 자체 호스팅 Agent를 실행하는 방식을 공식 지원합니다. 다만 원격 Mac에 전용 실행 계정을 만들고, Agent를 위해 불필요한 인바운드 포트를 열지 않는 구성이 우선입니다. 설치 직후에는 온라인 상태가 아니라 실제 프로젝트 작업의 저장소 접근, Xcode 실행, 결과 파일 생성을 확인해야 합니다.

Buildkite에서 Xcode 27 빌드 노드를 어떻게 지정하나요?

Xcode 27 전용 Queue와 태그를 만들고, 해당 원격 Mac의 Agent가 그 대기열만 받도록 설정합니다. 파이프라인 단계에도 같은 조건을 명시해야 합니다. 작업 내부에서는 xcode-select 또는 프로젝트 스크립트로 Xcode 경로를 직접 지정합니다. 진단 작업에서 시스템 아키텍처와 Xcode 버전을 출력하면 잘못된 노드 라우팅을 조기에 발견할 수 있습니다.

원격 Mac의 Agent는 재시작 뒤 자동으로 운영 상태로 복귀하나요?

launchd를 사용하면 재시작 뒤 Agent를 자동 실행할 수 있습니다. 그러나 자동 실행과 정상적인 CI 복귀는 다른 상태입니다. 원격 접속, 실행 계정, 사용자 세션, launchd 로그, Queue 연결을 확인한 뒤 실제 빌드를 제출해야 합니다. 프로세스 목록에 Agent가 보인다는 이유만으로 복구가 끝났다고 기록하면 안 됩니다.

자체 호스팅 Mac에서 iOS Simulator 테스트를 실행할 수 있나요?

가능하지만 그래픽 세션과 Simulator 런타임이 Agent 실행 계정에서 접근 가능해야 합니다. 먼저 대상 장치의 표시와 부팅을 확인하고, 최소 UI 테스트를 실행한 뒤 결과 수집과 정리를 검증합니다. 이 과정이 통과해도 실제 기기 검증, 하드웨어 기능, 배포 서명까지 보장되는 것은 아니므로 별도의 Queue와 승인 절차를 유지해야 합니다.

Apple 서명 인증서는 어떻게 격리하나요?

일반 코드 검증과 배포 서명에 서로 다른 Queue 또는 실행 계정을 사용합니다. 개인 키가 포함된 키체인은 배포 단계에서만 접근하도록 제한하고, 비대화형 Agent 세션에서 잠금 해제와 프로파일 매핑을 확인합니다. 토큰, 팀 식별자, 인증서 이름, 비밀번호는 저장소와 로그에 기록하지 않습니다. 서명 오류가 발생하면 키체인 전체를 삭제하기 전에 백업과 복구 경로를 확보해야 합니다.

안정 버전 Mac을 그대로 공유하면서 Xcode 27을 덧붙이는 방식은 도구 경로 충돌, Simulator 상태 공유, 서명 자산 노출이라는 문제가 생기기 쉽습니다. 사내 장비는 장기 점유 비용과 재부팅 조율 부담도 남습니다. 반면 별도 원격 Mac을 쓰면 베타 Queue를 안정 환경에서 떼어내고, 필요한 기간에만 구성과 접근 범위를 검증하기 쉽습니다. 장기간 고정된 고부하 작업이나 물리 장치 연결이 핵심이라면 직접 소유한 Mac이 더 적합하지만, Xcode 27 파이프라인을 시험하거나 임시 CI 노드가 필요하다면 VPSNIX의 Mac 이용 요금을 검수 항목과 함께 비교해 보세요.

노드를 실제 생산 Queue에 넣기 전에는 원격 Mac 운영 지원 안내에서 접속과 관리 조건을 확인할 수 있습니다. 이 글의 체크리스트대로 명령줄 빌드, Simulator, 서명, 재시작 복구를 각각 통과한 뒤에만 사용 범위를 넓히는 것이 안전합니다.

SECTION 10 자주 묻는 질문 FAQ