GitHub Actions 자체 호스팅 Mac Runner는 어떻게 배포하나요? 2026

터미널을 닫으면 Mac Runner가 멈추고, 작업이 대기열에 남아 있습니다.
macOS가 필요한 작업이라면 원격 Mac을 GitHub Actions 자체 호스팅 Runner로 등록한 뒤, 서비스 실행과 작업 흐름 검증까지 마치세요.

이 글은 Mac에서 iOS 또는 macOS 프로젝트를 빌드하는 독립 개발자, 고객 프로젝트용 빌드 환경이 필요한 프리랜서, Runner의 운영 책임과 저장소 권한을 검토하는 소규모 원격 팀을 위한 안내입니다. 일반적인 교차 플랫폼 작업만 있다면 Mac Runner를 추가할 필요가 없습니다.

배포 전, 자체 호스팅 Mac Runner가 필요한지 판단합니다

프로젝트에서 macOS 전용 도구나 빌드 환경이 실제로 필요한지 먼저 확인하세요. 단지 GitHub Actions를 쓴다는 이유만으로 Mac을 준비할 필요는 없습니다. GitHub 호스팅 Runner는 GitHub가 제공하는 실행 환경이고, 자체 호스팅 Runner는 호스트와 설치된 소프트웨어를 직접 관리하는 방식입니다. 자체 호스팅 Runner의 운영 책임과 동작 방식은 GitHub 문서에서 확인할 수 있습니다.

설치 전에 Runner의 시스템 요구 사항도 확인하세요. 운영체제와 아키텍처가 맞더라도 프로젝트 의존성, 권한, 네트워크 접근까지 자동으로 해결되는 것은 아닙니다. 필요한 기능이 자체 Mac에만 있다면 자체 호스팅 Runner를 검토하고, 그렇지 않다면 현재 제공되는 호스팅 환경에서 먼저 실행해 보세요.

준비 단계: 저장소 범위와 호스트 조건을 정합니다

Runner를 저장소 하나에서만 사용할지, 조직의 여러 저장소에서 사용할지 먼저 결정합니다. 설정 범위는 접근 권한과 작업을 받을 수 있는 저장소에 영향을 줍니다. 해당 저장소나 조직의 Runner 설정을 관리할 권한이 있는지도 확인하세요.

원격 Mac에는 프로젝트를 빌드하는 데 필요한 작업 디렉터리와 의존성을 준비합니다. Xcode 등 실제로 필요한 도구가 설치되어 있는지 확인하고, 호스트가 작업 중 절전이나 로그아웃으로 연결을 끊지 않는지도 살펴보세요. 회사나 고객의 저장소를 다룬다면 고객 정책이 자체 호스팅 실행을 허용하는지 먼저 확인해야 합니다.

Runner를 추가할 범위를 정했다면 GitHub의 Runner 추가 안내를 열고 해당 범위에서 macOS와 호스트 아키텍처를 선택합니다. GitHub 화면이 제공하는 안내는 등록 범위와 당시 화면에 따라 달라질 수 있으므로, 예전 블로그의 명령을 그대로 복사하지 마세요.

등록 단계: 현재 설정 화면의 명령을 사용합니다

GitHub 설정에서 macOS와 실제 호스트에 맞는 아키텍처를 고른 뒤, 화면에 표시되는 다운로드 및 구성 절차를 원격 Mac에서 실행합니다. 이때 등록 토큰은 공식 설정 흐름에서 제공된 일회성 절차에 따라 사용하세요. 토큰을 저장소에 커밋하거나, 문서와 공개 로그에 붙여 넣으면 안 됩니다.

GitHub가 생성한 지침으로 Runner를 등록한 다음, 화면의 상태와 호스트의 Runner 디렉터리를 확인합니다. 구성 명령을 바꾸거나 토큰이 포함된 줄을 재사용해야 하는 상황이면 작업을 멈추고 해당 설정 화면에서 새 지침을 확인하세요. 등록이 성공했다는 메시지만으로 실제 작업을 받을 준비가 끝난 것은 아닙니다.

