GitHub Actions Node 24 마이그레이션: 2026 맥 CI 업그레이드 체크리스트

오래된 맥 Runner는 지금 작업을 처리하고 있어도 Node 20 유예 기간이 끝나면 JavaScript Action 실행이 막힐 수 있습니다. 2026년 6월 16일부터 Node 24가 기본 런타임이 되었으므로, 격리된 Mac 노드에서 즉시 강제 실행하고 검증된 노드부터 생산 풀로 옮겨야 합니다. 업그레이드할 수 없는 노드는 생산 풀에서 빼거나 새 원격 Mac 노드로 교체해야 합니다.

이 글은 self-hosted runner를 관리하는 플랫폼 팀, Xcode 서명과 배포를 담당하는 개발 생산성 팀, 그리고 맥 CI 용량과 업무 연속성을 결정하는 IT 책임자를 위한 안내서입니다. GitHub Actions Node 24 마이그레이션을 한 번에 끝내는 방법이 아니라, 실패 범위를 제한하면서 단계적으로 전환하는 절차를 설명합니다.

주의: GitHub가 공지한 Node 20 임시 회귀 기간은 2026년 9월 23일까지입니다. GitHub Enterprise Cloud의 self-hosted runner 최소 버전 강제 적용은 2026년 9월 25일부터 시작될 예정이므로, 실제 조직 다운로드 화면과 공식 변경 기록을 마지막 기준으로 삼아야 합니다. Node 20 폐기 공지와 최소 Runner 버전 적용 일정을 함께 확인해야 합니다.

시작일: 자산 목록과 세 가지 버전 분리

먼저 저장소별로 다음 항목을 기록합니다.

• 워크플로 이름과 실행 저장소
• 사용 중인 JavaScript Action과 버전 또는 고정 커밋
• self-hosted runner 그룹, 라벨, 앱 버전
• macOS 버전과 CPU 아키텍처
• 프로젝트가 요구하는 Node.js 버전
• Xcode 빌드, 테스트, 보관, 서명 작업
• 캐시, 사설 의존성, 프록시 인증서, Keychain 사용 여부

여기서 가장 중요한 구분은 세 가지입니다. Action 내부에서 사용하는 Node 런타임, 프로젝트 스크립트가 사용하는 Node.js 버전, 그리고 Runner 앱 자체의 버전은 서로 다른 계층입니다. 프로젝트의 package.json에서 Node.js 버전을 올렸다고 JavaScript Action의 런타임이 바뀌지는 않습니다. 반대로 Action 런타임이 Node 24로 바뀌어도 프로젝트 빌드가 자동으로 Node 24를 사용하지는 않습니다.

Runner 목록은 self-hosted runner REST API 문서의 반환 필드와 대조합니다. 작업 실행 기록은 Workflow Runs API로 확인하고, 실패한 작업의 로그에서 오래된 런타임 경고와 Action 이름을 연결합니다. 조직 화면에 보이는 다운로드 버전과 실제 노드에 설치된 버전이 다를 수 있으므로 두 값을 따로 보관해야 합니다.

첫 시간: 격리 노드의 강제 실행

생산 서명 인증서가 없는 Mac을 시험 노드로 지정합니다. 이 노드는 일반 빌드와 테스트를 수행하되, 배포용 비밀과 보관용 인증서는 받지 않아야 합니다. 라벨 또는 Runner Group으로 시험 작업만 라우팅하면 기존 생산 노드와 실행 결과를 비교하기 쉽습니다.

GitHub가 안내한 마이그레이션 설정으로 JavaScript Action을 Node 24에서 먼저 실행합니다. 설정 이름과 적용 범위는 조직 정책에 따라 달라질 수 있으므로, 오래된 블로그 글의 환경 변수를 그대로 복사하지 말고 현재 GitHub Actions Runner 설정 문서를 확인해야 합니다.

시험용 기준 작업에는 다음 흐름을 모두 넣습니다.

• 저장소 체크아웃
• 의존성 캐시 복원과 저장
• 사설 패키지 다운로드
• 자체 JavaScript Action 실행
• 빌드 결과물 업로드
• 실패 시 로그와 실행 환경 보존

단순히 Xcode 컴파일 하나가 성공했다고 호환성이 확인된 것은 아닙니다. Action이 반환하는 출력값, 캐시 경로, 셸 스크립트의 오류 처리, 프록시 인증서 동작까지 기록해야 합니다. 작업마다 성공 여부, 실패 단계, Runner 라벨, 실행 시각, 회귀 설정을 남기면 이후 롤백의 근거가 됩니다.

첫날: Action과 Runner 업그레이드

Node 20 제거 뒤 실패할 작업의 범위

