GitHub Runner가 Cloud Mac AI Stack의 실행 엔진인 이유

최근 대화에서도 나왔듯, Claude Code·CodeGraph 인덱스·Ollama를 원격 macOS 노드로 옮기는 팀이 늘고 있습니다(Cloud Mac vs 로컬 Mac). 「클라우드에 올리면 push만으로 전부 초록」이라고 생각해도, 터미널 Agent는 순조로운데 git push 뒤 GitHub Actions는 ubuntu-latest 그대로라 xcodebuild가 실패하거나 macOS job이 30분 큐에 서는 패턴이 흔합니다.

이 글은 「GitHub Runner란」 백과도, actions/runner 등록 절차(다음 튜토리얼용)도 아닙니다. 목표는 Mac 대여 한 줄이 아니라 확장 가능한 방법론 Cloud Mac AI Stack입니다. L1이 답하는 질문: 왜 「Claude Code가 도는 원격 PC」에서 끝나지 않고, 먼저 실행 엔진이 필요한가.

Stack 언어: Context → Diff → Fact → Workflow

Claude Code, Cursor, MCP, OpenHands 이야기는 넘치지만, Agent가 코드를 고친 뒤 누가 조직이 인정하는 결과가 되는지는 잘 안 다뤄집니다. 업계 용어는 Agent, Tool, CI, Automation——Cloud Mac AI Stack에서는 네 가지산출물로 잇습니다(L2 추론은 표에서 별도):

기억용 체인(호출 순서 아님 · 5계층도 참고)

  Context  →  Diff  →  Fact  →  Workflow
  (MCP)      (Claude Code)  (Runner)  (OpenHands)

쟁점은 「AI가 똑똑한가」가 아니라 L1이 독립하는가입니다. Fact 층이 없으면 Context와 Diff가 아무리 좋아도 merge 버튼의 초록이 되지 않습니다.

코딩 계층과 실행 계층: Cloud Mac인데도 CI가 끊기는 이유

실행 계층 분리에서 모델 추론과 Agent 실행을 나눴습니다. 한 걸음 더——많은 팀이 놓치는 두 번째 실행 체인: 터미널에서 한 번 도는 pnpm test가 아니라, push 뒤 CI가 정의하는 재현·감사 가능한 빌드입니다.

단절은 여기서 납니다. Cloud Mac SSH에 Claude Code를 두고 테스트는 초록인데 workflow는 Linux runner——저장소의 공식 진실은 여전히 빨강입니다. iOS 팀에선 TestFlight 파이프라인이 Linux에서 시작되지 않습니다. 실행 계층은 독립해야 하고, 종종 같은 종류의 macOS 환경과 맞춰야 합니다.

전형 오판: Claude Code 「테스트 전부 통과」, PR은 빨강

고객 저장소에서 반복되는 동형 사고——도면보다 기억하기 쉽습니다:

1. Cloud Mac SSH에서 Claude Code. Agent: 「모든 테스트가 통과했습니다.」
2. 개발자가 git push 후 회의로.
3. GitHub Actions 기동. workflow는 runs-on: ubuntu-latest 그대로.
4. 약 10분 뒤 PR checks 빨강. 로그 단골: xcodebuild: command not found(또는 iOS job 없이 Node 테스트만 Linux에서 초록).

Claude Code 탓이 아니라, Claude Code 실행 환경 ≠ CI 실행 환경입니다. macOS 세션의 「통과」가 조직이 인정하는 Runner가 같은 GitHub Actions 파이프라인에서 재현되지 않았습니다. Runner는 세션 결론을 push마다 감사 가능한 Fact로 바꿉니다——필요하면 GitHub Actions self-hosted runner macOS와 동일 노드에.

Runner는 「Mac 하나 더 빌리기」가 아님

흔한 세 가지 오해를 분명히 합니다:

• 아님: Cloud Mac 제품 소개——대여는 L0. Runner는 그 위에서 GitHub 작업을 상시 대기하는 소프트웨어·정책(label, 동시성, workspace 정리).
• 아님: GitHub 공식 macos-latest 설명서——호스팅 runner는 다른 과금·큐·격리. self-hosted는 자기 노드로 디스패치.
• 아님: OpenClaw / OpenHands——OpenClaw 클라우드 자동화는 오케스트레이션·ACK. Runner는 xcodebuild, fastlane을 실제로 밟는 발입니다.

