GitHub Actions 자체 호스팅 Mac Runner 재시동 후 오프라인이면? 2026 문제 해결 안내

재시동 뒤 Offline은 왜 표시될까요?

GitHub의 Offline 표시는 단일 원인을 뜻하지 않습니다. 공식 안내는 호스트가 오프라인이거나 Runner 애플리케이션이 실행되지 않았거나 GitHub와 통신할 수 없는 경우를 구분합니다. 따라서 GitHub 화면만 보고 등록 오류로 판단하지 말고, 원격 접속 결과와 Mac의 재시동 기록을 함께 대조해야 합니다. GitHub의 Runner 상태 및 문제 해결 안내는 이 원인들을 구분해 점검하도록 안내합니다.

먼저 다음 항목을 확인합니다.

• [ ] Mac이 켜져 있고 원격 관리 경로에서 접근 가능한지 확인합니다.
• [ ] 화면 공유나 SSH 등 팀에서 쓰는 관리 경로가 응답하는지 확인합니다.
• [ ] 접근할 수 없다면 전원, 부팅, 네트워크, 현장 또는 데이터센터 운영 기록을 확인합니다.
• [ ] Mac은 접근되지만 GitHub에서는 Offline이라면 Runner 서비스 상태를 확인합니다.

호스트에 접근할 수 없는 상태에서 Runner를 재등록해도 호스트 장애는 해결되지 않습니다. 반대로 호스트에 접속할 수 있다고 해서 Runner 서비스나 GitHub 통신까지 정상이라는 뜻도 아닙니다.

macOS에서 Runner 서비스가 시작됐는지 확인하려면

Runner가 설치된 디렉터리에서 GitHub가 제공하는 ./svc.sh status로 서비스 상태를 확인합니다. 서비스가 설치되어 있고 중지된 것이 확인되면 ./svc.sh start로 시작한 뒤, 상태와 GitHub의 Runner 화면을 다시 대조합니다. 서비스 설치와 상태 확인 절차는 GitHub의 macOS Runner 서비스 구성 문서에 설명되어 있습니다.

macOS에서는 프로세스가 로그인한 사용자 세션에 속하는지, 시스템 수준 서비스로 실행되는지를 구별해야 합니다. Apple 문서에 따르면 LaunchAgent는 사용자 환경과 연결되고 LaunchDaemon은 시스템 서비스 맥락에서 동작합니다. 로그인한 뒤에만 시작되는 프로세스를 시스템 재시동 후에도 자동 복구되는 서비스로 간주하지 마세요. Apple의 서비스 관리 문서를 확인하고, 실제 설치 방식과 팀의 무인 운영 요건이 맞는지 살펴봅니다.

• [ ] ./svc.sh status 결과가 현재 서비스 상태와 일치하는지 확인합니다.
• [ ] 서비스가 설치되지 않았거나 시작에 실패했다면 설치 및 서비스 로그를 확인합니다.
• [ ] 사용자 로그인 여부에 따라 동작이 달라지는지 확인합니다.
• [ ] 상태 변경 후 GitHub Runner 화면에서도 Online 전환 여부를 확인합니다.

Runner 프로세스를 터미널에서 직접 실행해 Online으로 만드는 것은 원인 분리에 도움이 될 수 있지만, 재시동 뒤 자동 복구가 확인됐다는 증거는 아닙니다. 운영 서비스의 실행 방식으로 다시 검증해야 합니다.

프로세스는 실행 중인데 계속 오프라인이면

프로세스가 살아 있어도 DNS 조회, 프록시 설정, TLS 연결 또는 GitHub 서비스 접근이 실패하면 Runner는 연결되지 않을 수 있습니다. 일반적인 웹사이트가 열리는지만 확인하는 것으로는 충분하지 않습니다. Runner가 실제로 필요한 서비스에 연결되는지 검사하고, 실패 항목을 DNS·프록시·TLS·방화벽 정책별로 분류합니다.

GitHub의 Runner 문제 해결 문서에는 연결 점검 방향과 진단 정보 확인 방법이 안내되어 있습니다. Runner 디렉터리의 진단 로그를 확인하고, 로그에서 연결 실패가 발생한 시각과 대상 서비스를 찾아 네트워크 담당자에게 전달합니다. 프록시를 사용하는 환경은 자체 호스팅 Runner의 프록시 설정 문서와 실제 환경 변수를 대조합니다. 워크플로 진단이 더 필요하면 디버그 로깅 안내에 따라 필요한 로그를 켜고 실패 구간을 좁힙니다.

