GitLab은 macOS Runner 설치 안내에서 Runner가 사용자 계정의 LaunchAgent로 실행되는 방식과 로그인 세션의 관계를 설명합니다. (GitLab macOS 설치 안내) 따라서 GitLab macOS Runner 재시작 후 오프라인이면, 먼저 실행 계정이 로그인되어 있는지와 LaunchAgent가 시작됐는지 확인하세요. 자동 로그인은 보안 경계를 바꾸므로, 무조건적인 복구책으로 켜지 마세요.
이 글이 필요한 경우
여행 중 원격 Mac을 재시작한 뒤 GitLab CI/CD 작업이 Runner를 찾지 못하는 디지털 노마드와 원격 개발자를 위한 안내입니다.
iOS 프로젝트의 빌드 환경을 관리하거나, 소규모 팀에서 자체 Runner의 복구 책임을 판단하는 경우에도 참고할 수 있습니다.
GitLab macOS Runner 재시작 후 오프라인: 먼저 증상을 나누세요
GitLab에 작업이 대기 중이라고 해서 곧바로 Runner 서비스가 멈춘 것은 아닙니다. Runner 상태, 태그 일치, 프로젝트에서 사용할 수 있는지 여부를 각각 확인해야 합니다. GitLab은 Runner API에서 상태 정보를 제공하고, Runner 태그와 작업 태그가 작업 배정에 사용된다고 안내합니다. (Runner API 상태 정보, Runner 태그와 작업 배정 안내)
| 관찰한 증상 | 우선 확인할 것 | 다음 판단 |
|---|---|---|
| GitLab에서 Runner가 오프라인으로 표시됨 | 실행 계정의 로그인 상태, LaunchAgent, Runner 로그 | Mac에서 시작되지 않았는지 또는 GitLab 연결이 끊겼는지 확인합니다 |
| Runner는 온라인인데 작업이 대기 중임 | 작업 태그, Runner 태그, 프로젝트에서 사용할 수 있는 범위 | 설정이 맞지 않으면 호스트를 재시작하기보다 태그와 등록 범위를 수정합니다 |
| 작업은 시작되지만 실패함 | 작업 로그, 실행 계정 권한, Xcode 개발자 디렉터리 | Runner 연결과 실제 빌드 환경을 따로 진단합니다 |
| Xcode 명령이 작동하지 않음 | Xcode와 명령줄 도구 설치 상태, 활성 개발자 디렉터리 | Runner가 아니라 빌드 도구 구성 문제일 수 있습니다 |
GitLab 화면에 Runner가 보이지 않거나 작업을 받을 수 없더라도 원인은 다를 수 있습니다. 작업이 어떤 태그를 요구하는지, Runner가 해당 프로젝트에 등록되어 있고 사용할 수 있는지 먼저 대조하세요. 호스트에서 서비스를 다시 시작하기 전에 스케줄링 문제를 배제하면 불필요한 복구 작업을 줄일 수 있습니다.
첫 단계: 로그인 세션과 LaunchAgent 확인
GitLab의 macOS 안내에 따르면 Runner는 사용자 계정의 LaunchAgent로 설치하고 실행하는 방식입니다. 사용자 LaunchAgent는 해당 사용자 세션에 연결됩니다. 시스템 시작 시 동작하는 LaunchDaemon과 같은 것으로 취급하면 안 됩니다. (GitLab의 macOS Runner 설치 및 세션 안내)
Mac에 접속해 Runner를 설치한 계정으로 로그인한 뒤, GitLab Runner의 공식 명령 문서에 따라 서비스 상태를 확인하세요. 필요하면 Runner 상태와 검증 명령을 사용하고 로그를 확인합니다. (GitLab Runner 명령 안내) 확인 결과에 따라 다음처럼 진행하세요.
- 계정이 로그인되지 않았다면: 먼저 해당 계정에 로그인한 뒤 LaunchAgent와 Runner 상태를 다시 확인합니다.
- 계정은 로그인됐지만 서비스가 실행되지 않았다면: 설치와 실행에 사용한 계정이 같은지, 서비스 설정이 유효한지 확인합니다.
- 서비스는 실행 중인데 GitLab에서 오프라인이라면: 네트워크 연결과 Runner 등록 상태를 살펴보고 검증 명령과 로그 결과를 대조합니다.
- Runner가 온라인으로 바뀌었다면: 작업이 실제로 배정되고 실행되는지 확인합니다. 온라인 표시만으로 빌드 성공을 판단하지 않습니다.
GitLab 화면의 상태와 Mac 안의 서비스 상태는 서로 다른 증거입니다. 둘 중 하나만 보고 복구 완료로 처리하지 마세요.
SSH 연결을 닫은 뒤에도 같은 문제인지 구분하세요
SSH 연결 종료, macOS에서 로그아웃, 호스트 재시작은 서로 다른 동작입니다. SSH 창을 닫았다는 사실만으로 사용자 세션이 종료됐다고 볼 수 없습니다. 반대로 Runner가 SSH에서 명령을 실행할 수 있다는 이유만으로, 로그아웃이나 재부팅 뒤에도 LaunchAgent가 유지된다고 단정할 수 없습니다.
예를 들어 여행 중 원격 Mac을 재시작한 뒤에는 SSH 접속은 되지만 GitLab에 Runner가 오프라인으로 보일 수 있습니다. 이때는 실행 계정이 로그인 상태인지 확인하고, 사용자 세션에서 LaunchAgent가 시작됐는지 살펴보세요. 이어서 Runner 로그와 GitLab 상태를 대조합니다. SSH 접속 가능 여부는 호스트 접근의 단서일 뿐, Runner의 준비 상태를 증명하지 않습니다.
주의: 자동 로그인은 사용자 세션을 자동으로 여는 선택입니다. 원격 호스트의 물리적 접근과 저장된 계정 자격 증명에 대한 위험도 함께 달라집니다. (Apple의 자동 로그인 보안 안내)
Runner는 온라인인데 작업이 실패하면 빌드 환경을 점검하세요
문제를 세 단계로 나누면 대응이 정확해집니다. Runner 서비스가 시작됐는지, GitLab이 작업을 배정했는지, 작업에서 Xcode 빌드가 성공했는지를 각각 확인하세요. 앞 단계가 정상이라고 뒤 단계까지 정상인 것은 아닙니다.
작업 로그에서 실패한 명령과 실행 계정을 확인한 다음, 해당 계정이 필요한 프로젝트 파일과 서명 관련 환경에 접근할 수 있는지 점검하세요. Xcode 명령줄 도구가 설치되어 있는지, 활성 개발자 디렉터리가 의도한 Xcode를 가리키는지도 확인할 수 있습니다. Apple은 명령줄 도구 설치와 추가 Xcode 구성요소 설치 방법을 안내합니다. (Xcode 명령줄 도구 설치 안내, 추가 Xcode 구성요소 안내)
터미널에서 개발자 디렉터리를 확인할 때는 xcode-select -p를 실행하고, 필요하면 xcodebuild -version 결과를 작업 로그와 비교하세요. 예상한 경로와 다르면 Xcode 설정을 먼저 바로잡습니다. Runner를 반복해서 재시작해도 활성 개발자 디렉터리나 프로젝트 권한 문제는 해결되지 않습니다.
원격 Mac에서 iOS 빌드를 이어가야 한다면, 프로젝트가 요구하는 Xcode 환경과 로그인 세션이 실제로 준비됐는지 함께 확인하세요. GitLab CI/CD의 등록과 작업 설정은 Runner 서비스 복구와 별도 항목으로 관리해야 합니다.
복구 방식은 자동 로그인 위험과 대체 경로로 결정하세요
| 복구 방식 | 장점 | 부담과 위험 | 선택 기준 |
|---|---|---|---|
| 사용자 로그인 후 Runner 실행 | 사용자 세션과 서비스 상태를 직접 확인할 수 있습니다 | 재시작 뒤 사람이 로그인해야 할 수 있습니다 | 무인 복구보다 접근 통제를 우선할 때 고려합니다 |
| 자동 로그인 사용 | 재시작 뒤 사용자 세션이 열리는 방식으로 복구를 구성할 수 있습니다 | 물리적 접근과 계정 자격 증명의 보안 경계가 달라집니다 | 조직의 보안 기준과 호스트 접근 통제가 허용할 때만 검토합니다 |
| 대체 빌드 경로 준비 | 자체 Runner 장애 때 빌드 업무가 한 경로에만 묶이지 않습니다 | 환경과 서명 설정을 별도로 맞춰야 합니다 | 자동 로그인을 허용할 수 없거나, 복구 대기 시간을 감당하기 어려울 때 검토합니다 |
자동 로그인은 GitLab 문서가 설명하는 설치 및 세션 동작과 관련된 선택이지, 모든 원격 Mac에 적용할 보편적인 권장 설정은 아닙니다. Apple의 안내를 확인하고, 해당 기기에 누가 물리적으로 접근할 수 있는지와 계정에 어떤 자격 증명이 남는지 검토하세요. 보안 요구사항과 충돌한다면 자동 로그인 대신 담당자의 로그인 절차나 별도 빌드 경로를 선택합니다.
자체 Runner의 운영 책임과 원격 Mac 접속 방식을 함께 살펴보려면 MACCOME의 원격 Mac 이용 안내에서 이용 범위를 확인하세요.
재부팅 검수로 자체 Runner를 유지할지 결정하세요
장애가 복구된 다음에는 재부팅부터 프로젝트 빌드까지 한 흐름으로 확인하세요. 결과는 각 단계의 증거와 함께 기록합니다.
- [ ] Mac 재시작 뒤 원격 접속이 가능한지 확인합니다.
- [ ] Runner 실행 계정이 로그인되어 있는지 확인합니다.
- [ ] 사용자 LaunchAgent가 시작됐고 Runner 서비스가 실행 중인지 확인합니다.
- [ ] GitLab에서 Runner가 온라인이며 프로젝트 작업을 받을 수 있는지 확인합니다.
- [ ] 실제 작업을 실행하고 로그에서 Xcode 빌드 결과를 확인합니다.
- [ ] 자동 로그인을 사용했다면 물리적 접근과 계정 자격 증명에 대한 보안 검토도 기록합니다.
사용자 세션이 필수이고 사람이 로그인할 수 있으며 빌드 결과까지 재현된다면, 현재 방식의 자체 Runner를 유지할 수 있습니다. 사람이 없는 시간에도 복구가 필요하지만 자동 로그인을 허용할 수 없다면, 로그인 절차를 보완하거나 대체 빌드 경로를 마련하세요. 자동 로그인 위험을 받아들일 수 있는 경우에도 재부팅 검수와 보안 검토를 모두 통과한 뒤에만 운영 방식으로 확정합니다.
자주 묻는 점
재시작 뒤 Runner가 오프라인이면 Mac 자체가 고장 난 건가요?
그렇다고 단정할 수 없습니다. Mac에 접속할 수 있어도 실행 계정의 세션이 열리지 않았거나 LaunchAgent가 시작되지 않았을 수 있습니다. 반대로 서비스는 실행 중인데 태그나 프로젝트 접근 설정 때문에 작업이 배정되지 않을 수도 있습니다. GitLab 상태, 호스트 서비스, 작업 로그를 차례로 비교해 원인을 좁히세요.
Runner의 온라인 표시만 확인하면 복구된 건가요?
아닙니다. 온라인은 Runner의 연결 상태를 보여주는 단서이지, 프로젝트 작업의 성공이나 Xcode 빌드 완료를 보장하지 않습니다. 작업이 Runner에 배정됐는지, 실제 명령이 실행됐는지, 빌드 로그가 성공으로 끝났는지 각각 확인하세요. 서명이나 개발자 도구 문제는 서비스 상태와 별도로 남아 있을 수 있습니다.
여행 중에는 자동 로그인과 수동 로그인을 어떻게 고르면 되나요?
먼저 원격 Mac에 물리적으로 접근할 수 있는 사람과 계정에 저장된 자격 증명을 검토하세요. 자동 로그인이 보안 정책과 충돌하거나 접근 통제를 설명하기 어렵다면 사용하지 않는 편이 낫습니다. 수동 로그인으로 필요한 복구 시간을 감당할 수 있는지 시험하고, 어렵다면 보안 요건에 맞는 대체 빌드 경로를 마련하세요.
자체 Mac을 들고 다니면 분실이나 파손 때 작업 환경을 다시 준비해야 하고, 재부팅 뒤 현장에 접근할 수 없는 상황도 생길 수 있습니다. 다른 빌드 경로로 바꾸면 기존 Xcode 설정과 서명 환경을 맞추는 일이 남습니다. 프로젝트가 지속적으로 접근 가능한 macOS 빌드 환경을 필요로 한다면, 실제 Mac을 원격으로 이용하는 방안도 비교해 보세요. MACCOME의 원격 Mac 구성과 주문 안내를 확인한 뒤, 사용자 세션과 복구 검수 결과에 맞는 운영 방식을 선택할 수 있습니다.