GitHub Actions 자체 호스팅 러너: 2026 원격 맥 배포

SSH 연결은 되지만 워크플로가 실행되지 않고, 재부팅 뒤 러너가 오프라인으로 표시됩니다.

가장 빠른 해결법은 관리자 권한이 있는 실제 애플 실리콘 원격 맥에 러너를 등록한 뒤 시스템 서비스로 상주시키고, 라벨 라우팅·권한 격리·서명 검증·재부팅 복구까지 확인하는 것입니다. 공개 저장소의 신뢰하지 않는 풀 리퀘스트는 지속형 러너에 직접 보내지 않아야 합니다.

이 글은 아이오에스 또는 맥오에스 프로젝트에 지속적인 빌드 노드를 추가하려는 개발자, 조직 단위 러너와 비밀 키를 관리하는 데브옵스 엔지니어, 지속 캐시나 사내 네트워크 접근이 필요한 팀을 위한 안내서입니다. 단순히 화면에 Online이 표시되는 상태를 배포 완료로 보지 않습니다.

원격 맥을 생산용 빌드 노드로 써도 될까요?

가능합니다. 다만 호스트가 계속 켜져 있어야 하고, 러너 설치 권한이 있어야 하며, 워크플로가 사용하는 저장소와 패키지 서버에 외부 네트워크로 접근할 수 있어야 합니다. 깃허브는 저장소, 조직, 기업 단위로 자체 호스팅 러너를 등록할 수 있다고 안내합니다. 여러 저장소가 함께 사용할 노드라면 조직 단위 등록부터 검토하는 편이 관리에 유리합니다. (깃허브 러너 추가 안내)

먼저 아래 항목을 확인합니다.

• [ ] 관리자 계정으로 원격 맥에 로그인할 수 있습니다.
• [ ] 프로세서가 애플 실리콘인지 확인했습니다.
• [ ] 필요한 맥오에스와 엑스코드 조합을 애플의 공식 시스템 요구 사항에서 확인했습니다.
• [ ] 작업 파일과 캐시를 저장할 디스크 여유 공간을 점검했습니다.
• [ ] 저장소, 패키지 저장소, 서명 관련 서비스로 나가는 네트워크가 허용됩니다.
• [ ] 러너 서비스가 중단되었을 때 확인할 로그 위치를 알고 있습니다.

애플 플랫폼 빌드는 운영체제와 엑스코드의 조합에 영향을 받습니다. 최신 엑스코드의 지원 범위는 맥오에스 버전에 따라 달라지며, 특정 플랫폼 개발에는 애플 실리콘이 요구될 수 있습니다. 따라서 “맥오에스가 설치되어 있다”는 조건만으로는 충분하지 않습니다. 프로젝트가 요구하는 에스디케이와 시뮬레이터를 먼저 확인해야 합니다.

저장소 수준과 조직 수준 중 무엇부터 시작해야 하나요?

한 프로젝트의 빌드와 서명을 먼저 확인한다면 저장소 수준에서 시작합니다. 여러 저장소가 같은 맥오에스 빌드 노드를 사용하고, 라벨과 접근 정책을 중앙에서 관리해야 한다면 조직 수준으로 옮깁니다. 조직 단위 러너는 여러 저장소에서 사용할 수 있지만, 조직 소유자 권한과 접근 정책 검토가 필요합니다.

KVMFLUX의 원격 맥 개발 환경 설정 안내를 먼저 확인하면 에스에스에이치 접속, 사용자 계정, 개발 도구 설치 범위를 나누어 준비하는 데 도움이 됩니다.

설치 계정과 권한 경계를 먼저 나눕니다

일상 개발에 사용하는 계정으로 러너를 실행하지 않는 편이 안전합니다. 별도의 시아이 계정을 만들고, 개인 문서·브라우저 로그인·개발용 에스에스에이치 키·소스 저장 폴더가 빌드 작업과 섞이지 않도록 분리합니다.

지속형 러너는 작업이 끝난 뒤에도 호스트와 작업 디렉터리가 남습니다. 따라서 한 번 실행된 스크립트가 파일, 환경 변수, 캐시, 임시 키를 남길 수 있다는 점을 전제로 설계해야 합니다. 특히 공개 저장소의 포크가 만든 풀 리퀘스트는 악성 코드를 실행할 수 있으므로, 깃허브도 공개 저장소에서 자체 호스팅 러너를 사용하는 방식을 권장하지 않습니다. (깃허브 보안 사용 안내)

권한은 다음처럼 나누는 것이 좋습니다.

• 빌드 전용 계정에는 필요한 폴더만 읽고 쓸 수 있게 합니다.
• 배포용 인증서와 프로비저닝 파일은 저장소 파일에 넣지 않습니다.
• GITHUB_TOKEN 권한은 기본 읽기 중심으로 두고, 필요한 작업에만 높입니다.
• 서명과 배포 작업은 보호된 환경과 승인 절차를 사용합니다.
• 조직 러너를 쓴다면 러너 그룹에서 접근 가능한 저장소를 제한합니다.