• [ ] Mac의 DNS 결과와 Runner 진단 로그의 연결 오류를 비교합니다.
• [ ] 프록시를 쓰는 경우 Runner 프로세스에도 올바른 설정이 전달되는지 확인합니다.
• [ ] TLS 인증서 체인과 네트워크 정책을 점검합니다.
• [ ] TLS 검증을 끄는 방식으로 우회하지 않습니다. 원인과 신뢰 체인을 바로잡은 뒤 다시 검사합니다.

Runner가 Online이어도 특정 워크플로 작업을 받을 수 있다는 보장은 없습니다. runs-on에 지정한 라벨이 Runner에 실제로 붙어 있는지, 작업이 지정한 Runner group에 접근 가능한지, 해당 저장소의 사용 권한이 허용되는지 확인합니다. GitHub는 작업별 Runner 선택 방식에서 라벨과 그룹을 이용한 작업 배정을 설명합니다. 라벨은 Runner 라벨 관리 문서, 그룹 접근은 Runner group 권한 문서와 대조합니다.

• [ ] 워크플로의 runs-on 값과 Runner 라벨이 일치하는지 확인합니다.
• [ ] 작업이 지정한 Runner group에 해당 저장소의 접근 권한이 있는지 확인합니다.
• [ ] 온라인 Runner가 조건에 맞지 않으면 워크플로와 권한 설정을 수정합니다.
• [ ] 조건을 바꾼 뒤 실제 작업이 해당 Runner에서 실행되는지 확인합니다.

등록 기록과 Mac 서비스가 서로 다를 때

GitHub에 보이는 Runner 이름, Mac에서 실행 중인 서비스, 현재 설정 파일의 대상을 서로 비교합니다. 사용하지 않는 예전 기록이 남았거나 서비스가 중복으로 실행되면 화면의 상태와 실제 노드가 혼동될 수 있습니다. GitHub의 서비스 구성 절차를 기준으로 현재 서비스와 등록 대상을 확인하세요.

증거 없이 등록을 해제하고 다시 설정하면 기존 원인을 가리고, 잘못된 노드를 추가로 남길 수 있습니다. 서비스가 정상이고 네트워크도 통하는데 등록 정보 자체가 손상된 정황이 있을 때만 등록 정리를 검토합니다. 정리 전에는 어떤 Runner가 어떤 Mac에 해당하는지 기록하고, 작업 라우팅과 권한이 의도대로 유지되는지도 확인합니다.

복구를 결정할 때는 표시 상태와 기능 검증을 분리합니다. 아래 조건에 따라 다음 조치를 고릅니다.

• Mac에 접근할 수 없으면 Runner를 재등록하지 말고 전원·부팅·네트워크 문제부터 해결합니다.
• Mac은 접근되지만 서비스가 중지됐다면 서비스 구성과 실행 맥락을 확인하고, 시작 후 상태를 다시 대조합니다.
• 서비스가 실행 중인데 Offline이면 DNS·프록시·TLS·진단 로그에서 통신 실패를 찾습니다.
• Runner가 Online인데 작업이 대기 중이면 라벨·그룹·저장소 접근 조건을 확인합니다.
• 위 항목이 정상이어도 등록 불일치가 확인되면 현재 서비스와 Runner 기록을 대조한 다음에만 재구성을 검토합니다.

다음으로 프로덕션 서명 자산을 사용하지 않는 대표 작업을 실행합니다. 작업이 실제 Runner에 배정되는지, 체크아웃한 작업공간과 필요한 도구에 접근하는지, 실행 결과와 로그가 GitHub로 돌아오는지 확인합니다. 빌드가 필요한 팀은 변경 영향이 제한된 검증 빌드까지 통과시킨 뒤 팀의 배포 승인 절차를 적용합니다. Online 표시만으로 iOS 빌드나 배포가 복구됐다고 판단하지 않습니다.

이미 보유한 Mac을 직접 관리하면 장비 수명주기와 현장 복구, 사용자 세션 및 네트워크 구성을 팀이 맡아야 합니다. 다른 클라우드나 가상 환경은 실제 Mac 기반 작업 요건과 맞는지, 그리고 운영 경계를 충족하는지 별도 검증이 필요합니다. 재시동 뒤 원격 복구가 불확실한 노드를 임시 검증이나 변동성 있는 작업에 쓰려면, 맥 미니 대여 조건과 가격 정보와 MESHLAUNCH의 원격 Mac 제공 정보를 현재 구매 방식과 나란히 확인할 수 있습니다. 다만 장기간의 상시 고부하 운영이나 물리 인터페이스 접근이 중요하다면 직접 구매가 더 적합할 수 있습니다. 어떤 방식을 택하든 실제 서비스 복구 절차와 검증 가능한 운영 정보를 확인한 뒤 생산 작업을 맡기세요.