GitHub Actions macOS Runner 2026: 원격 Mac은 어떻게 설정하나요?
GitHub는 자체 호스팅 Runner를 저장소, 조직, 기업의 세 범위에 등록할 수 있다고 안내합니다. Runner 등록 범위와 공개 저장소의 보안 경고를 확인하면, Xcode가 필요한 신뢰된 작업에는 원격 Mac을 연결할 수 있지만 공개 저장소의 신뢰할 수 없는 PR에 민감한 Runner를 노출해서는 안 됩니다. 먼저 접근 범위와 실행 조건을 제한한 뒤 서비스를 구성하고, 실제 프로젝트 빌드로 확인합니다.
GitHub Actions를 사용하면서 macOS에서 iOS 앱을 빌드해야 하는 독립 개발자에게 적합합니다.
소규모 팀에서 Runner의 접근 권한, 서비스 상태, 빌드 증거를 점검하려는 담당자도 따라 할 수 있습니다.
이미 원격 Mac이 있지만 자동화에 연결하지 않은 개발자는 상주 빌드 노드로 적합한지 판단할 수 있습니다.
GitHub Actions macOS Runner를 원격 Mac에 연결하기 전 조건을 확인합니다
이 절차는 Xcode 또는 macOS 환경이 필요한 워크플로를 대상으로 합니다. GitHub가 관리하는 Runner와의 비용 비교나 완전한 App Store 배포 절차는 다루지 않습니다. 시작 전에 저장소, 이벤트 출처, 빌드 대상, 자격 증명 사용 여부를 확인합니다.
공개 저장소에서 자체 호스팅 Runner를 써도 되나요? 공개 저장소에서 발생한 포크 PR은 신뢰할 수 없는 코드를 실행할 수 있습니다. 해당 작업이 민감한 파일이나 권한이 있는 Runner에 접근하지 못하도록 해야 합니다. 보안 경계를 분명히 만들 수 없다면 공개 PR을 해당 Runner에 배정하지 말고, 별도로 격리된 빌드 방식을 선택합니다. GitHub의 자체 호스팅 Runner 보안 안내를 먼저 검토하세요.
| 조건 | 진행 기준 | 진행을 멈추거나 바꿀 때 |
|---|---|---|
| 저장소와 등록 범위 | 한 저장소만 사용할 작업은 저장소 범위부터 검토합니다. 여러 저장소가 필요하면 조직 Runner의 접근 제한을 확인합니다. | 공개 저장소의 외부 기여 작업이 실행될 수 있고 격리할 수 없다면 민감한 Runner를 연결하지 않습니다. |
| 트리거와 권한 | 신뢰된 브랜치의 변경처럼 코드 출처를 관리할 수 있는 이벤트부터 시작합니다. | 출처를 통제하기 어려운 이벤트에 비밀 값이나 서명 권한을 제공하지 않습니다. |
| 빌드 대상 | 사용할 Xcode 프로젝트, 스킴, 시뮬레이터 또는 빌드 설정을 정합니다. | 프로젝트가 요구하는 도구를 원격 Mac에서 확인하지 못하면 등록보다 환경 준비를 먼저 합니다. |
조직이나 기업 범위로 Runner를 등록할 때는 연결된 저장소를 모두 확인해야 합니다. Runner 접근 범위 관리 문서에 따라 사용할 저장소를 제한하고, 권한 범위가 필요 이상으로 넓지 않은지 검토합니다.
GitHub Actions self-hosted runner에서 Xcode 빌드를 실행할 수 있나요? macOS Runner에 Xcode와 프로젝트가 요구하는 도구가 준비되어 있으면 가능합니다. 다만 등록만으로 Xcode나 시뮬레이터가 설치되는 것은 아닙니다. 작업은 자체 호스팅 Runner 참고 문서에 나온 실행 환경 및 레이블 조건을 확인한 뒤 연결합니다.
첫 준비 단계: macOS와 Xcode 도구 체인을 확인합니다
원격 Mac에 로그인할 수 있는지, GitHub에 연결할 네트워크가 유지되는지 확인합니다. 원격 접속이 불안정하거나 호스트를 다시 시작한 뒤 접근할 방법이 없다면, Runner 설치보다 복구 경로를 먼저 마련합니다.
터미널에서 현재 선택된 개발자 디렉터리와 Xcode 버전을 확인합니다.
xcode-select -p
xcodebuild -version
xcode-select -p 결과가 프로젝트에서 사용할 Xcode 설치 위치인지 살펴봅니다. 필요한 경우 Apple의 명령줄 도구 설정 안내에 따라 활성 개발자 디렉터리를 선택합니다. Apple은 Xcode 명령줄 도구 설치 안내도 별도로 제공합니다. 명령줄 도구만 설치된 상태와 전체 Xcode가 준비된 상태는 같지 않으므로, 프로젝트가 요구하는 SDK나 시뮬레이터를 실제로 사용할 수 있는지 확인해야 합니다.
프로젝트 파일이나 스킴이 인식되는지도 점검합니다.
xcodebuild -list -project "<프로젝트>.xcodeproj"
출력이 실패하면 Runner 등록을 진행하지 말고 프로젝트 경로, Xcode 선택 상태, 필요한 구성 요소를 먼저 바로잡습니다. 원격 Mac에서 Xcode 명령줄 빌드를 실행할 수 있는지 확인하려면 xcodebuild의 버전 확인만으로 끝내지 말고, 프로젝트의 실제 스킴을 조회하고 서명 없이 가능한 빌드도 시험합니다.
Runner를 등록하고 접근 범위를 검증합니다
저장소의 설정 화면에서 자체 호스팅 Runner 추가 절차를 시작합니다. GitHub는 등록 위치에 따라 저장소, 조직, 기업 범위를 제공합니다. 등록 위치를 선택한 뒤 화면에 표시되는 macOS용 설치 및 구성 안내를 따릅니다. Runner 응용 프로그램 구성과 서비스 설정 문서에서 현재 절차를 확인하세요.
Runner 파일은 안내된 위치에 내려받고 구성합니다. 등록 토큰이나 계정 정보는 저장소, 로그, 문서에 넣지 않습니다. 아래 표시는 형식을 설명하기 위한 자리표시자이며 실제 자격 증명이 아닙니다.
<등록 토큰>
<Runner 이름>
<필요한 레이블>
이름은 저장소와 운영 담당자가 알아볼 수 있게 정하고, 작업에서 구분해야 하는 환경이 있다면 레이블을 일관되게 지정합니다. 구성 과정에서 등록 범위나 접근 가능한 저장소를 잘못 골랐다면 온라인 상태를 확인하기 전에 설정을 되돌리고 올바른 범위로 다시 등록합니다.
GitHub Actions가 원격 Mac Runner에 연결되려면 무엇을 해야 하나요? Runner 앱을 올바른 범위에 등록하고, 원격 Mac에서 실행 중인 상태로 유지해야 합니다. GitHub 화면에서 해당 Runner가 온라인인지 확인하고, 작업의 실행 레이블이 그 Runner의 레이블과 맞는지 비교합니다. 온라인으로 표시되지 않으면 네트워크, 등록 상태, Runner 프로세스를 먼저 점검합니다.
서비스로 실행해 재시작 뒤에도 연결을 확인합니다
등록을 마친 뒤에는 GitHub의 macOS 서비스 구성 절차를 따라 Runner를 서비스로 설정합니다. 서비스 상태와 GitHub 화면의 온라인 상태를 각각 확인해야 합니다. 서비스가 설치되었다는 표시만으로 작업을 받을 수 있다고 판단하지 않습니다.
서비스 환경과 대화형 데스크톱 세션의 환경이 다를 수 있습니다. 특히 키체인, 서명 인증서, 그래픽 화면에 기대는 절차가 백그라운드에서도 동일하게 동작한다고 가정하지 않습니다. 서명이나 화면 조작이 필요한 단계가 있다면 별도 시험을 거쳐야 합니다.
원격 Mac Runner를 계속 온라인 상태로 유지하려면 어떻게 해야 하나요? 서비스로 실행하고 호스트가 다시 시작된 뒤 Runner가 복구되는지 확인합니다. 재시작 후 오프라인이라면 서비스 상태와 네트워크 연결을 확인하고, 원인을 찾기 전까지 실제 배포 작업을 배정하지 않습니다. 모니터링 및 문제 해결 안내를 참고해 로그와 상태를 함께 살펴봅니다.
신뢰된 브랜치에서 첫 Xcode 빌드를 실행합니다
처음에는 신뢰된 브랜치의 코드만 대상으로 하는 간단한 워크플로를 만듭니다. 아래 예시는 빌드 확인에 필요한 구조를 보여 줍니다. 프로젝트 경로와 스킴은 실제 저장소 값으로 바꾸며, 서명과 업로드는 이 검증에서 분리합니다.
name: macOS build
on:
push:
branches: [main]
permissions:
contents: read
jobs:
build:
runs-on: [self-hosted, macOS]
steps:
- uses: actions/checkout@v4
- name: Check Xcode
run: xcodebuild -version
- name: Build for simulator
run: >
xcodebuild
-project "<프로젝트>.xcodeproj"
-scheme "<스킴>"
-sdk iphonesimulator
-configuration Debug
CODE_SIGNING_ALLOWED=NO
build
작업의 runs-on 조건은 Runner에 지정된 레이블과 일치해야 합니다. GitHub는 워크플로에서 자체 호스팅 Runner를 선택하는 방법과 워크플로 권한 설정 문법을 안내합니다. 예시의 contents: read는 코드 확인에 필요한 최소 권한으로 시작하기 위한 설정입니다. 추가 권한이 필요한 작업이 생기면 목적을 확인한 뒤 범위를 늘립니다.
작업이 예상한 Runner에서 실행됐는지, 체크아웃이 성공했는지, xcodebuild가 프로젝트를 읽고 종료했는지 로그에서 확인합니다. 원격 Mac iOS 자동 빌드의 첫 검증은 어디까지 해야 하나요? 우선 코드 체크아웃과 시뮬레이터 대상 빌드가 재현되는지 확인합니다. 아카이브 생성, 인증서 사용, App Store Connect 업로드는 보안과 권한을 따로 검토한 다음 확장합니다.
체크리스트로 운영 투입 여부를 판정합니다
| 확인 항목 | 통과 증거 | 실패할 때의 조치 |
|---|---|---|
| Runner 연결 | GitHub에서 올바른 Runner가 온라인으로 표시됩니다. | 네트워크, 등록 범위, 서비스 실행 상태를 확인합니다. |
| 작업 배정 | 신뢰된 브랜치 작업이 의도한 macOS Runner에서 시작됩니다. | 레이블과 워크플로 조건을 맞추고 트리거 범위를 재검토합니다. |
| 빌드 확인 | 로그에서 코드 체크아웃과 실제 프로젝트의 xcodebuild 실행 결과를 추적할 수 있습니다. |
프로젝트 경로, 스킴, Xcode 선택 상태를 점검합니다. |
| 결과물 확인 | 산출물이 프로젝트가 기대한 형태인지 검토할 수 있습니다. | 빌드와 아카이브 단계를 구분해 필요한 산출물을 다시 정의합니다. |
| 복구 확인 | 서비스를 멈추거나 호스트를 재시작한 뒤 Runner가 다시 연결됩니다. | 서비스 설정과 복구 절차를 고친 뒤 운영 투입을 보류합니다. |
운영을 시작한 뒤에는 Runner 앱 업데이트, 저장소 접근 권한, 워크플로 권한을 정기적으로 살핍니다. 사용을 마친 Runner는 GitHub에서 제거하고 원격 Mac의 서비스와 등록 정보를 정리합니다. 테스트 로그에서 작업을 다시 추적할 수 없다면, 성공 표시만으로 상시 배포에 투입하지 않습니다.
개인 Mac에서 수동 빌드만 이어가면 담당자의 사용 가능 시간에 작업이 묶이고, 로컬 환경 변화가 결과에 섞이며, 다른 작업과 자원을 나눠 써야 할 수 있습니다. 반대로 원격 Mac을 자체 호스팅 Runner로 쓰면 서비스 상태와 접근 권한을 직접 관리해야 하므로, 보안 경계와 복구 절차를 운영할 준비가 된 경우에 적합합니다. 이미 상주 macOS 빌드 환경이 필요하다고 판단했다면 KuzCloud 원격 Mac 이용 안내를 검토해 접속 방식과 운영 조건이 요구 사항에 맞는지 확인하세요. 지역별 이용 조건을 함께 살펴보려면 국내 요금 안내를 확인한 뒤 선택하면 됩니다.
맥 빌드 환경이 필요하다면 쿠즈클라우드에서 시작해 보세요
쿠즈클라우드는 전용 맥 미니를 제공해 실제 맥 환경에서 빌드와 테스트를 실행할 수 있도록 지원합니다.
가상화로 인한 성능 저하 없이 전용 하드웨어와 관리자 권한으로 필요한 개발 도구를 자유롭게 구성할 수 있습니다.