GitHub Actions에서 Xcode 버전 고르는 법

runs-on 라벨은 어떤 macOS 이미지에서 돌지를 고르고, 그 안에서 어떤 Xcode를 쓸지는 워크플로가 고릅니다. 아무것도 정하지 않으면 이미지의 기본 Xcode가 쓰이고, 이미지가 바뀌면 기본도 바뀝니다. 아래 수치는 러너 이미지 개요에서 확인한 값입니다(Xcode 목록 기록 2026-09-25). 기준일(data_asof): 2026-10-06.

1. Xcode를 고르는 세 가지 방법

• DEVELOPER_DIR — 잡 또는 step의 env에 DEVELOPER_DIR: /Applications/Xcode_26.6.app/Contents/Developer처럼 앱 경로를 그대로 적습니다. 시스템 설정을 바꾸지 않고 그 잡이나 step에만 적용됩니다.
• setup-xcode 액션 — maxim-lobanov/setup-xcode에 xcode-version: "26.6"처럼 숫자 버전을 적습니다. latest, latest-stable은 숫자 고정이 아닙니다.
• xcode-select — step의 run에서 xcode-select -s(또는 --switch) 뒤에 같은 앱 경로를 적습니다. 시스템 전체 선택을 바꾸므로 관리자 권한이 필요합니다.

XenoCI는 이 세 가지를 워크플로에 글자 그대로 적었을 때 버전 요구로 인식합니다. 변수·표현식으로 계산한 버전이나 저장소 스크립트 안에서 바꾼 경로는 분석하지 않습니다.

2. xenoci-macos에 설치된 Xcode

macOS 26.6.2 이미지 기준입니다. 기준일: 2026-10-06 (러너 이미지 개요, Xcode 목록 기록 2026-09-25).

표의 제공 범위는 Xcode 설치 여부입니다. 모든 작업 VM에 해당 시뮬레이터 런타임이 있다는 뜻은 아닙니다. 정확한 목록은 도구 인벤토리와 러너 이미지 개요를 원출처로 보세요.

3. 워크플로 예시

DEVELOPER_DIR로 Xcode 26.6을 잡 전체에 고정하는 예입니다. xcodebuild -version step으로 실제 쓰인 버전을 로그에 남깁니다. scheme 이름은 프로젝트에 맞게 바꾸세요.

name: build
on: [push, workflow_dispatch]

jobs:
  ios:
    runs-on: xenoci-macos
    env:
      DEVELOPER_DIR: /Applications/Xcode_26.6.app/Contents/Developer
    steps:
      - uses: actions/checkout@v4
      - run: xcodebuild -version
      - run: xcodebuild -scheme App -destination 'generic/platform=iOS' build CODE_SIGNING_ALLOWED=NO

여러 버전을 확인하려면 matrix 대신 버전마다 잡을 나누고, 각 잡에 숫자 버전을 그대로 적습니다. 아래는 기본 Xcode(27.0) 잡과 setup-xcode로 26.6을 고정한 잡입니다.

name: xcode-versions
on: [push, workflow_dispatch]

jobs:
  xcode-default:
    runs-on: xenoci-macos
    steps:
      - uses: actions/checkout@v4
      - run: xcodebuild -version
      - run: xcodebuild -scheme App -destination 'generic/platform=iOS' build CODE_SIGNING_ALLOWED=NO

  xcode-26-6:
    runs-on: xenoci-macos
    steps:
      - uses: actions/checkout@v4
      - uses: maxim-lobanov/setup-xcode@v1
        with:
          xcode-version: "26.6"
      - run: xcodebuild -version
      - run: xcodebuild -scheme App -destination 'generic/platform=iOS' build CODE_SIGNING_ALLOWED=NO

4. 시뮬레이터를 쓰는 잡

버전 고정만으로는 시뮬레이터 런타임 요구가 인식되지 않습니다. step의 run에 -sdk iphonesimulator나 -destination 'generic/platform=iOS Simulator'를 직접 적으면 그 Xcode에 맞는 런타임을 요구하고, -destination 'platform=iOS Simulator,OS=26.5'처럼 OS를 적으면 그 값이 우선합니다. 요구가 인식됐는데 호환 런타임을 가진 호스트가 비어 있지 않으면 잡은 대기합니다. 러너 이미지 개요에 따르면 Xcode 26.6 시뮬레이터 잡의 배정부터 빌드 성공까지는 아직 검증되지 않았습니다.

5. 자주 겪는 실패

• 이미지에 없는 Xcode — 잡이 시작된 뒤 그 step에서 실패하고, 그때까지 실행한 시간은 사용량에 들어갑니다. 위 표에서 먼저 확인하세요.
• 고정하지 않은 버전 — 이미지 채널이 승격되면 기본 Xcode가 바뀌어 같은 워크플로가 다른 Xcode로 돌 수 있습니다.
• 라벨 섞기 — runs-on에 xenoci-macos 외 라벨을 함께 쓰면 XenoCI가 잡을 받지 않고, 잡은 GitHub에서 대기합니다. 이 경우 요금은 생기지 않습니다.

6. 다음에 볼 문서

Xcode 목록과 시뮬레이터 런타임은 러너 이미지 개요, 설치된 도구 전체는 도구 인벤토리, 연결 순서는 GitHub Actions 연동, 느린 잡 점검은 macOS 러너가 느릴 때 확인할 것에 있습니다.