TeamCity에 iOS 또는 macOS 빌드 기능을 추가하는 플랫폼 엔지니어를 위한 글입니다.
공용 Mac mini를 팀 공유 빌드 노드로 바꾸려는 기업 IT 담당자에게도 해당합니다.
여러 원격 Mac을 구매하거나 렌탈하면서 서명 격리, 용량 근거, 장애 복구를 확보하려는 기술 책임자도 대상입니다.

마지막 점검일은 2026년 8월 30일입니다. TeamCity 온프레미스 2026.1과 TeamCity 클라우드 2026.2의 공식 문서, 그리고 Xcode 관련 Apple 개발자 문서를 대조했습니다. 클라우드 문서의 시작 방식은 온프레미스 기능의 보증으로 해석하지 마십시오.

가장 먼저 확인할 것은 프로젝트가 아니라 Agent 프로세스의 실행 환경입니다. TeamCity 2026.1용 Agent가 사용하는 JDK와 프로젝트가 실제로 코드를 컴파일할 때 사용하는 JDK는 같은 항목이 아닐 수 있습니다.

다음 조건이 하나라도 불명확하면 생산 등록을 보류하십시오.

• Agent 프로세스의 JAVA_HOME이 Java 21을 가리키는가
• Apple Silicon 호스트에서 실행 파일과 설치 경로가 의도한 방식으로 동작하는가
• macOS 버전, 디스크 여유 공간, 운영 계정이 자산 기록과 일치하는가
• 완전한 Xcode가 설치되어 있는가
• Agent 디렉터리와 로그 디렉터리의 소유권이 전용 계정에 있는가

확인은 짧게 시작할 수 있습니다.

java -version
echo "$JAVA_HOME"
uname -m
xcode-select -p

이 출력은 설치 성공의 증명이 아닙니다. 실행 시점의 환경이 서비스 등록 뒤에도 유지되는지 확인해야 합니다. 특히 관리자 셸에서 확인한 JAVA_HOME이 launchd 환경에는 전달되지 않는 경우가 있습니다.

생산 Agent는 root로 실행하지 않는 편이 안전합니다. root는 작업 스크립트가 호스트 전체 파일과 키체인에 접근할 수 있는 범위를 키웁니다. 관리자 권한이 필요한 초기 디렉터리 생성, 시스템 서비스 등록, 방화벽 정책 변경만 임시로 수행하고, 실제 Agent와 빌드는 전용 비관리자 계정으로 실행하십시오.

이 계정에는 필요한 작업 디렉터리와 임시 키체인만 권한을 부여합니다. 프로젝트가 요구하는 컴파일용 JDK가 별도로 있다면 빌드 단계의 환경 변수로 지정하고, Agent 연결용 Java 21과 섞지 마십시오.

서버 화면의 Connected는 연결 경로가 열렸다는 뜻에 가깝습니다. 등록 승인, 인증 토큰, 서버 주소, 프록시 정책과 작업 요구 조건이 모두 맞다는 의미는 아닙니다.

TeamCity 공식 빠른 설정 안내와 Agent 설치 설정 문서를 기준으로 다음 자료를 함께 보관하십시오.

1. Agent 설정 파일의 serverUrl 값
2. 등록에 사용한 authorizationToken의 승인 상태
3. Agent 로그의 연결 및 인증 결과
4. 역방향 프록시를 통과하는 HTTPS 요청 기록
5. 서버 화면의 Agent 이름, Pool, 승인 상태

TeamCity Agent는 일반적으로 서버가 작업을 밀어 넣는 방식보다 Agent가 서버에 연결해 작업을 받는 구조로 이해해야 합니다. 따라서 인바운드 포트를 열었다는 이유만으로 정상 작동을 판단하면 안 됩니다. Agent에서 서버로 나가는 연결, 프록시의 인증서 처리, 장시간 연결 유지 정책을 확인해야 합니다.

Agent 이름은 자동 생성값보다 고정된 운영 규칙을 사용하십시오. 예를 들어 지역, Xcode 계열, 용도를 조합해 이름을 정하면 로그와 장애 인계가 쉬워집니다. 설정 파일은 수동 편집본과 배포본을 구분하고, 토큰은 일반 저장소에 넣지 마십시오.