한 줄: Cloud Mac은 macOS 연산과 출구. Runner는 그것을 GitHub 이벤트 모델에 연결한다.

Runner 없으면 Cloud Mac은 원격 PC. Runner가 있어야 연구 인프라. 한 문장만 기억: Diff → Fact(위 파란 박스).

Cloud Mac AI Stack 5계층 구조도(시리즈 공통 · 되돌아오기 #stack-map)

앞으로 L2–L5는 「Cloud Mac AI Stack 5계층 구조도 참고」(본문 #stack-map)로 통일합니다. 단발 SEO가 아니라 방법론과 명명을 쌓습니다.

Cloud Mac AI Stack 5계층(책임 · 아래에서 위)

                 ┌──────────────┐
                 │  OpenHands   │  L5 · Workflow
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │     MCP      │  L4 · Context
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │ Claude Code  │  L3 · Diff
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │    Ollama    │  L2 · Inference(선택)
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │ GitHub Runner│  L1 · Fact  ← 본문
                 └──────┬───────┘
                        │
                 ┌──────▼───────┐
                 │  Cloud Mac   │  L0 · 인프라
                 └──────────────┘

읽는 법: L0가 연산을 받치고, L1이 조직이 믿는 Fact를 받치고, 그 위에 Diff·Context·Workflow. Ollama는 L2 「프라이빗 추론을 얹을 수 있음」 표시. L3 전에 Ollama 필수 아님.

「실행 엔진」이라 부르는 이유

5계층 모델에서 Runner는 L1 고정. Claude Code와 「누가 더 똑똑한가」가 아니라 재현 실행 세 가지:

1. 저장소 이벤트——on: push, pull_request, workflow_dispatch가 label self-hosted runner에 job 전달.
2. macOS 네이티브 도구——xcodebuild, swift test, notarytool, 서명·아카이브. Linux 대체 불가.
3. AI 계층 분리——Agent가 고침 ≠ CI 자동 통과. Runner는 「고침」을 artifact·테스트 리포트·배포 가능물로.

iOS / Flutter(iOS 타깃)용 실제 딜리버리 경로:

Cloud Mac AI Stack · L1 실행 사슬(개념)

  Claude Code(L3 · SSH / 터미널)
           │
           │  git commit & push
           ▼
  GitHub(webhook / Actions 스케줄)
           │
           ▼
  GitHub Actions workflow
           │
           ▼
  GitHub Runner(L1 · self-hosted · macOS · ARM64)
           │
           ├── xcodebuild(Debug / Release)
           ├── 단위 / UI 테스트
           ├── archive → .ipa
           └── fastlane → TestFlight

가치: 「Runner란」 정의는 복사되기 쉽지만, Stack 전체 계층 관계는 복사되기 어렵다. 코딩은 L3. 바이너리를 밖으로보내는 건 L1. 한 고리가 비면 「Agent는 완료, App Store Connect에 패키지 없음」.

# .github/workflows/ios-ci.yml(발췌)
jobs:
  build-ios:
    runs-on: [self-hosted, macOS, ARM64, cloud-mac]
    steps:
      - uses: actions/checkout@v4
      - name: Build & Test
        run: xcodebuild -scheme MyApp -destination 'platform=iOS Simulator,name=iPhone 16' test

검색은 「GitHub Runner」보다 iOS CI / Mac mini Runner

SEO·지원 티켓에서 엔지니어는 포괄어보다 다음 의도로 옵니다:

• GitHub Actions self-hosted runner macOS / macOS ARM64 runner / Apple Silicon runner
• GitHub Runner Mac mini / GitHub Actions Mac mini
• iOS CI/CD self-hosted runner / GitHub Actions iOS build
• Cloud Mac CI, Xcode on CI, TestFlight 자동화

배경은 같은 아키텍처 문제: job을 자사 Apple Silicon으로 보내고 싶다. Cloud Mac(또는 사무실 Mac mini)이 머신. Runner 등록 + label로 「배차」 완성. 이 글은 층을 세우는 이유. L1-Q02에서 절차.

「Mac mini 구매 vs Cloud Mac 대여」는 L0 이야기——Mac mini vs Cloud Mac(iOS 팀). Runner 로직은 동일. L1-Q05에서 비용 비교 예정.

Linux로 부족할 때 · macOS Runner가 불필요할 때

ubuntu-latest는 웹 백엔드에 강하지만 Apple 딜리버리에는 딱딱한 경계가 있습니다.

「해당 없음」도 같이 중요——만능 Cloud Mac 오해를 막기 위해. 다음은 Linux runner로 충분한 전형:

• Next.js / 정적 프론트——Node 빌드만, Xcode 없음.
• Node / Python / Go API——Docker job은 Linux가 일반적.
• 컨테이너 백엔드——K8s 배포는 macOS 불필요.
• 개인 소규모 저장소——월 몇 번 CI면 호스팅 runner 큐 비용이 더 쌀 수 있음.

macOS Runner 신호는 집중: workflow에 Xcode, 서명, notarize, Simulator, TestFlight. 또는 Mac mini vs Cloud Mac 검토 중. 이 글은 L1 위치만 강조.

호스팅 macos-latest vs Cloud Mac 자체

경험칙(계약 아님): 주당 macOS job 10회 초과의 절반이 iOS 서명·아카이브면 L1을 「임시 큐」에서 「고정 Cloud Mac + self-hosted」로. 그 미만이면 호스팅 macOS로 파이프라인부터 통과하는 편이 수월한 경우가 많습니다.

도입 순서: 먼저 Fact, 그다음 Diff——도와 별개

5계층도는 책임 계층. 도입은 배포 순서도 따로: 많은 글은 Claude Code → MCP → 마지막 CI. 우리는:

1. L0——Cloud Mac(상시 macOS, 출구, SSH).
2. L1——GitHub Runner. 먼저 push → 초록/빨강 재현(본문).
3. L2–L3——Ollama, Claude Code. 「객관적 빌드 결과」 위에 AI.
4. L4–L5——MCP, OpenHands. 안정 CI 뒤.

CodeGraph + Agent가 18개 파일을 고쳐도 macOS CI가 불안정하면 archive에서 터지는 누락을 알 수 없습니다. Runner가 먼저 「기계 검수」를 고정해 AI가 샌드박스 놀이가 되지 않게.

Mac mini + Claude Code 일주는 L3 체험. 이 글은 L1——같은 머신에서 밤 Runner·낮 Agent 가능. 다만 글에서는 계층을 섞지 않습니다.

판단: Runner를 실행 엔진으로 볼지

왼쪽에 두 항목 이상이면 다음은 MCP 추가 전에 L1을 통과하세요. L1 연재로.

L1 연재: 실행 엔진에서 운영 가능한 macOS CI로

본문은 Cloud Mac AI Stack · L1 기반(L1-Q01). 이어서 Runner를 개념에서 운영으로:

Google은 L1 글 묶음을 「GitHub Runner + macOS CI」 주제로 이해하기 쉽습니다. L2 이후 Ollama(Inference), Claude Code(Diff), MCP(Context), OpenHands(Workflow)——모두 「push에 Fact가 있다」 전제. 되돌아오기 5계층 구조도.

자주 묻는 질문

Cloud Mac과 self-hosted Runner 관계?
Cloud Mac은 L0. Runner는 L1 프로세스·정책. 대여 ≠ Runner 자동 부착.

MacBook만으로 Runner?
가능하나 안정성 어려움. 일일 macOS CI는 24/7 Cloud Mac이 일반적.

Runner와 Claude Code 동일 머신 필수?
필수 아님. 동일하면 「SSH 초록·Actions 빨강」 마찰 감소.

OpenClaw와 차이?
Runner는 step 실행. OpenClaw는 트리거·ACK. OpenClaw 클라우드 자동화 참고.

self-hosted runner macOS와 Cloud Mac 병용?
L0에 Runner 등록, runs-on: [self-hosted, macOS, ARM64]로 iOS CI/CD·xcodebuild·TestFlight를 해당 노드로.

Claude Code → Diff, Runner → Fact 의미?
Diff는 세션 내 변경·주관적 결론. Fact는 GitHub Checks 초록, 로그, artifact. 조직이 merge하는 건 후자. MCP는 Context, OpenHands는 Workflow. § Stack 언어.

도에서 Ollama가 Claude Code 아래＝Ollama 먼저?
아님. 책임 계층이지 호출 순서 아님. Claude Code는 API가 많고 Ollama는 L2 선택 Inference. § 5계층도.