자체 호스팅 Runner의 등록 토큰이나 작업용 비밀 정보를 Runner의 코드 저장소에 두지 마세요. 저장소에 접근할 수 있는 사람과 워크플로가 실행할 수 있는 코드를 함께 검토해야 합니다.

상시 실행 단계: 터미널 프로세스와 macOS 서비스를 구분합니다

Runner를 터미널에서 직접 실행하면 그 프로세스가 실행되는 동안에만 작업을 받을 수 있습니다. 터미널을 닫거나 세션이 종료되면 Runner도 중단될 수 있습니다. 지속적인 실행이 필요하다면 GitHub의 macOS 서비스 구성 절차에 따라 서비스를 설치하고 시작하세요.

Runner 디렉터리에서 GitHub가 안내하는 서비스 스크립트를 사용합니다. 아래 명령은 절차의 형태를 설명하는 예시입니다. 실제 실행 전에 설치한 Runner의 안내와 스크립트를 확인하세요.

./svc.sh install
./svc.sh start
./svc.sh status

정상 여부는 명령 실행 자체가 아니라 서비스 상태와 GitHub 설정 화면의 Runner 상태를 함께 확인해 판단합니다. 서비스가 실행 중이어도 호스트의 네트워크가 끊기거나 프로젝트 도구에 접근할 수 없다면 작업은 실패할 수 있습니다. GitHub의 Runner 모니터링 및 문제 해결 안내에서 로그와 상태 확인 방법을 참고하세요.

등록 직후에는 터미널을 열어 둔 채 작업을 실행해 보고, 그다음 서비스를 통해 실행되도록 전환합니다. 마지막으로 Mac을 재시작하고 Runner가 다시 온라인으로 표시되는지 확인하세요. 재시작 전의 성공만으로 개입 없이 계속 실행되는 환경이라고 판단하면 안 됩니다.

작업 흐름 검증 단계: 대상 레이블과 실제 빌드를 확인합니다

워크플로가 의도한 Runner로 배정되도록 runs-on에 등록된 Runner의 레이블을 지정합니다. 기본 레이블은 설정에 따라 다를 수 있으니 GitHub 화면에 표시된 값을 확인하고, 문서의 자체 호스팅 Runner 레이블 안내와 대조하세요.

예를 들어 Runner 화면에 아래 레이블이 실제로 표시될 때에만 다음과 같이 지정합니다.

jobs:
  macos-check:
    runs-on: [self-hosted, macOS, ARM64]
    steps:
      - uses: actions/checkout@v4
      - run: echo "Runner 작업 확인"

예시의 ARM64는 모든 Mac에 적용되는 값이 아닙니다. 등록된 아키텍처와 레이블이 다르면 해당 Runner를 선택하지 못하거나 다른 환경에서 작업이 실행될 수 있습니다. 화면에 표시된 레이블과 워크플로의 지정이 정확히 일치하는지 확인하세요.

첫 검증은 비밀 정보나 고객 데이터를 사용하지 않는 낮은 위험의 반복 가능한 작업으로 진행합니다. 확인할 항목은 다음과 같습니다.

• 작업이 의도한 Runner에 배정되는지 확인합니다.
• GitHub 작업 로그에서 실행과 종료 상태를 확인합니다.
• 필요한 산출물이 예상한 방식으로 생성되고 전달되는지 확인합니다.
• 프로젝트가 요구하는 macOS 도구를 실제 빌드 과정에서 호출해 봅니다.
• 서비스 실행과 호스트 재시작 뒤에도 Runner가 다시 작업을 받는지 확인합니다.

간단한 명령이 성공했다고 해서 모든 프로젝트의 macOS CI 빌드가 호환된다고 볼 수는 없습니다. 프로젝트별 서명, 의존성, 비밀 정보, 캐시 설정을 반영한 실제 작업 흐름으로 끝까지 검증하세요.

운영 단계: 코드 신뢰도와 호스트 상태를 함께 관리합니다

자체 호스팅 Runner는 작업을 실행하는 호스트입니다. 지속적으로 사용하는 호스트에는 작업 환경이나 데이터가 남을 수 있습니다. 특히 신뢰하지 않는 코드가 실행되면 호스트의 파일, 실행 권한, 비밀 정보에 위험이 생길 수 있습니다. GitHub의 안전한 사용 지침은 공개 저장소의 기여 코드와 워크플로 권한을 검토하도록 안내합니다.