연결 승인 전후에 남겨야 할 증거

• 서버에서 승인된 시각
• Agent 로그의 마지막 성공 연결 시각
• 첫 작업 수락 시각
• 프록시 또는 방화벽 로그의 허용 결과
• Agent Pool 배정 기록

승인 직후 아무 작업이나 실행하지 마십시오. 먼저 의도적으로 잘못된 요구 조건을 가진 작업을 보내고, 해당 Agent가 거부하는지 확인하면 라우팅 검증에도 도움이 됩니다.

iOS 빌드에 필요한 것은 Command Line Tools만이 아닙니다. 서명, 시뮬레이터, 보관, 프로젝트 빌드에 필요한 완전한 Xcode가 있어야 할 수 있습니다. Apple의 Xcode 명령줄 도구 문서는 명령줄 도구의 범위를 설명하지만, 이를 완전한 Xcode 설치와 동일하게 취급해서는 안 됩니다.

단일 Xcode 환경에서는 xcode-select가 가리키는 경로와 TeamCity의 Xcode 관련 설정이 일치해야 합니다. 여러 버전을 함께 운용한다면 세 가지 층을 분리해 설계하십시오.

• 작업 요구 조건: 이 작업이 어떤 Xcode 계열을 요구하는지 선언합니다.
• Agent 매개변수: 각 Mac이 실제로 제공하는 Xcode 경로와 버전을 표시합니다.
• 도구 체인 출력: 작업이 실제로 사용한 경로와 버전을 로그에 남깁니다.

TeamCity 공식 Xcode 빌드 문서는 Xcode 프로젝트 실행 방식을 설명합니다. Agent 요구 조건 문서는 작업 요구 사항과 Agent 속성을 맞추는 기준으로 활용할 수 있습니다.

검증 기준은 “작업 요구 조건 → 노드 매개변수 → 실제 도구 출력”의 세 값이 모두 일치하는 것입니다. 첫 번째와 두 번째만 맞으면 잘못된 기본 경로가 선택될 수 있습니다.

아래 조건표를 생산 설계의 초기 결정 도구로 사용하십시오.

현재 호스트가 Mac mini인지 원격 Mac인지보다 중요한 것은 증거의 일관성입니다. TeamCity Agent Pool 공식 문서를 참고해 신뢰 수준과 작업 종류가 다른 프로젝트를 같은 Pool에 넣지 마십시오.

팀 규모가 커지면 팀 iOS CI/CD 용량 계획에 적합한 Mac 구성을 검토할 수 있습니다. 이때 장비 수를 먼저 정하지 말고, 평균 대기 시간, 동시 보관 작업 수, 대체 노드가 필요한 업무부터 기록해야 합니다.

TeamCity의 같은 Agent에서 실행되는 작업이 자동으로 강한 보안 경계를 갖는다고 가정하면 안 됩니다. 작업 디렉터리, 캐시, 환경 변수, 임시 파일, 키체인이 서로 남아 있을 수 있습니다.

특히 다음 조합은 공식 배포 노드에서 피하는 편이 좋습니다.

• 신뢰할 수 없는 변경 요청과 공식 서명 작업
• 외부 기여 코드와 배포 인증서가 있는 계정
• 여러 팀의 캐시를 같은 디렉터리에 유지하는 구성
• 작업 후 키체인과 프로파일을 정리하지 않는 구성

작업별로 checkout 디렉터리를 분리하고, 재현성이 중요하거나 이전 작업의 잔여물이 의심되면 clean checkout을 사용하십시오. 캐시는 속도를 높일 수 있지만, 서명 파일이나 생성된 설정을 보존하는 저장소로 사용해서는 안 됩니다.

서명 노드는 별도 Agent Pool로 분리하는 것이 기본입니다. 임시 키체인을 작업 시작 때 만들고, 인증서와 프로파일을 설치한 뒤, 작업 종료 시 목록과 파일 잔여물을 검사합니다. 실패한 작업에서도 정리 단계가 실행되는지 확인하십시오.

주의: 로그에 서명 인증서의 비밀 값이나 토큰이 출력되지 않는지 먼저 확인하십시오. 빌드 실패를 조사하려고 전체 환경 변수를 출력하면, 작업 로그가 새로운 유출 경로가 될 수 있습니다.