주의: 비밀 값이 로그에 출력되면 자동 가림이 항상 보장되지 않습니다. 로그를 삭제하는 것만으로 끝내지 말고 노출된 키를 폐기하고 다시 발급해야 합니다.

첫 배포는 깃허브 화면에서 생성한 명령으로 진행합니다

러너 버전과 등록 토큰을 본문에 고정하지 마십시오. 깃허브는 점진적으로 새 러너를 배포하므로 저장소나 조직 화면에 표시되는 다운로드 명령이 공식 기준입니다. 공식 릴리스 페이지에서도 새 릴리스가 모든 조직과 저장소에 동시에 표시되지 않을 수 있다고 안내합니다. (러너 공식 릴리스)

원격 맥에서 다음 순서로 진행합니다.

• [ ] 깃허브에서 저장소 또는 조직의 설정 화면을 엽니다.
• [ ] 작업 메뉴에서 러너 추가를 선택합니다.
• [ ] 맥오에스와 실제 아키텍처를 선택합니다.
• [ ] 화면에 표시된 다운로드와 압축 해제 명령을 그대로 실행합니다.
• [ ] 화면에서 생성된 주소와 일회성 토큰으로 설정 스크립트를 실행합니다.
• [ ] 러너 이름과 용도를 구분할 수 있는 라벨을 지정합니다.
• [ ] 설정이 끝난 뒤 연결 상태를 확인합니다.

명령은 다음처럼 자리 표시자로 이해하면 됩니다. 실제 주소, 토큰, 다운로드 파일명은 깃허브 설정 화면의 값을 사용해야 합니다.

mkdir actions-runner
cd actions-runner
# 깃허브 화면에서 생성한 애플 실리콘용 다운로드 명령 실행
tar xzf ./다운로드된_러너_파일.tar.gz
./config.sh --url 저장소_또는_조직_주소 --token 일회성_토큰
./run.sh

등록 화면은 운영 범위에 따라 달라집니다. 저장소 단위 등록은 특정 프로젝트에만 연결되고, 조직 단위 등록은 여러 저장소가 사용할 수 있습니다. 러너 이름에는 운영 환경과 용도를 드러내는 표현을 넣고, 개인 이름이나 비밀 정보를 포함하지 않는 편이 좋습니다.

서비스 상주와 라벨 라우팅을 검증합니다

터미널에서 ./run.sh를 실행한 상태만으로는 배포가 끝난 것이 아닙니다. 에스에스에이치 세션을 닫으면 프로세스가 종료될 수 있고, 호스트가 재부팅되면 다시 시작되지 않을 수 있습니다.

맥오에스에서는 러너를 등록한 뒤 설치 디렉터리에서 서비스 명령을 실행합니다.

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

깃허브 공식 문서에 따르면 맥오에스 서비스는 시작 시 자동으로 러너 애플리케이션을 실행하도록 구성할 수 있으며, 상태 확인에는 svc.sh status를 사용할 수 있습니다. (맥오에스 서비스 설정 안내)

서비스 설치 후에는 다음 순서로 증거를 남깁니다.

• [ ] svc.sh status가 실행 중인 상태를 보여 줍니다.
• [ ] 에스에스에이치 연결을 끊은 뒤 깃허브에서 러너가 계속 유휴 상태인지 확인합니다.
• [ ] 원격 맥을 재부팅합니다.
• [ ] 시스템 서비스와 러너 상태를 다시 확인합니다.
• [ ] 테스트 워크플로가 실제 노드에서 실행되는지 확인합니다.

깃허브 액션이 애플 실리콘 원격 맥을 정확히 선택하게 하려면 어떻게 하나요?

러너에 사용자 지정 라벨을 붙이고 워크플로의 runs-on에 운영체제, 아키텍처, 용도를 함께 지정합니다.

jobs:
  build:
    runs-on: [self-hosted, macOS, ARM64, ios-build]
    steps:
      - uses: actions/checkout@v4
      - run: uname -m
      - run: sw_vers
      - run: xcodebuild -version

깃허브는 runs-on의 라벨과 그룹이 일치하는 온라인·유휴 러너를 찾아 작업을 배정합니다. 일치하는 노드가 없으면 작업은 대기 상태로 남습니다. 그러므로 macOS만 지정하지 말고 애플 실리콘 여부와 빌드 용도를 구분하는 라벨을 추가해야 합니다. (자체 호스팅 러너 참고 문서)

이 단계에서 “러너 연결 성공”과 “프로젝트 빌드 성공”을 분리해 확인합니다. 먼저 아키텍처와 시스템 버전을 로그에 남깁니다. 그다음 의존성 설치, 캐시 복원, 테스트, 아카이브, 서명, 업로드를 한 단계씩 추가합니다. 엑스코드 변경 자체는 별도 주제로 다루고, 여기서는 현재 프로젝트가 요구하는 도구 체인을 실제 노드에서 찾는지만 검증합니다.

서명 파일과 작업 디렉터리를 운영 기준으로 고정합니다

지속형 원격 맥에서는 작업 디렉터리가 자동으로 깨끗해지지 않습니다. 빌드가 끝난 뒤 소스, 인증서, 임시 프로비저닝 파일, 패키지 캐시가 남는지 확인하고 정리 규칙을 정해야 합니다.

