GitLab Runner macOS 재시동 후 오프라인? 2026 기업 복구 가이드

Mac의 전원 상태와 Runner의 작업 가능 상태는 같은 의미가 아닙니다. 최소한 다음 상태를 따로 기록해야 합니다.

따라서 먼저 GitLab 화면의 Runner 상태, 현재 로그인 사용자, 서비스 로딩 결과를 저장합니다. 세 항목을 남기지 않고 다시 설치하면 잘못된 계정에 새 설정을 만들거나 기존 서비스를 중복 등록할 수 있습니다.

Apple은 launchd 작업을 사용자 영역과 시스템 영역으로 나누어 설명합니다. Apple의 launchd 작업 문서와 Agent 및 Daemon 구분 문서를 기준으로 보면, 사용자 세션이 필요한 Runner를 시스템 서비스로 단순 이전하는 것은 같은 기능의 복제가 아닙니다.

사용자 로그인 없이 Runner가 시작되지 않는 경우

macOS의 GitLab Runner는 전용 CI 계정의 사용자 영역에서 실행되는 형태가 지원 경계입니다. 설정 파일과 LaunchAgent가 다른 계정의 홈 디렉터리에 있으면 서비스가 로드되어도 의도한 Runner가 아닐 수 있습니다.

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

whoami
id
launchctl print gui/$(id -u)

이 명령의 목적은 서비스를 고치는 것이 아니라, 현재 접속한 계정과 사용자 영역의 로딩 상태를 확인하는 것입니다. 운영자가 자신의 계정에서 반복 설치했다면 전용 CI 계정의 설정과 system_id가 서로 달라질 수 있습니다.

GitLab Runner를 빠른 부팅만을 이유로 LaunchDaemon으로 바꾸지 않습니다. 시스템 영역에서는 사용자 세션, 로그인 Keychain, 그래픽 세션과 같은 조건이 달라집니다. Apple의 시스템 Daemon 설계 기준은 두 실행 문맥을 구분합니다.

계정과 서비스가 섞인 흔적

다음 흔적이 있으면 재설치보다 정리가 먼저입니다.

• 전용 CI 계정과 운영자 계정에 각각 설정 파일이 있습니다.
• 서로 다른 사용자 영역에 LaunchAgent가 남아 있습니다.
• GitLab에 비슷한 이름의 Runner가 여러 개 보입니다.
• 실제 Mac의 system_id와 프로젝트에서 기대하는 Runner가 다릅니다.
• 한 Runner에는 Xcode 서명 자격이 있지만 다른 Runner에는 없습니다.

오래된 서비스를 바로 삭제하지 말고, 계정·경로·등록 시각·마지막 작업 기록을 보존합니다. 삭제 전에는 어떤 프로젝트가 그 Runner를 사용했는지 확인해야 합니다.

FileVault가 켜진 상태에서는 디스크 잠금 해제와 macOS 사용자 로그인이 분리될 수 있습니다. 자동 로그인은 보안 설정과 함께 검토해야 하며, FileVault가 활성화된 환경에서 자동 로그인과 무인 복구가 항상 동시에 가능한 것은 아닙니다. Apple의 자동 로그인 설명과 FileVault 관리 문서를 함께 확인합니다.

Apple Silicon, macOS 버전, 기기 관리 정책, 네트워크 조건에 따라 원격 해제 경로가 달라집니다. 그러므로 “재시동하면 반드시 자동으로 Runner가 온라인이 된다”는 운영 가정을 문서에 넣지 않습니다.

원격 복구 설계는 다음처럼 선택해야 합니다.

• 자동 복구를 우선하면: 제한된 복구 계정, 접근 승인, 감사 로그를 함께 설계합니다.
• 저장 장치 보호를 우선하면: 원격 해제에 필요한 승인 절차와 현장 또는 별도 관리 경로를 명시합니다.
• 둘 다 필요하면: 주 노드와 예비 노드의 역할을 분리하고, 한 대의 자동 로그인에 전체 출시를 의존하지 않습니다.

Remote Login이 실제로 켜져 있고 네트워크 경로가 유지되는지도 따로 확인합니다. Apple의 Remote Login 설정 안내는 SSH 접근 가능 여부를 확인하는 출발점입니다. SSH가 된다는 사실만으로 사용자 세션과 Runner 작업 환경이 준비됐다고 판단하면 안 됩니다.

주의: FileVault 원격 해제 능력과 복구 시간은 장치 구조, 관리 정책, 네트워크에 따라 달라집니다. 검증하지 않은 성공률이나 복구 시간을 출시 기준으로 쓰지 않습니다.

Runner가 GitLab에 온라인으로 표시되어도 생산 작업을 수행할 수 있다는 뜻은 아닙니다. 가장 짧은 시험부터 실행해 실패 영역을 좁힙니다.

1. 전용 CI 계정으로 현재 사용자와 홈 경로를 기록합니다.
2. GitLab Runner 서비스의 등록 사용자와 LaunchAgent 경로를 확인합니다.
3. 평범한 셸 작업으로 작업 수락 여부를 확인합니다.
4. Xcode 빌드만 별도로 실행합니다.
5. 시뮬레이터 시작을 별도로 확인합니다.
6. 코드 서명과 내보내기를 마지막에 검증합니다.