기업 원격 Mac의 서명 자격 증명과 작업 공간 격리 기준을 참고해 저장소 신뢰도, 서명 권한, 캐시 범위를 각각 문서화하십시오. Mac mini를 팀 공용으로 운영하는 경우에도 물리적으로 한 대라는 이유만으로 프로젝트 경계를 생략할 수 없습니다.

원격 노드의 생산 가치는 작업을 한 번 성공시키는 데 있지 않습니다. 재부팅이나 Agent 프로세스 종료 뒤에도 사람이 현장에 로그인하지 않고 다시 작업을 받을 수 있어야 합니다.

확인은 다음 순서로 진행하십시오.

1. 전용 실행 계정과 Agent 파일의 소유권을 확인합니다.
2. launchd 등록 파일의 실행 경로와 환경 변수를 확인합니다.
3. 원격 Mac을 재부팅하고 Agent가 서버에 다시 연결되는지 기록합니다.
4. 재연결 뒤 Xcode를 처음 호출하는 작업을 실행합니다.
5. 임시 키체인이 필요한 서명 작업을 실행합니다.
6. Agent 중지, 서버 연결 실패, 키체인 실패에 대한 경보를 확인합니다.

TeamCity 공식 Agent 시작 문서는 시작 속성 확인에 참고할 수 있습니다. 다만 TeamCity 클라우드 2026.2 문서의 설치 및 시작 흐름을 온프레미스 2026.1의 동일한 기능으로 단정하지 마십시오.

서비스가 사용자 로그인 이후에만 실행된다면 대기 노드나 개발용 노드에는 쓸 수 있어도 무인 생산 서명 노드에는 부족합니다. 재부팅 뒤 사람이 로그인해야 하는 구조를 해결하지 못했다면 생산 Pool에 넣지 말고 시험 Pool에 남겨야 합니다.

빈 프로젝트의 성공은 용량이나 안정성을 증명하지 못합니다. 대표적인 변경 요청 빌드, 시뮬레이터 테스트, 보관, 제한된 서명 작업을 실제 순서로 제출하십시오.

기록할 항목은 다음과 같습니다.

• 작업 대기 시간과 Agent 점유 시간
• 빌드 성공 및 실패 원인
• clean checkout 뒤 작업 공간의 잔여물
• Xcode 경로와 실제 도구 버전 출력
• 재부팅 뒤 재연결 시각
• 서명 작업 뒤 키체인과 프로파일 정리 결과
• 주 노드 장애 시 대체 노드의 작업 인계 여부

용량 선택은 다음 조건으로 결정하십시오.

• 대표 작업이 반복 성공하고 대기열이 누적되지 않으며 대체 노드가 확인되면 주 생산 Pool로 승격합니다.
• 빌드는 성공하지만 서명 정리나 재부팅 복구가 실패하면 일반 테스트 Pool로 되돌립니다.
• Xcode 요구 조건이 흔들리면 한 노드에 여러 버전을 계속 추가하지 말고 버전별 노드로 나눕니다.
• 고정된 Mac 용량이 없으면 독립 원격 Mac을 먼저 시험 노드로 사용하고, 실제 TeamCity 작업 기록이 쌓인 뒤 추가합니다.
• 신뢰할 수 없는 변경 요청을 처리해야 하면 공식 서명 노드와 같은 Agent Pool을 사용하지 않습니다.

이 표와 조건 판단을 Apple Silicon Mac 빌드 노드의 재시작 복구 점검과 함께 운영 기록 양식으로 관리하면, 구매 수량이나 렌탈 기간을 감으로 정하는 일을 줄일 수 있습니다.

TeamCity macOS Build Agent를 재부팅 뒤 자동으로 실행하려면 어떻게 해야 하나요?

전용 실행 계정과 Agent 디렉터리의 소유권을 먼저 고정한 뒤, 운영체제의 launchd 등록 방식을 사용해 자동 시작을 구성합니다. 단순히 사용자가 로그인해야 실행되는 방식은 무인 생산 노드에 적합하지 않습니다. 재부팅 후 Agent 연결, Xcode 최초 호출, 임시 키체인 접근까지 실제 작업으로 확인해야 합니다.

