2026년 5월 14일 GitHub는 macOS 이미지 이전 계획을 공식 발표했습니다. GitHub의 공식 이미지 이전 공지처럼 러너 태그의 연결은 바뀔 수 있으므로, 이번 주에는 재실행보다 먼저 Set up job 로그를 저장해야 합니다. 실제 이미지, 프로세서 아키텍처, 엑스코드와 SDK를 성공 작업과 비교한 뒤 원인을 분리하십시오. 단기 복구는 검증된 러너 라벨 고정, 장기적으로 고정 도구 체인과 캐시가 필요한 작업은 관리 가능한 원격 맥 자체 호스팅 노드 검증이 순서입니다.
이 글은 iOS 또는 macOS 자동 빌드, 테스트, 배포 파이프라인이 갑자기 실패한 개발자를 위한 내용입니다. GitHub Actions 러너 환경을 관리하는 데브옵스 엔지니어와 서명 자산, 사설 도구 체인을 운영하는 플랫폼 팀도 대상입니다.
마지막 업데이트: 2026년 8월 21일. 태그와 이미지 정보는 GitHub Actions 러너 공식 문서, 공식 macOS 26 이미지 목록, Apple의 엑스코드 명령줄 도구 설정 문서를 기준으로 확인해야 합니다.
먼저 고정할 것과 다시 조사할 것을 나누십시오
코드가 바뀌지 않았는데 같은 워크플로가 실패했다면 곧바로 이미지 업데이트를 범인으로 단정하지 마십시오. 먼저 마지막 성공 실행과 첫 실패 실행에서 다음 항목을 모으십시오.
- 운영 체제 이름과 이미지 버전
- 프로세서 아키텍처
- 기본 엑스코드와 개발자 디렉터리
- SDK와 시뮬레이터 런타임
- 루비, 노드, 파이썬, 홈브루 버전
- 캐시 적중 여부와 복원된 키
- 실패한 정확한 단계와 앞뒤 로그
GitHub가 제공하는 워크플로 변수 문서를 참고해 환경 정보를 로그에 남기되, 인증서와 비밀번호는 출력하지 마십시오. 환경 정보가 같고 커밋이나 잠금 파일이 달라졌다면 코드 회귀를 계속 조사합니다. 반대로 환경 정보가 달라졌다면 이미지, 아키텍처, 도구 체인 문제로 분기합니다.
원인별 복구 경로
| 관찰된 차이 | 우선 확인할 증거 | 먼저 적용할 복구 | 복구 후 검증 |
|---|---|---|---|
| 이미지 또는 라벨 변화 | 설정 단계의 이미지 기록 | 검증된 라벨을 명시 | 깨끗한 빌드와 재실행 |
| 아키텍처 변화 | 시스템 및 실행 파일 아키텍처 | 의존성과 캐시 재생성 | 네이티브 모듈 테스트 |
| 엑스코드 변화 | 개발자 경로와 SDK | 엑스코드 직접 선택 | 빌드와 시뮬레이터 테스트 |
| 캐시 변화 | 키와 복원 로그 | 운영 체계와 도구 체인 분리 | 캐시 삭제 후 재구축 |
| 서명 또는 권한 | 키체인, 프로비저닝, 세션 로그 | 서명 단계만 격리 | 아카이브와 설치 검증 |
이 표에서 중요한 점은 증상과 해결책을 바로 연결하지 않는 것입니다. macos-latest라는 이름만으로 실제 macOS 이미지를 알 수 없습니다. 단일 작업의 로그와 당일 공식 이미지 목록이 함께 있어야 판단할 수 있습니다.
첫 번째 단계: 아키텍처 불일치를 증명하십시오
ARM과 인텔 환경을 바꾼 뒤에는 다음 세 가지를 같은 실행에서 확인해야 합니다.
- 시스템이 보고하는 프로세서 아키텍처
- 실패한 실행 파일 또는 라이브러리가 지원하는 아키텍처
- 홈브루와 패키지 관리자의 설치 접두사
루비 젬, 홈브루 패키지, 노드 네이티브 모듈, 사전 빌드 캐시는 이전 아키텍처의 산출물을 복원할 수 있습니다. 이때 나타나는 오류는 로드 실패, 잘못된 바이너리 형식, 모듈을 찾을 수 없음처럼 서로 다를 수 있습니다. 러너 라벨만 보고 ARM 또는 인텔 문제라고 결론 내리지 말고 실제 파일을 검사하십시오.
복구할 때는 의존성을 다시 설치하고 캐시 키에 운영 체제, 아키텍처, 엑스코드 버전을 포함하십시오. 아키텍처를 유지할 이유가 없다면 프로젝트의 네이티브 의존성이 더 잘 검증된 쪽을 고르십시오. 반대로 특정 바이너리나 사내 도구가 한 아키텍처만 지원한다면 러너를 고정하고 전환을 별도 작업으로 진행해야 합니다.
두 번째 단계: 유동적인 엑스코드와 SDK를 분리하십시오
실패 메시지를 다음 세 유형으로 나누면 조사 범위가 줄어듭니다.
- 엑스코드가 설치되지 않았거나 경로가 틀린 경우
- 엑스코드는 있지만 기본 개발자 디렉터리가 다른 경우
- 엑스코드와 SDK는 맞지만 프로젝트나 의존성이 호환되지 않는 경우
워크플로에서 사용 가능한 엑스코드 경로를 출력하고, 프로젝트가 요구하는 SDK와 시뮬레이터 런타임을 기록하십시오. Apple의 명령줄 도구 선택 방법대로 개발자 디렉터리를 명시하면 기본값 변화에 덜 의존할 수 있습니다.
고정 순서는 다음과 같이 잡으십시오.
- 검증된 러너 라벨을 워크플로에 명시합니다.
- 필요한 엑스코드 경로를 직접 선택합니다.
- SDK와 시뮬레이터 런타임 존재 여부를 검사합니다.
- 새 이미지에서 깨끗한 빌드를 실행합니다.
- 성공 뒤 캐시 빌드와 테스트를 실행합니다.
이미지 목록에 특정 도구가 보인다고 해서 이후에도 영구히 제공된다는 뜻은 아닙니다. 이미지 변경 때마다 공식 목록을 다시 확인해야 합니다.
세 번째 단계: 캐시를 재사용할 것과 버릴 것을 구분하십시오
캐시는 빌드를 빠르게 만들 수 있지만 환경을 숨기는 저장소가 되기도 합니다. 운영 체제나 프로세서가 바뀌었는데 같은 키를 사용하면 이전 산출물이 새 환경으로 들어옵니다. GitHub 의존성 캐시 문서의 방식처럼 잠금 파일을 포함하되, 여기에 운영 체제, 아키텍처, 엑스코드 차원도 추가하십시오.
루비, 노드, 파이썬, 홈브루, 오픈SSL의 버전 변화는 설치 스크립트와 컴파일 인자를 바꿀 수 있습니다. 따라서 사전 설치 상태를 전제로 하지 말고 필요한 버전을 워크플로에서 명시하십시오. 첫 복구 실행은 캐시를 끈 깨끗한 빌드로 진행합니다. 그 결과가 성공하면 새 키로 캐시를 만든 뒤 동일 커밋을 다시 검증합니다.
캐시를 지웠는데도 같은 단계에서 실패하면 캐시가 주원인이 아닐 가능성이 커집니다. 이때는 코드, 엑스코드, 서명 자산으로 조사 범위를 옮기십시오.
네 번째 단계: 빌드 성공과 배포 성공을 분리하십시오
컴파일은 통과했지만 아카이브 서명에서 실패한다면 일반 빌드 복구로 처리하면 안 됩니다. 키체인 접근 권한, 인증서, 프로비저닝 프로파일, 팀 식별자, 서명 키의 만료 상태를 별도로 확인하십시오. 로그에는 민감한 값 대신 <인증서 이름>과 <프로파일 이름> 같은 자리 표시자만 남겨야 합니다.
시뮬레이터 작업이 실패한다면 런타임이 설치되어 있는지, 대상 기기의 이름과 운영 체제가 맞는지, 비대화형 세션에서 시뮬레이터를 시작할 수 있는지 확인하십시오. 화면이 없는 세션에서 권한이나 사용자 키체인 접근이 달라질 수 있으므로 명령줄 빌드가 통과했다는 사실만으로 배포 경로가 복구됐다고 판단하지 마십시오.
각 수정 뒤에는 다음 순서로 확인하십시오.
- [ ] 캐시를 사용하지 않은 깨끗한 빌드가 통과합니다.
- [ ] 새 캐시를 복원한 빌드가 통과합니다.
- [ ] 필요한 시뮬레이터 테스트가 통과합니다.
- [ ] 서명된 아카이브가 생성됩니다.
- [ ] 테스트 설치 또는 배포 전 단계가 통과합니다.
- [ ] 러너 또는 원격 맥을 재시작한 뒤 같은 작업이 다시 통과합니다.
이 목록에서 마지막 항목이 빠지면 일회성 성공일 수 있습니다. 특히 키체인과 지속 캐시를 사용하는 파이프라인은 재시작 뒤 복구 여부가 중요합니다.
다섯 번째 단계: 고정 라벨과 원격 맥을 선택하십시오
일시적인 장애이고 작업이 무상태라면 먼저 검증된 이미지와 프로세서 라벨을 고정하는 편이 합리적입니다. 작업 시간이 짧고 사설 네트워크나 지속 프로세스가 없다면 GitHub-hosted runner의 관리 편의성이 더 큽니다. 더 큰 러너를 검토할 때는 GitHub larger runner 문서에서 해당 계정과 작업 유형의 제공 조건을 확인해야 합니다.
다음 조건이 두 가지 이상 겹치면 원격 맥 자체 호스팅 노드를 별도로 검증하십시오.
- 특정 엑스코드와 SDK를 오래 유지해야 합니다.
- 대형 캐시를 반복해서 만들고 보존해야 합니다.
- 사설 네트워크나 내부 패키지 저장소에 접근해야 합니다.
- 서명 키체인과 배포 도구를 통제된 호스트에 두어야 합니다.
- 예약 작업이나 지속 실행 프로세스가 필요합니다.
- 이미지 변경 때마다 긴 회귀 검증을 수행하기 어렵습니다.
다만 자체 호스팅은 유지 관리 책임이 사라지는 선택이 아닙니다. macOS 업데이트, 디스크 용량, 키체인 보호, 러너 보안, 재시작 후 자동 등록을 직접 운영해야 합니다. 그래서 생산 러너를 즉시 바꾸기보다 격리된 원격 맥에서 같은 저장소와 같은 비밀 변수 구조로 재현하십시오. 고정 엑스코드, 캐시, 서명, 내부망 접근, 재시작 후 재실행까지 통과한 뒤에만 이전을 결정해야 합니다.
원격 맥 자체 호스팅 러너의 설치 흐름이 필요하다면 원격 맥 러너 배포 안내를 먼저 확인하십시오. 엑스코드 노드의 검수 항목은 엑스코드 빌드 노드 환경 점검 안내에서 이어서 확인할 수 있습니다. 캐시와 도구 체인을 고정하는 운영 기준은 프로젝트의 현재 워크플로와 보안 요구에 맞춰 별도로 검토해야 합니다.
자주 묻는 문제를 빠르게 판별하십시오
macos-latest가 실제로 연결된 이미지는 어디서 확인합니까?
태그 이름이 아니라 실패 작업의 Set up job 로그에서 운영 체제 이미지와 버전을 읽어야 합니다. 이후 당일 macOS 26 공식 이미지 목록과 대조하십시오. 성공 작업의 같은 항목도 저장해 두면 태그 연결이나 사전 설치 도구가 바뀌었는지 확인할 수 있습니다.
이미지가 바뀐 뒤 컴파일이 실패하면 무엇부터 비교해야 합니까?
운영 체제, 프로세서, 엑스코드, SDK, 패키지 관리자와 캐시 복원 결과를 한 번에 비교하십시오. 이미지 변경 공지가 있더라도 그것만으로 원인을 확정하지 말아야 합니다. 코드 커밋과 잠금 파일도 같은 방식으로 대조해야 하며, 환경 차이가 확인된 뒤에만 러너 고정이나 의존성 재설치를 적용해야 합니다.
엑스코드와 프로세서 아키텍처를 워크플로에서 어떻게 고정합니까?
검증된 러너 라벨을 명시하고, 사용 가능한 엑스코드 경로를 출력한 뒤 개발자 디렉터리를 직접 선택하십시오. 캐시 키에는 운영 체제, 프로세서, 엑스코드와 잠금 파일 정보를 넣어야 합니다. 고정 뒤에는 깨끗한 빌드, 캐시 빌드, 시뮬레이터 테스트와 서명된 아카이브를 모두 다시 실행해야 합니다.
ARM과 인텔 러너는 어떤 기준으로 고릅니까?
프로젝트와 의존성이 실제로 지원하는 아키텍처를 기준으로 결정하십시오. 시스템 아키텍처만 보지 말고 실패한 실행 파일의 아키텍처와 홈브루 설치 접두사도 확인해야 합니다. 아키텍처를 바꾸면 기존 네이티브 모듈과 사전 빌드 캐시를 재사용하지 말고 새 환경에서 다시 만들어야 합니다.
환경 변화가 반복되면 원격 맥 자체 호스팅으로 옮겨야 합니까?
짧은 무상태 작업은 검증된 라벨 고정으로 해결될 수 있습니다. 특정 엑스코드, 지속 캐시, 사설망, 서명 키체인, 상시 프로세스가 함께 필요하면 원격 맥을 격리 노드로 먼저 검증하십시오. 재시작 후에도 동일한 워크플로가 통과하고 운영 책임을 감당할 수 있을 때 생산 이전을 판단하는 편이 안전합니다.
현재 GitHub-hosted runner는 이미지와 사전 설치 도구가 바뀔 때마다 재현성 검증이 필요하고, 유동 태그에 의존한 캐시와 서명 세션은 장애 범위를 키울 수 있습니다. 반면 VMSPIN의 원격 맥은 고정된 엑스코드와 내부망, 지속 캐시를 실제 작업으로 검증할 수 있는 선택지입니다. 먼저 격리 노드에서 전체 워크플로를 재실행한 뒤 생산 이전 여부를 결정하면, 기존 파이프라인을 성급하게 교체하지 않고 원격 맥이 더 안정적인지 직접 판단할 수 있습니다. 자세한 환경 선택은 VMSPIN 원격 맥 이용 안내에서 확인하십시오.