Node 20이 공식 실행 경로에서 제거되면 오래된 Node 런타임을 지정한 JavaScript Action이 우선적인 위험 대상입니다. 셸 명령만 실행하는 단계가 모두 실패한다는 뜻은 아니지만, 해당 Action의 메타데이터가 구형 런타임을 요구하거나 현재 Runner가 새 런타임을 제공하지 못하면 작업이 중단될 수 있습니다.

조직의 모든 워크플로에서 Action을 찾은 뒤 다음 순서로 수정합니다.

• 공식 Action은 지원되는 최신 태그로 올립니다.
• 제삼자 Action은 유지 관리 상태와 최근 릴리스를 확인합니다.
• 커밋을 고정한 경우 새 커밋이 실제로 반영되었는지 확인합니다.
• 내부 Action은 action.yml의 런타임 선언과 의존성 호환성을 점검합니다.
• 동일 Action을 호출하는 재사용 워크플로까지 함께 검색합니다.

Action을 최신 태그로 바꾸는 것만으로 충분하지 않을 수 있습니다. 고정 커밋, 사설 레지스트리 인증, 오래된 종속 패키지가 업데이트를 막는 경우가 있기 때문입니다. 시험 노드에서 새 버전을 먼저 실행한 뒤 생산 워크플로에 반영해야 합니다.

Runner 앱과 macOS 조건

Runner 앱은 Node 런타임과 별도로 업데이트해야 합니다. 공식 릴리스 목록은 Actions Runner Releases에서 확인합니다. 업데이트 후에는 서비스가 다시 시작되었는지, 조직에 정상 등록되었는지, 올바른 Runner Group과 라벨을 유지하는지 확인합니다.

macOS가 새 Runner 조건을 충족하지 못하는 경우에는 임시 회귀 설정을 장기 해법으로 삼지 않아야 합니다. 시스템 업그레이드가 가능한지 먼저 판단하고, 불가능하면 노드 교체 또는 생산 풀 제외로 결정합니다. 오래된 노드를 계속 남겨 두면 작업이 간헐적으로 다른 노드에 배정되어 원인 파악이 더 어려워집니다.

첫 생산 검증: Xcode와 서명 폐쇄 루프

self-hosted runner에서 Node 24 호환성을 확인하는 방법

생산과 같은 워크플로를 시험 노드에 복제하되, 배포 권한은 제거한 상태로 실행합니다. 검증 범위는 체크아웃부터 결과물 전달까지 이어져야 합니다.

• 사설 저장소와 패키지 저장소 인증
• 의존성 설치와 캐시 적중 여부
• Xcode 프로젝트 빌드
• 단위 테스트와 UI 테스트
• 보관 파일 생성
• 서명에 필요한 Keychain 접근
• 결과물 업로드와 외부 저장소 전달

각 단계의 로그에서 Node 24와 직접 관련된 오류만 찾으면 안 됩니다. 자체 Action의 입력과 출력, 환경 변수 이름, 인증서 체인, 캐시 디렉터리, 셸의 종료 코드가 바뀌었는지도 확인해야 합니다. 특히 프록시를 사용하는 기업망에서는 새 런타임이 인증서 저장 위치나 TLS 검증에 영향을 받을 수 있습니다.

서명과 배포는 별도 통제 노드에서 마지막에 수행합니다. 시험 노드에 생산 인증서를 복사해 빠르게 확인하는 방식은 편하지만, 실패 시 비밀이 여러 노드에 남는 위험을 키웁니다. GitHub Actions 보안 사용 지침에 따라 권한을 작업 단위로 줄이고, 로그에 인증 정보가 표시되지 않는지도 점검해야 합니다.

생산 전환 판단표

첫 주: 이중 운영과 회귀 훈련

업그레이드에 실패한 Mac Runner를 회귀 노드로 남기는 방법

검증된 기존 생산 풀과 Node 24 시험 풀을 동시에 유지합니다. 다만 기존 풀은 무기한 보존하는 회귀 창고가 아니라, 정해진 종료 조건을 가진 제한된 안전망이어야 합니다.

저장소를 Runner Group 또는 라벨 기준으로 나눕니다. 변경 위험이 낮은 테스트 작업부터 Node 24 풀로 보내고, 서명과 배포 작업은 승인된 노드에서만 실행합니다. 작업이 실패하면 기존 풀로 자동 전환하기보다 실패 로그를 수집하고 담당자가 재라우팅해야 합니다. 자동 전환은 새 런타임 문제를 숨기고 구형 환경을 계속 사용하게 만들 수 있습니다.

다음 복구 상황을 실제로 연습합니다.