TeamCity Agent가 연결됨으로 표시되는데 Xcode 빌드가 실행되지 않는 이유는 무엇인가요?

연결 상태는 서버와 Agent 사이의 통신만 증명합니다. 해당 노드에 완전한 Xcode가 설치되어 있는지, 선택된 개발자 도구 경로가 올바른지, 작업이 요구하는 Agent 매개변수와 일치하는지는 별도로 확인해야 합니다. Agent 로그, 작업 요구 조건, 도구 버전 출력을 함께 비교해야 원인을 좁힐 수 있습니다.

TeamCity에서 Xcode 버전에 따라 작업을 다른 Mac으로 보낼 수 있나요?

가능합니다. 각 Mac에 설치된 Xcode 경로와 버전을 Agent 매개변수로 표현하고, 빌드 설정의 요구 조건이 해당 값과 일치하도록 구성합니다. 여러 버전을 한 노드에 억지로 넣기보다, 릴리스용과 테스트용을 별도 Agent 또는 Agent Pool로 나누면 잘못된 도구 체인으로 작업이 실행되는 위험을 줄일 수 있습니다.

TeamCity Mac Agent에서 서명 인증서와 작업 공간을 어떻게 격리하나요?

공용 Agent의 작업 디렉터리와 키체인을 자동으로 안전한 경계로 간주하면 안 됩니다. 신뢰할 수 없는 변경 요청, 일반 테스트, 공식 서명 작업을 서로 다른 Agent Pool 또는 전용 Mac으로 분리해야 합니다. 작업 전용 임시 키체인을 만들고, 작업 후 인증서와 프로파일 목록 및 작업 디렉터리 잔여물을 검사하십시오.

원격 Mac을 TeamCity 생산 빌드 노드로 사용할 수 있나요?

사용할 수 있지만 온라인 표시만으로 생산 승인을 내리면 안 됩니다. 자바 실행 환경, Xcode 라우팅, 서명 격리, 재시작 뒤 자동 복귀, 실제 보관 및 서명 작업을 모두 검증해야 합니다. 고정된 Mac 용량이 아직 없다면 독립 원격 Mac 한 대를 시험 노드로 사용한 뒤, 대기열과 장애 인계 자료를 바탕으로 확장하는 편이 안전합니다.

직접 구매한 Mac mini는 장기적으로 물리 장비를 통제하기 쉽지만, 초기 조달과 교체 부품, 장애 대응, 유휴 시간까지 직접 부담해야 합니다. 여러 팀이 동시에 사용하면 예비 장비와 네트워크, 보관 공간도 필요합니다.

원격 Mac 렌탈은 고정된 물리 장비를 보유하지 않고 시험 노드를 빠르게 추가할 수 있다는 장점이 있습니다. 반면 네트워크 지연, 제공 업체의 유지보수 절차, 물리 인터페이스가 필요한 작업의 한계를 계약 전에 확인해야 합니다. 장기간 일정한 고부하가 지속되고 현장 장비 통제가 필수라면 직접 구매가 더 적합할 수 있습니다.

반대로 새 Xcode 버전 검증, 단기간 릴리스 증가, 팀 확장처럼 수요가 흔들리는 경우에는 처음부터 여러 대를 구매하기보다 KVMNODE의 독립 원격 Mac으로 실제 작업을 검증하는 편이 합리적입니다. 제공 방식과 기간을 확인한 뒤, 승인표에 필요한 초기화 기록과 복구 증거를 요청하십시오.

현재 방식이 개발자별 로컬 Mac에 의존한다면 환경 차이, 장비 유휴 시간, 서명 자격 증명 분산이 남습니다. 직접 구매한 공용 Mac 한 대만 운영하면 장애 때 대체 노드가 없고, 수요가 줄어도 비용이 고정됩니다. 이런 조건이라면 먼저 KVMNODE의 원격 Mac 한 대를 격리된 TeamCity 시험 노드로 사용해 보십시오. Agent 라우팅과 Xcode, 서명, 재부팅 복구가 확인된 뒤에만 주간, 월간 또는 더 긴 기간의 용량으로 확대하는 방식이 기업 운영에 맞습니다.