공개 저장소의 외부 기여 작업을 중요한 데이터나 자격 증명이 있는 지속형 Mac에 바로 배정하지 마세요. 워크플로를 실행할 수 있는 사람과 이벤트를 검토하고, 비밀 정보는 꼭 필요한 작업에만 제한하세요. 신뢰 경계를 분리하기 어렵다면 해당 작업에 자체 호스팅 Runner를 사용하지 않는 편이 안전합니다.

운영을 시작한 뒤에는 호스트의 macOS와 프로젝트 도구를 관리하고, 업데이트나 네트워크 변경 뒤 Runner가 다시 온라인인지 확인합니다. 작업이 대기열에 머무르면 레이블 불일치, 서비스 중단, 호스트 접근성, 필요한 도구의 변경을 순서대로 점검하세요. 원격 Mac 환경의 지역과 접근 조건을 살펴볼 때도 Runner 실행에 필요한 네트워크 경로와 실제 작업 위치를 함께 고려해야 합니다.

자주 묻는 질문

GitHub Actions에 macOS 자체 호스팅 Runner를 등록하려면 어디서 시작하나요?

저장소 설정이나 조직 설정에서 Runner를 추가할 범위를 먼저 정하고, 해당 화면에서 macOS와 실제 호스트에 맞는 아키텍처를 선택합니다. 화면이 제공하는 다운로드와 등록 명령을 원격 Mac에서 실행하면 됩니다. 등록 토큰은 화면에서 발급된 절차 안에서만 사용하고, 저장소 파일이나 공개 로그에 넣지 마세요.

터미널을 닫아도 Mac Runner가 작업을 계속 받나요?

Runner를 터미널에서 직접 실행한 상태라면 해당 프로세스가 끝난 뒤 작업을 받을 수 없습니다. macOS에서 GitHub가 안내하는 서비스 설정을 마치고 서비스를 시작해야 터미널 창과 별도로 동작합니다. 설정 뒤에는 서비스 상태와 GitHub의 Runner 화면을 확인하고, 호스트를 다시 시작한 뒤에도 온라인으로 표시되는지 점검하세요.

Mac에서 자체 호스팅 Runner를 로그인할 때마다 자동 실행하려면 어떻게 하나요?

로그인할 때마다 터미널에서 Runner를 수동으로 실행하는 대신, Runner 디렉터리의 서비스 스크립트를 사용해 설치하고 시작합니다. 명령과 필요한 권한은 설치한 Runner 버전과 GitHub 안내에 맞춰야 합니다. 설치 후 서비스 상태를 확인하고, 재시작 검증까지 통과해야 자동 실행 구성이 실제로 동작한다고 판단할 수 있습니다.

공개 저장소의 외부 Pull Request를 지속형 Mac Runner에서 처리해도 되나요?

외부 기여자의 코드는 호스트에 접근하거나 남아 있는 자격 증명과 작업 환경을 악용할 위험이 있습니다. 따라서 신뢰할 수 없는 공개 Pull Request 작업을 중요한 데이터와 비밀 정보가 있는 지속형 Runner에 직접 배정하지 않는 편이 안전합니다. 저장소 권한과 비밀 정보 노출 범위를 먼저 점검하고, 격리된 실행 환경을 선택하세요.

노트북에서 직접 Runner를 운영하면 이동 중 장비의 전원과 연결 상태를 관리해야 하고, 장비 분실이나 환경 변경 때 개발 환경을 다시 구성해야 합니다. 반면 일반적인 호스팅 환경만으로는 프로젝트가 요구하는 Mac 도구나 직접 관리하는 환경을 충족하지 못할 수 있습니다. 프로젝트가 자체 호스팅 Runner 검증을 통과했고 원격 Mac이 필요하다면, Mac 환경 선택 기준을 살펴보고 OnceMac의 접근 방식과 이용 주기가 작업 흐름에 맞는지 확인하세요. 장기적이고 지속적인 고부하 작업이나 물리 장비 연결이 필수라면 직접 보유한 Mac이 더 적합할 수 있습니다.

자주 묻는 질문