• Action 업데이트 뒤 작업 실패
• Runner 업데이트 중 서비스 중단
• Mac 재시작 뒤 등록 상태 손실
• 네트워크 단절 뒤 작업 재배정
• 서명 노드에서 비밀 접근 실패
• 회귀 노드가 오래된 런타임으로 다시 실행되는 상황

Runner 서비스 구성은 공식 서비스 설정 절차와 대조합니다. 재시작 뒤 온라인 상태만 확인하지 말고, 테스트 작업이 실제로 해당 라벨에 배정되고 완료되는지까지 확인해야 합니다.

용량 판단은 추정치가 아니라 실제 대기열과 시험 통과율을 기준으로 합니다. Node 24 풀의 처리 여유가 부족하면 새 Mac을 임시로 추가할 수 있지만, 먼저 어떤 저장소가 어느 기간 동안 추가 노드를 필요로 하는지 기록해야 합니다. 이때 원격 Mac은 오래된 노드를 서둘러 폐기하기 위한 대체 환경이 아니라, 서명 권한을 분리한 검증용 풀로도 사용할 수 있습니다. 팀의 원격 Mac 이용 방법을 확인할 때는 Runner Group, 네트워크 경로, 비밀 저장 정책을 함께 검토해야 합니다.

기한 전: 생산 승인과 구매 판단

Node 24 마이그레이션의 생산 승인 조건

조직별 승인표에는 다음 항목을 빠짐없이 남깁니다.

• Action이 Node 24에서 성공했는지
• Runner 앱이 조직의 최소 조건을 만족하는지
• macOS가 해당 Runner를 지원하는지
• Xcode 빌드와 테스트가 완료되었는지
• 보관과 서명이 통제된 노드에서 성공했는지
• 캐시와 사설 의존성이 정상인지
• 재시작 뒤 서비스가 자동 복구되는지
• 실패 시 담당자와 회귀 경로가 지정되었는지

GitHub의 날짜나 최소 버전은 변경될 수 있습니다. 따라서 문서에 고정된 숫자만 복사하지 말고 조직의 Runner 다운로드 화면, 공식 변경 기록, 최신 릴리스를 배포 직전에 다시 확인해야 합니다. 2026년 9월 23일 이후에도 회귀 설정이 남아 있다면 이를 정상 운영으로 간주하지 말고, 제거가 완료되었는지 감사해야 합니다.

기존 Mac을 계속 보유할지 교체할지는 다음 조건으로 결정합니다. macOS 업그레이드가 가능하고 Runner 서비스가 안정적으로 복구되면 기존 노드를 갱신합니다. 시스템 조건이나 보안 격리를 충족하지 못하면 생산 풀에서 제외하고 새 원격 Mac을 시험한 뒤 교체 수량을 정합니다. 장기적으로 서명과 배포를 수행하는 노드는 물리적 접근, 인증서 보관, 네트워크 정책까지 함께 평가해야 합니다.

현재 보유한 Mac을 그대로 유지하는 방법은 초기 지출이 이미 끝났다는 장점이 있지만, 오래된 시스템의 업그레이드 작업, 부품 교체, 무인 재시작 복구, 예비 노드 확보가 IT 팀의 운영 부담으로 남습니다. 특히 Node 24 전환 시점에 맞춰 여러 노드를 동시에 정비하면 업무 중단과 구매 승인 지연이 겹칠 수 있습니다. 반면 RUVCLOUD의 원격 Mac은 격리된 시험 노드로 먼저 사용한 뒤, 실제 Xcode 파이프라인이 통과한 경우에만 필요한 기간과 수량을 늘리는 방식으로 검토할 수 있습니다. 맥 렌탈 요금과 이용 기간을 확인할 때도 장기 고정 계약보다 시험 기간, Runner 재시작 복구, 생산 전환 조건을 먼저 문서화하는 편이 안전합니다.

Node 24 전환은 설정 하나를 바꾸는 작업이 아닙니다. 오래된 Action, Runner 앱, macOS, 프로젝트 Node.js, Xcode 서명 경로를 시간순으로 검증해야 합니다. 지금 격리 노드에서 시작하고, 2026년 9월의 유예 종료와 최소 버전 적용 전에 생산 승인을 끝내야 합니다.

기존 노드가 기한 안에 업그레이드되지 않는다면 RUVCLOUD의 원격 Mac을 별도 시험 풀로 추가해 실제 작업 흐름을 검증할 수 있습니다. 검증 결과가 나온 뒤에야 교체 수량과 렌탈 기간을 결정하면, 불필요한 장기 구매와 급한 생산 전환을 모두 피할 수 있습니다. 필요한 경우 한국 지역 원격 Mac 신청 경로에서 해당 운영 조건을 확인할 수 있습니다.