잡이 계속 pending인 흔한 이유는?

YAML tags와 Runner tags 불일치, 잘못된 스코프 등록, Runner 오프라인, concurrent 고갈이 흔합니다.

concurrent를 낮게 시작하는 이유는?

여러 xcodebuild가 메모리·DerivedData·키체인을 경쟁합니다. 안정 기준선 후 상향하세요.

언제 노드를 수평 추가해야 하나?

대기열이 SLA를 넘기고 디스크·메모리 경고가 반복되거나 리전 분리가 필요할 때입니다. 단일 호스트 concurrent만 올리지 마세요.

2026 Mac 클라우드에서 GitLab Runner(macOS) 운영: 등록 토큰, Executor, 안전한 병렬

Linux Docker executor에 익숙한 플랫폼 팀은 macOS에서 아키텍처 오류, YAML tags 불일치로 pending, concurrent 과다로 DerivedData·키체인 경쟁 같은 패턴으로 막힙니다. 이 글은 SSH 가능한 Mac 클라우드를 GitLab의 라벨된 용량으로 쓰는 전제에서 Linux와의 차이, 네 가지 반복 문제, shell과 custom 비교표, 등록부터 스모크 잡까지 다섯 단계, 용량 회의용 수치, FAQ를 정리합니다. 2026년 기준 GitLab·Runner 호환 표는 반드시 공식 문서로 확인하세요.

1. 요약: Linux 습관과의 차이

Linux에서는 컨테이너로 의존성과 파일을 분리합니다. macOS의 xcodebuild는 동일 사용자 공간에서 DerivedData·모듈 캐시·키체인을 공유하므로 concurrent를 코어 수에 맞춰 올리면 링커 오류나 컴파일러 OOM이 무작위 실패로 보입니다.darwin-arm64 GitLab Runner 바이너리를 amd64로 잘못 쓰면 Rosetta 혼합으로 재현성이 깨집니다. 목표는 .gitlab-ci.yml의 tags와 Runner 등록 tags를 완전히 일치시키고 concurrent와 정리 작업을 config.toml에 남기는 것입니다. Mac 클라우드는 노트북 수면·출장 리스크를 줄이고 VPS처럼 SSH와 태그로 수평 확장할 수 있습니다.

2. 문제: 토큰, tags, 키체인, 디스크

등록 범위: 인스턴스 토큰과 프로젝트 토큰을 바꿔 끼우면 Runner가 다른 계층에 생깁니다. 토큰 순환 후 config.toml 미갱신이면 online이지만 job을 못 가져옵니다.
tags 드리프트: YAML과 Runner tags가 조금만 달라도 영구 pending. 재설치 때 README를 갱신하지 않으면 재발합니다.
서명과 비대화 세션: shell executor는 로그인 키체인 전제가 깨지면 코드 서명이 중간에 사라집니다. CI 전용 사용자와 파티션이 필요합니다.
디스크 경쟁: 병렬 job이 같은 DerivedData 루트를 청소하면 중간 산출물이 사라져 불안정해집니다. 경로 분리와 태그별 풀이 도움이 됩니다.

3. shell과 custom executor 비교

항목	shell	custom / 외부 격리
시작 속도	몇 시간 내 스모크	며칠~몇 주 정비
격리	약함(동일 사용자)	작업공간·VM으로 강화
서명	로그인 맥락과 맞으면 단순	시크릿 주입 설계 필요
병렬	`concurrent`와 tags로 엄격히	호스트/디렉터리 단위 분할 용이
디스크	경로 규약+정기 청소	훅으로 삭제·스냅샷
적합	중소 iOS 중심 CI	멀티테넌트·강한 컴플라이언스

팁: custom을 안정 운용하기 전에는 tags로 PR과 Archive를 나누고 concurrent를 보수적으로 유지하는 편이 총비용에 유리한 경우가 많습니다.

4. 등록에서 green 잡까지 5단계

설치 검증: darwin-arm64 gitlab-runner 배치, uname -m 대조. Rosetta amd64 체인 혼합 금지를 문서화.
register: 올바른 토큰으로 gitlab-runner register, 미래 YAML과 동일한 tags 입력, config.toml에 [[runners]] 확인.
executor·concurrent: executor = "shell", concurrent 1~2부터. PR용과 릴리스용 Runner 이름 분리.
스모크 YAML: sw_vers, xcodebuild -version만 실행하는 잡으로 라우팅 검증.
청소·임계값: DerivedData·캐시 경로 문서화, 여유 공간 알림, 야간 또는 파이프라인 끝에서 정리.

stages: [verify]

mac-smoke:
  stage: verify
  tags: [macos-arm64, ci-pool-dev]
  script:
    - sw_vers
    - xcodebuild -version

5. 메모리·디스크·병렬 지표

중형 Swift/iOS 기준이며 반드시 자사 모듈로 재측정하세요. 리뷰에서는 p95와 대기열을 분리해 Runner 추가인지 concurrent 축소인지 판단합니다. 스왑이 나오면 링크 단계 꼬리가 길어집니다.

메모리: 단일 Archive가 Apple Silicon에서 약 12~18GB 피크 사례. 32GB 머신에서 세 강한 병렬 빌드는 스왑으로 p95 악화.
디스크: 캐시 사용 시 여유 40GB급 버퍼 권장. 10GB 미만이면 링크 불안정 증가.
병렬 시작: custom 없으면 xcodebuild 1~2병렬부터. 가벼운 검사와 무거운 Archive는 tags 분리.
네트워크: 의존성·Git이 멀면 페치 시간이 선형 증가. PoC에서 페치 구간을 기록.
버전: GitLab 메이저 업은 스테이징 Runner로 선검증 후 프로덕션 tags 전환.
로그: 매 잡 df -h와 결과 번들 경로를 남겨 디스크 경쟁을 빠르게 판별.

6. Linux만으로 부족한 이유와 전용 Mac 클라우드

Linux Runner만으로는 네이티브 Xcode 서명과 Apple 공식 툴체인을 끝까지 수행하기 어렵습니다. 노트북을 빌리는 방식은 가용성·감사에 취약하고 비 Apple 하드 근사는 라이선스·성능 벽이 있습니다. 무인 서명, Xcode 소버전 고정, 기업 출구·레지스트리 정렬이 필요하면 SSH와 tags로 늘리는 전용 Mac 클라우드를 GitLab 풀에 올리는 편이 총비용에 유리한 경우가 많습니다. Docker 스타일 격리는 macOS에서 가치가 있으나 운영 부담도 커집니다. 운영 시간이 길수록 숨은 인건비가 임대료를 압도하지 않도록 지표를 분리해 보고하세요. 발주를 API에 가깝게 만들려면 VPSMAC의 90초 API와 CI/CD 연동 글을 참고해 주문부터 green까지 한 흐름으로 설계하세요.