GitHub Actions Runner 버전 만료 시 어떻게 해야 할까? 2026 Mac 업그레이드 체크리스트

증상: Runner가 온라인인데 작업이 계속 대기하거나 실행되지 않습니다.
가장 빠른 해법: 중단될 때까지 기다리지 말고 현재 버전, 자동 업데이트 경로, 계정 적용 범위를 즉시 확인하십시오.

자동 업데이트가 켜진 노드는 업데이트 연결과 로그를 먼저 검증하십시오. 고정 버전이거나 외부 통신이 제한된 노드는 예비 Mac을 만든 뒤 회색 배포하십시오. 노드 풀이 크다면 테스트, 단계적 확대, 롤백 순서로 진행해야 합니다. 기존 Mac을 안전하게 멈출 수 없다면 생산 노드를 덮어쓰기보다 격리된 원격 Mac을 추가하는 편이 안전합니다.

이 글은 한 대의 Runner를 운영하는 개인 개발자, 여러 저장소가 서명 환경을 공유하는 소규모 팀, 고정 버전과 제한된 네트워크를 관리하는 플랫폼 및 데브옵스 팀을 위한 런북입니다. 처음 설치하는 방법이나 서비스 가격 비교가 아니라, 버전 만료 전 업그레이드 승인 기준을 다룹니다.

현재 적용 범위와 확인 근거

GitHub는 자체 호스팅 Runner에 최소 버전 실행 정책을 적용하고 있으며, GitHub Enterprise Cloud에는 단계적인 제한과 정식 적용 일정이 별도로 공지되어 있습니다. 2026년 8월 26일 기준으로 구체적인 최소 버전은 계정의 Runner 다운로드 안내와 공식 릴리스 페이지에서 다시 확인해야 합니다. 검색 결과에 남은 예전 버전 번호를 고정 기준으로 사용하면 안 됩니다. GitHub의 최소 버전 적용 일정 공지를 기준으로 계정 유형과 적용 시점을 대조하십시오.

자체 호스팅 Runner의 현재 버전은 어디에서 확인합니까?

먼저 저장소, 조직, 기업 가운데 Runner가 어느 관리 단계에 등록되어 있는지 확인합니다. 그다음 다음 자료를 같은 시점에 저장하십시오.

• GitHub 설정 화면의 Runner 버전과 상태
• Mac의 Runner 작업 디렉터리에 기록된 버전 정보
• 서비스 상태와 마지막 시작 시각
• 최근 작업 로그의 업데이트 또는 버전 경고
• 계정 화면에 표시되는 최신 다운로드 안내

GitHub의 자체 호스팅 Runner 공식 문서는 관리 범위와 라벨, 자동 업데이트 동작을 확인하는 출발점입니다. 화면에 online이라고 표시되는 것은 등록된 프로세스가 응답한다는 뜻에 가깝습니다. 새 작업을 받을 수 있는 최소 버전을 충족한다는 증거는 아닙니다.

개인 개발자의 단일 노드 보전

Mac이 한 대뿐이면 업그레이드 자체보다 작업 공백이 더 큰 위험입니다. 업데이트 전에 다음 정보를 별도 저장소에 남기십시오.

• self-hosted, 운영체제, 아키텍처 등 라벨 목록
• 작업 디렉터리와 캐시 위치
• 서비스 등록 방식과 실행 계정
• Xcode, SDK, 패키지 매니저의 현재 상태
• 인증서, 프로비저닝 프로파일, 키체인 접근 방식
• 마지막으로 성공한 커밋과 생성된 아카이브의 식별 정보

서명 키와 비밀값을 평문 파일로 복사하지 마십시오. 키체인 접근 권한과 환경 변수 이름만 기록하고, 실제 비밀값은 기존 비밀 관리 절차에서 복구할 수 있어야 합니다. 작업 디렉터리에 남은 임시 파일을 백업본으로 오해하지 않는 것도 중요합니다.

업그레이드 전에 임시 호스팅 작업을 준비하거나 격리된 원격 Mac을 예비 노드로 확보하십시오. 예비 노드는 같은 라벨을 바로 사용하지 말고 별도 라벨로 등록해야 합니다. 그렇지 않으면 검증되지 않은 노드로 배포 작업이 흘러갈 수 있습니다. MacDate의 원격 Mac 환경을 이용하는 경우에도 먼저 최소 빌드 체인을 복제하고, 실제 프로젝트의 등록과 서명까지 통과한 뒤 라벨을 전환하십시오.

검증은 다음 순서로 진행합니다.

• Runner 등록과 조직 또는 저장소 권한 확인
• 라벨 기반 작업 라우팅 확인
• 서비스 중지와 재시작 후 자동 복구 확인
• 캐시가 없어도 의존성 설치가 가능한지 확인
• 실제 테스트와 아카이브 작업 실행
• 기존 노드를 다시 사용할 수 있는지 확인

단일 노드에서는 일반 테스트만 통과했다고 완료로 판단하면 안 됩니다. 이동 개발자가 실제로 필요한 것은 저장소 체크아웃, 패키지 설치, 서명, 아카이브까지 이어지는 전체 경로입니다.