이 순서를 지키면 “Runner는 온라인이지만 Keychain을 읽지 못하는 문제”와 “Runner 자체가 작업을 받지 못하는 문제”를 분리할 수 있습니다. 로그인 Keychain, 시스템 Keychain, CI 서비스 계정, 출시 서명 신원을 같은 저장소처럼 취급하지 않습니다.

Keychain 오류가 나면 먼저 다음을 확인합니다.

• 작업이 같은 전용 CI 계정으로 실행되는가
• 서명 자격 증명이 로그인 Keychain에만 남아 있지 않은가
• Keychain 잠금 해제 상태가 사용자 세션과 함께 복구되는가
• 권한 변경 뒤 이전 프로세스가 계속 실행 중이지 않은가
• 시뮬레이터가 그래픽 사용자 세션을 요구하는가

전체 출시 파이프라인을 한 번에 돌리면 어느 단계에서 권한이 사라졌는지 알 수 없습니다. 일반 스크립트, Xcode, 시뮬레이터, 서명 순서로 각각 증거를 남깁니다.

Runner가 온라인이어도 프로젝트의 작업을 받지 못할 수 있습니다. Runner 태그, 보호 브랜치 권한, 프로젝트 또는 그룹 범위를 확인합니다. GitLab Runner 태그 및 범위 설정 문서를 기준으로 다음을 대조합니다.

• 파이프라인 작업이 요구하는 태그
• 실제 Runner에 등록된 태그
• 보호 브랜치 또는 보호 태그의 실행 권한
• 프로젝트 전용인지 그룹 공유인지 여부
• 동일한 이름을 가진 오래된 Runner의 존재

이 단계에서 태그가 맞지 않으면 Mac을 재시동하거나 Runner를 다시 설치해도 해결되지 않습니다. 반대로 태그가 맞는데 서비스 로그가 비어 있다면 사용자 세션과 LaunchAgent를 먼저 봅니다.

디버그 로그는 통제된 점검 시간에만 켭니다. 변수와 토큰, 서명 관련 값이 로그에 들어가지 않도록 GitLab의 Runner 문제 해결 안내에 맞춰 로그 보관 범위와 삭제 절차를 정합니다.

다음 목록은 단순 온라인 표시가 아니라 실제 출시 작업을 기준으로 합니다.

• [ ] 전용 CI 계정의 이름과 홈 경로를 기록했습니다.
• [ ] Runner 설정 파일이 전용 CI 계정의 사용자 영역에 있습니다.
• [ ] LaunchAgent가 올바른 사용자 세션에서 로드됩니다.
• [ ] LaunchDaemon으로 임의 변경하지 않았습니다.
• [ ] FileVault 잠금 해제 방식과 승인자를 문서화했습니다.
• [ ] Remote Login 경로가 실제로 접속되는지 확인했습니다.
• [ ] 일반 셸 작업이 정상적으로 실행됩니다.
• [ ] Xcode 빌드가 별도 시험으로 통과합니다.
• [ ] 시뮬레이터 실행 결과를 저장했습니다.
• [ ] 코드 서명과 내보내기 결과를 확인했습니다.
• [ ] Runner 태그와 보호 브랜치 권한이 일치합니다.
• [ ] 디버그 로그에서 비밀 값이 제거됩니다.
• [ ] 정상 재시동뿐 아니라 비정상 전원 종료 뒤 복구 경로도 시험했습니다.
• [ ] 계정 권한을 회수했을 때 남은 서비스와 자격 증명을 확인했습니다.
• [ ] 주 노드가 실패할 때 사용할 예비 Mac 또는 수동 전환 절차가 있습니다.

이 목록에서 하나라도 빠지면 GitLab 화면이 온라인으로 바뀌었다는 이유만으로 출시 작업을 다시 열지 않습니다. 특히 FileVault 잠금 해제, 로그인 세션, Keychain, 실제 Xcode 작업은 서로 대체할 수 없는 검증 항목입니다.

단일 Mac이 현장 조작에 의존한다면 운영 구조도 다시 봐야 합니다. 이미 보유한 Mac의 원격 Mac 임대 조건과 비용을 검토할 때도 단순 접속 가능 여부보다 전용 CI 계정, 원격 제어 방식, 재시동 뒤 작업 수락, 장애 시 교체 절차를 확인해야 합니다. 기업용 Mac 인프라에서 중요한 것은 Runner 한 줄의 온라인 표시가 아니라 복구 증거의 연속성입니다.

현재 사내 Mac만 사용하는 방식은 초기 구매 후에도 장비 교체, 현장 접근, 계정 회수, 예비 노드 확보를 직접 부담해야 합니다. 단일 노드에 출시 작업이 묶이면 재시동이나 FileVault 승인 지연이 곧 배포 지연으로 이어집니다. 원격 Mac 임대를 활용하면 별도 노드를 빠르게 분리해 테스트하거나 예비 빌드 환경으로 운영할 수 있어, 현장 조작에 의존하는 구조보다 복구 선택지가 넓어집니다. MESHLAUNCH의 한국용 Mac 임대 경로를 검토할 때도 가격보다 먼저 이 체크리스트를 대조하시기 바랍니다. 꾸준한 고정 부하와 물리 포트가 반드시 필요한 조직에는 직접 구매가 더 적합할 수 있지만, 재시동 복구와 임시 CI 용량이 문제라면 격리된 원격 Mac을 예비 노드로 두는 편이 현실적인 선택입니다.