권장하는 운영 흐름은 다음과 같습니다.

• 체크아웃 전 기존 작업 디렉터리의 잔여 파일을 점검합니다.
• 빌드와 테스트에 필요한 캐시만 유지합니다.
• 서명 키는 보호된 환경 변수나 비밀 저장소에서 주입합니다.
• 변환된 인증서와 임시 파일도 별도 비밀 값으로 등록합니다.
• 작업 종료 뒤 임시 키와 생성된 프로비저닝 파일을 삭제합니다.
• 배포 작업은 보호된 브랜치와 승인된 환경에서만 실행합니다.
• 로그에 인증서 내용, 토큰, 키 경로가 출력되지 않는지 검토합니다.

깃허브는 비밀 값에 최소 권한을 적용하고, 민감한 값은 워크플로 파일에 평문으로 저장하지 말라고 안내합니다. 서드파티 액션과 셸 스크립트가 데이터를 외부로 보내지 않는지도 직접 검토해야 합니다.

경험: 서명 작업이 한 번 성공했더라도 배포 권한이 과도하면 실패한 워크플로의 디버깅 과정에서 민감한 파일이 남을 수 있습니다. 테스트 브랜치에는 개발용 서명 자격만 연결하고, 실제 배포 자격은 별도 승인 단계에서만 주입하십시오.

오프라인 상태와 장기 운영을 점검합니다

원격 맥 러너가 오프라인으로 표시되면 어디부터 봐야 하나요?

오프라인은 호스트가 꺼졌거나, 러너 애플리케이션이 실행되지 않거나, 깃허브와 통신하지 못하는 상태를 뜻합니다. 먼저 원격 접속 가능 여부를 확인한 뒤 서비스 상태, 러너 로그, 네트워크 순서로 좁혀 가야 합니다. 깃허브는 config.sh --check로 필요한 네트워크 서비스 접근을 점검하는 방법을 제공합니다. (러너 모니터링과 문제 해결)

./svc.sh status
./config.sh --check --url 저장소_또는_조직_주소 --pat 점검용_토큰

점검용 토큰은 필요한 범위로 제한하고, 명령 기록이나 셸 로그에 남지 않게 관리합니다. 결과가 실패하면 설치 디렉터리의 _diag 로그에서 실패한 서비스와 인증서, 프록시, 방화벽 문제를 확인합니다. TLS 검증을 끄는 방식은 임시 시험 외에는 사용하지 않는 편이 안전합니다.

장기 운영에서는 다음 항목을 정기적으로 확인합니다.

• [ ] 깃허브 화면의 러너 상태가 유휴 또는 실행 중인지 확인합니다.
• [ ] 시스템 서비스가 재부팅 뒤 다시 올라오는지 확인합니다.
• [ ] _diag 폴더의 러너와 작업 로그를 보존하고 회전합니다.
• [ ] 디스크 사용량과 캐시 정리 결과를 확인합니다.
• [ ] 러너 자동 업데이트 로그를 확인합니다.
• [ ] 맥오에스와 엑스코드 업데이트는 유지보수 시간에 따로 진행합니다.
• [ ] 실패 작업 재실행, 노드 중지, 재부팅 복구를 실제로 시험합니다.

러너 애플리케이션은 자동으로 업데이트될 수 있지만 운영체제와 개발 도구까지 함께 업데이트해 주지는 않습니다. 일정 기준보다 오래된 러너는 작업을 처리하지 못할 수 있으므로, 자동 업데이트 로그를 운영 점검 항목에 넣어야 합니다.

자체 호스팅 러너를 공개 저장소에 안전하게 연결할 수 있나요?

신뢰하지 않는 코드가 실행될 가능성이 있다면 지속형 러너에 직접 연결하지 않는 것이 원칙입니다. 공개 저장소의 포크 풀 리퀘스트는 호스트에 남아 있는 파일과 자격 증명에 접근할 위험이 있으므로, 비공개 저장소 중심으로 운영하고, 공개 코드 검증이 필요하면 격리된 일회성 실행 환경을 별도로 설계해야 합니다.

현재 윈도우 또는 리눅스 서버에서 맥오에스 빌드를 우회하면 애플 전용 도구 체인 접근이 제한되고, 가상화 환경은 성능과 호환성, 유지보수 조건을 따로 확인해야 합니다. 직접 맥을 구매하면 사용하지 않는 기간에도 비용과 관리 책임이 남습니다. 이런 조건에서 KVMFLUX의 원격 맥은 장비 구매 없이 맥오에스 빌드 노드를 확보하고, 필요한 기간 동안만 운영하려는 경우에 더 현실적인 선택이 될 수 있습니다.

먼저 KVMFLUX의 원격 맥 이용 사례와 임대 주문 절차를 확인한 뒤, 이 글의 점검 목록대로 관리자 권한, 애플 실리콘 도구 체인, 서비스 자동 실행, 라벨 라우팅, 서명 보안과 재부팅 복구를 직접 검증하십시오.