소규모 팀의 회색 배포

여러 저장소가 한 대 또는 소수의 Mac 빌드 노드를 공유하면 라벨만 확인해서는 부족합니다. 다음 의존성을 저장소별로 분류하십시오.

• 특정 Xcode 또는 SDK에 고정된 작업
• 키체인과 서명 인증서를 직접 사용하는 작업
• 로컬 캐시와 사전 설치 도구에 의존하는 작업
• 배포용 비밀값과 보호된 환경을 사용하는 작업
• 긴 빌드 시간으로 인해 대기열에 큰 영향을 주는 작업

새 노드 또는 격리된 노드에서 먼저 위험이 낮은 저장소를 실행합니다. 업그레이드 전후의 Runner 버전, 작업 로그, 빌드 산출물 식별값을 보관하십시오. 산출물이 생성되었다는 사실만 기록하지 말고, 서명 검증과 배포 단계까지 성공했는지 구분해야 합니다.

구버전 Runner가 온라인인데 작업을 받지 않는 이유는 무엇입니까?

대표적인 원인은 등록 상태와 실행 자격이 서로 다르기 때문입니다. 프로세스가 GitHub에 응답해도 최소 버전 제한, 라벨 불일치, 저장소 권한, 서비스 계정 문제로 작업을 거부할 수 있습니다. Runner 모니터링 및 문제 해결 문서의 진단 항목에 따라 GitHub 화면, Runner 로그, 실제 작업 로그를 함께 비교하십시오.

회색 배포의 중단 조건도 미리 정해야 합니다. 다음 중 하나라도 나타나면 다음 저장소로 확대하지 마십시오.

• Runner가 등록 직후 오프라인으로 바뀜
• 라벨이 맞는데 작업이 계속 대기함
• 서명 또는 키체인 접근이 실패함
• 같은 커밋에서 산출물이 달라짐
• 재시작 뒤 서비스가 자동으로 올라오지 않음
• 롤백 절차를 실제로 재현하지 못함

기존 노드는 바로 삭제하지 말고 일정 기간 격리해 두십시오. 모든 저장소가 새 노드로 전환되고 예비 노드가 작동하는 것을 확인한 뒤에만 이전 환경을 정리하는 방식이 복구 시간을 줄입니다.

고정 버전과 제한 네트워크의 업데이트 책임

자동 업데이트를 꺼 둔 Runner는 온라인 상태만으로 유지 관리가 끝나지 않습니다. 업데이트 서버와 릴리스 정보를 확인할 수 있는 통신 경로, 패키지 저장 위치, 검증 절차, 서비스 계정 권한을 별도로 관리해야 합니다.

자동 업데이트를 끈 Runner는 어떻게 올립니까?

먼저 actions/runner 공식 릴리스 목록과 계정 내부 다운로드 안내의 버전을 대조합니다. 그 후 다음 순서로 작업하십시오.

• 변경 승인과 유지 보수 시간을 기록합니다.
• 현재 Runner 디렉터리, 서비스 설정, 라벨을 보관합니다.
• 프록시와 방화벽에서 필요한 통신이 가능한지 확인합니다.
• 공식 패키지의 출처와 무결성 확인 정보를 검토합니다.
• 서비스 계정이 파일 교체와 재시작 권한을 갖는지 확인합니다.
• 새 파일을 운영 디렉터리에 덮기 전에 격리 노드에서 실행합니다.
• 서비스 로그와 작업 로그를 저장한 뒤 실제 빌드를 수행합니다.

프록시 설정이 맞지 않으면 다운로드가 실패하고, 파일 권한이 맞지 않으면 서비스는 설치되어도 재시작 후 실행되지 않을 수 있습니다. TLS 인증서 검증을 끄는 방법은 일반적인 해결책으로 사용하지 마십시오. 정말 예외가 필요하다면 승인자, 적용 범위, 복구 방법, 원상 복구 시점을 함께 기록해야 합니다.

수동 업데이트는 한 번의 작업이 아니라 반복 가능한 변경 절차여야 합니다. 정기 점검 때마다 계정 안내, 공식 릴리스, 노드 상태, 최근 실패 로그를 대조하십시오. 고정 버전의 이유가 특정 Xcode나 플러그인 호환성이라면 Runner만 올려도 되는지, 노드 전체를 재현해야 하는지 먼저 결정해야 합니다.

기업 노드 풀의 분할 운영

기업 플랫폼 팀은 노드 이름만 나열한 목록을 만들면 안 됩니다. 관리 단계, 운영체제와 아키텍처, 라벨, 연결된 저장소 권한, 자동 업데이트 상태, 현재 버전, 마지막 작업 결과를 한 번에 확인할 수 있어야 합니다. GitHub의 자체 호스팅 Runner REST API 문서를 사용하면 조직 또는 기업 범위의 목록을 자동 수집하는 데 도움이 됩니다.

노드 유형에 따라 전략을 나누십시오.

• 짧게 만들고 폐기하는 노드: 이미지나 부트스트랩을 고친 뒤 새 노드로 교체합니다.
• 오래 유지하는 노드: 서비스, 캐시, 서명 환경을 백업하고 회색 배포합니다.
• 자동 확장 노드: 새로 생성되는 노드가 최신 검증 절차를 통과했는지 확인합니다.
• 핵심 배포 노드: 일반 테스트 노드와 분리하고 별도 승인 후 전환합니다.

첫 번째 그룹은 비핵심 저장소와 낮은 위험도의 라벨로 구성합니다. 등록, 작업 수신, 실패율, 산출물, 배포 흐름을 관찰한 뒤 다음 그룹으로 확대하십시오. 숫자로 정한 내부 기준이 있다면 그 기준과 관찰 시간을 변경 기록에 남기십시오. 외부 진단 로그에는 저장소 비밀값과 서명 비밀을 포함하지 않아야 합니다.

릴리스 책임자의 최종 승인

배포 담당자는 “테스트가 통과했다”가 아니라 “실제 릴리스 경로가 복구 가능한가”를 승인해야 합니다. 다음 항목을 하나의 변경 기록으로 묶으십시오.

• 실제 Xcode 프로젝트 체크아웃
• 의존성 설치와 캐시 유무별 실행
• 단위 테스트와 통합 테스트
• 인증서 및 프로비저닝 프로파일 접근
• 아카이브 생성과 서명 검증
• 배포 단계의 보호 환경 접근
• Runner 서비스 재시작 뒤 작업 재수신
• 이전 노드 또는 예비 노드로의 전환

일반 테스트만 성공하고 아카이브나 배포에서 실패했다면 마이그레이션 완료로 표시하지 마십시오. 이 경우 배포 라벨을 기존 노드에 유지하고, 새 노드는 테스트 라벨로 격리합니다. 실패 원인이 Runner 자체인지 Xcode, 키체인, 네트워크, 캐시 변화인지 로그를 나눠서 확인해야 합니다.

주의: Runner 파일을 교체하기 전에 서비스 중지, 현재 디렉터리 보관, 복구용 라벨과 권한 확인을 끝내십시오. 복사본 없이 생산 노드를 덮어쓰면 버전 문제를 해결해도 이전 빌드 환경으로 돌아갈 수 없습니다.

업그레이드 방식별 판단표

아래 점수는 성능 점수가 아니라 운영 위험을 비교하기 위한 판단 점수입니다. 점수가 높을수록 해당 조건에서 선택하기 쉽다는 뜻입니다.

MacDate의 Mac 미니 렌탈 요금 안내는 장기 노드와 임시 검증 노드의 비용 조건을 확인할 때 참고할 수 있습니다. 다만 장기적으로 계속 높은 부하를 처리하거나 물리 장치 연결이 필요한 경우에는 직접 구매한 Mac이 더 적합할 수 있습니다.

기존 Mac과 원격 Mac의 역할 분담

현재 생산 Mac을 그대로 업그레이드하는 방식은 구성이 단순하지만, 실패하면 모든 작업이 동시에 멈춥니다. 오래된 캐시와 수동 설정이 많은 노드는 복구가 어렵고, 제한 네트워크에서는 패키지 확보 자체가 지연될 수 있습니다. 반대로 원격 Mac은 별도 노드로 격리해 등록, 실제 프로젝트, 서명, 재시작 복구를 검증하기 좋습니다.

원격 접속 지연, 키체인 정책, 사설망 접근, 물리 장치 의존성은 사전에 확인해야 합니다. 베어메탈과 가상화 macOS 비교처럼 실행 방식의 차이도 검토하십시오. 생산 Mac을 즉시 대체하는 것이 아니라, 안전한 업그레이드와 짧은 기간의 증설을 위한 보조 노드로 쓰는 것이 이 문제에 더 맞습니다.

마지막 판단은 다음처럼 내리면 됩니다.

• 현재 노드가 자동 업데이트되고 로그에도 정상 갱신이 보이면: 업데이트 경로를 확인한 뒤 기존 노드를 유지합니다.
• 자동 업데이트가 꺼졌거나 네트워크가 제한되면: 예비 노드를 만들고 회색 배포를 진행합니다.
• 노드 설정이 오래되어 재현이 어렵다면: 새 Mac 노드를 재구축하고 작업을 옮깁니다.
• 실제 배포 검증이 실패하면: 확대를 중지하고 기존 노드 또는 예비 Mac으로 라벨을 되돌립니다.

Runner가 온라인이라는 표시만 믿고 기다리는 것은 가장 위험한 선택입니다. 현재 Mac의 버전과 서비스 상태를 먼저 기록하고, 한 번이라도 예비 노드 전환을 연습한 뒤 업그레이드하십시오. 생산 Mac을 멈출 수 없다면 격리된 원격 Mac에 최소 빌드 체인을 복사해 실제 등록, 서명, 아카이브까지 확인하는 방식이 더 안전합니다. MacDate의 원격 Mac을 단기 검증 환경이나 추가 Mac CI 노드로 검토하면 기존 생산 노드를 덮어쓰지 않고 업그레이드 여부를 판단할 수 있습니다.