빌드는 끝났는데 일반 실행기에서 Xcode 검증 단계만 실패합니다. 가장 빠른 해법은 Claude Code GitHub Actions 원격 맥 구성을 두 작업으로 나누는 것입니다.

Claude Code는 이슈와 풀 리퀘스트를 읽고 코드를 수정합니다. 원격 맥은 고정된 커밋을 받아 Xcode 빌드와 테스트만 수행합니다. 외부 변경은 서명 자산이 없는 검증 노드로 제한하고, 배포는 별도 노드와 수동 승인을 거쳐야 합니다.

이 글은 다음 개발자를 위한 실행 기준입니다.

  • GitHub 이슈나 풀 리퀘스트에 따라 애플 플랫폼 프로젝트를 자동 수정하는 개발자
  • GitHub 자체 호스팅 맥 실행기의 라우팅과 복구를 담당하는 데브옵스 엔지니어
  • 에이전트의 소스 코드, 네트워크, 키체인, 배포 토큰 접근 범위를 통제하는 보안 담당자

마지막 업데이트: 2026년 9월 7일. Claude Code Action, GitHub 자체 호스팅 실행기, Xcode 명령 줄 도구와 테스트 문서를 기준으로 내용을 확인했습니다.

작업 경계 분리

에이전트 작업의 책임

Claude Code Action은 이슈나 풀 리퀘스트의 지시를 바탕으로 저장소를 읽고 변경을 제안하는 역할을 맡깁니다. 변경 결과는 커밋 또는 브랜치로 남기고, 다음 작업이 사용할 커밋 식별자를 명확히 기록해야 합니다. 공식 사용 문서의 작업 흐름과 인증 방식을 먼저 확인하십시오. Claude Code Action 공식 사용 문서

에이전트 작업에서 확인할 항목은 다음과 같습니다.

  • 이벤트가 이슈인지 풀 리퀘스트인지
  • 변경을 요청한 브랜치와 실제 검사할 브랜치
  • 작업 흐름 파일을 수정할 수 있는지
  • 저장소 토큰이 읽기 전용인지, 제한된 쓰기 권한인지
  • 외부 풀 리퀘스트의 스크립트가 자동 실행되는지

일반적인 코드 분석과 문서 수정은 리눅스 실행기에서도 처리할 수 있습니다. macOS 전용 도구가 필요한 검증만 원격 맥으로 보내야 실행기 비용과 공격 범위를 줄일 수 있습니다.

맥 검증 작업의 책임

원격 맥 작업은 에이전트가 코드를 다시 해석하거나 수정하는 곳이 아닙니다. 에이전트가 만든 고정 커밋을 받아 다음 결과만 반환해야 합니다.

  • 사용 가능한 Xcode와 명령 줄 도구
  • 프로젝트 또는 작업 공간의 방식
  • 의존성 해석 결과
  • xcodebuild 종료 상태
  • 테스트 결과 묶음 파일
  • 작업 디렉터리 정리 결과

Apple의 Xcode 명령 줄 도구 참고 문서에 맞춰 명령을 구성하십시오. 실행기가 온라인이라는 표시만으로는 빌드 성공을 판단할 수 없습니다.

이슈와 풀 리퀘스트 변경

신뢰 경계

내부 브랜치와 외부 풀 리퀘스트를 같은 경로로 처리하지 마십시오. 외부 변경은 작업 흐름 파일 자체를 바꿀 수 있고, 저장소 안의 스크립트가 실행될 수 있습니다. GitHub도 자체 호스팅 실행기를 사용할 때 저장소와 작업의 신뢰 수준을 분리하도록 안내합니다. GitHub Actions 보안 사용 지침을 기준으로 권한을 검토하십시오.

안전한 기본값은 다음과 같습니다.

  • 외부 풀 리퀘스트는 서명 없는 별도 맥 노드에서만 실행합니다.
  • 보호된 브랜치의 작업 흐름 파일 변경은 사람의 검토 뒤에 허용합니다.
  • 에이전트 작업에는 배포 토큰과 개인 키를 주입하지 않습니다.
  • 풀 리퀘스트 번호, 소스 저장소, 기준 커밋을 로그에 남깁니다.
  • 검증이 끝나면 작업 디렉터리와 임시 자격 증명을 삭제합니다.

Claude Code Action의 보안 문서도 권한과 신뢰할 수 없는 입력을 별도로 다룹니다. 공식 보안 설명을 읽은 뒤 저장소 정책을 정하십시오.

커밋 전달

에이전트 작업이 성공했다는 사실만 다음 작업에 전달하면 안 됩니다. 에이전트가 실제로 만든 커밋 식별자를 출력값으로 남기고, 맥 작업은 그 값을 받아 체크아웃해야 합니다.

jobs:
  agent:
    runs-on: ubuntu-latest
    outputs:
      revision: ${{ steps.change.outputs.revision }}

  mac-verify:
    needs: agent
    runs-on: [self-hosted, macos, apple-verify]
    steps:
      - name: checkout exact revision
        run: |
          git fetch --all --prune
          git checkout "${{ needs.agent.outputs.revision }}"
      - name: build and test
        run: |
          xcodebuild \
            -workspace "<WORKSPACE_PATH>" \
            -scheme "<SCHEME_NAME>" \
            -destination "platform=iOS Simulator,id=<SIMULATOR_ID>" \
            -resultBundlePath "<RESULT_PATH>"

위 경로와 이름은 예시용 자리표시자입니다. 저장소 이름, 계정 이름, 실행기 라벨, 토큰, 인증서, 팀 식별자, 방식과 파일 경로를 실제 값으로 바꾸기 전에 저장소 정책을 먼저 확인하십시오.

애플 도구 체인 검증

빌드 실패의 분류

원격 맥에서 실패했다고 바로 캐시를 삭제하거나 Xcode를 다시 설치하게 만들면 안 됩니다. 먼저 실패 지점을 구조화해야 합니다.

  1. Xcode 선택과 명령 줄 도구 상태
  2. 프로젝트 파일과 방식 이름
  3. 패키지 또는 의존성 해석
  4. 서명 없는 빌드 가능 여부
  5. 테스트 대상과 시뮬레이터 목적지
  6. 결과 묶음 생성 여부
  7. 작업 디렉터리와 로그 정리 여부

xcodebuild의 종료 상태가 실패를 가리키면 로그를 에이전트의 다음 추론 입력으로 제한적으로 돌려보내십시오. 에이전트가 임의로 키체인을 변경하거나 노드 전체 캐시를 삭제하도록 허용하지 마십시오. Apple의 Xcode 자동화 테스트 문서는 테스트 실행과 결과 수집의 기준을 제공합니다.

시뮬레이터와 그래픽 세션

명령 줄 빌드, 시뮬레이터 테스트, 그래픽 로그인 세션이 필요한 UI 테스트는 서로 다른 작업입니다.

  • 명령 줄 빌드는 로그인 화면 없이도 가능한지 확인합니다.
  • 시뮬레이터 테스트는 대상 장치가 실제로 부팅되고 테스트 결과 묶음이 생성되는지 확인합니다.
  • 그래픽 자동화는 사용자 세션, 화면 접근 권한, 창 포커스와 같은 추가 조건을 확인합니다.

시뮬레이터가 부팅되었다고 실제 기기 테스트를 대신할 수 있는 것은 아닙니다. 또한 원격 화면이 보인다고 모든 UI 자동화가 무인 실행된다는 뜻도 아닙니다. 연결이 끊긴 뒤에도 프로세스가 살아 있는지, 결과 파일이 남는지, 실패 작업이 다시 대기열에 들어가는지를 별도로 기록하십시오.

서명과 배포 경로

기본 경로

개발 단계의 기본 작업은 서명 없는 빌드와 테스트로 두는 편이 안전합니다. Claude Code가 접근하는 작업과 인증서, 키체인, 프로비저닝 파일, 배포 토큰을 같은 실행기에 두지 마십시오.

애플의 서명된 코드 생성과 보관 문서에 맞춰 배포 작업의 입력과 출력 범위를 따로 설계하십시오.

배포가 반드시 필요하다면 다음 조건을 모두 만족해야 합니다.

  • 보호된 브랜치에서만 실행합니다.
  • 배포 전용 실행기 그룹을 사용합니다.
  • 환경 승인 단계를 둡니다.
  • 에이전트 작업과 배포 작업의 토큰을 분리합니다.
  • 인증서와 키체인의 읽기·사용 범위를 최소화합니다.
  • 실패 시 자동 재시도보다 사람의 승인과 로그 검토를 우선합니다.

주의: 외부 풀 리퀘스트, 작업 흐름 파일을 수정할 수 있는 브랜치, 검토되지 않은 스크립트는 운영 서명 자산을 가진 맥 노드에 들어가면 안 됩니다.

여러 저장소와 실행기 그룹

라벨과 접근 제어

GitHub 자체 호스팅 실행기는 라벨로 작업을 특정 노드에 보낼 수 있습니다. 예를 들어 self-hosted, macos, apple-verify를 함께 요구하면 모든 조건을 만족하는 실행기만 선택됩니다. 실행기 라벨 공식 문서를 기준으로 라벨을 고정하십시오.

저장소 신뢰 수준이 다르면 실행기 그룹도 나눠야 합니다.

운영 구역 허용 작업 금지 항목 확인할 증거
개발용 내부 브랜치의 빌드와 테스트 배포 인증서 공유 커밋, 로그, 결과 묶음
팀 공유용 승인된 저장소의 검증 외부 스크립트와 잔여 자격 증명 작업 출처, 정리 기록
배포용 보호된 브랜치의 보관과 배포 에이전트의 직접 서명 접근 승인 기록, 배포 로그

실행기 그룹 접근 제어 문서를 이용해 저장소별 연결 범위를 제한하십시오.

장기 실행과 작업 격리

장기 실행 맥은 설치가 끝나면 방치하는 서버가 아닙니다. 실행기 업데이트, 계정 권한, 디스크 여유, 네트워크 연결, 작업 폴더 정리를 계속 확인해야 합니다. macOS 노드는 컨테이너처럼 매 작업마다 완전히 새로 만들어지지 않으므로 캐시와 키체인 잔여물이 다음 저장소에 영향을 줄 수 있습니다.

작업마다 다음 값을 기록하십시오.

  • 작업 출처와 저장소
  • 실제 커밋 식별자
  • 실행기 라벨과 작업 디렉터리
  • Xcode 명령과 종료 상태
  • 결과 묶음 위치
  • 정리 성공 여부
  • 재시작 또는 재대기열 여부

GitHub의 자체 호스팅 실행기 운영 문서를 바탕으로 업데이트와 연결 상태를 점검하십시오.

재시작과 복구 시나리오

재시작 복구는 실행기 프로세스 하나만 다시 띄우는 문제가 아닙니다. 다음 순서로 확인하면 원인과 영향 범위를 나누기 쉽습니다.

  1. 맥이 네트워크에 다시 연결되었는지 확인합니다.
  2. 실행기 서비스와 등록 상태를 확인합니다.
  3. 작업 계정의 권한과 작업 디렉터리를 확인합니다.
  4. 이전 작업의 프로세스와 잠금 파일을 확인합니다.
  5. 결과 묶음과 로그가 외부 저장 위치에 도착했는지 확인합니다.
  6. 진행 중이던 작업을 자동 이어받기보다 커밋 식별자로 다시 검증합니다.
  7. 재실행 후 동일한 결과가 나오는지 비교합니다.

온라인 상태가 복구되어도 그래픽 로그인 세션, 시뮬레이터, 키체인 접근은 별도로 실패할 수 있습니다. 따라서 무인 운영을 승인하기 전 실제 에이전트 변경, 맥 빌드, 결과 반환, 노드 재시작을 한 번의 폐쇄된 시험으로 검증해야 합니다.

선택 조건

다음 조건으로 운영 방식을 결정하십시오.

  • 내부 저장소만 사용하고 서명이 필요 없다면, Claude Code 작업과 서명 없는 원격 맥 검증을 분리해 시작합니다.
  • 외부 풀 리퀘스트를 받지만 애플 검증이 필요하다면, 서명 자산이 없는 격리 맥 노드로 제한합니다.
  • 시뮬레이터와 그래픽 세션이 필요하다면, 로그인 세션과 화면 접근 권한을 별도 검증하고 무인 실행을 가정하지 않습니다.
  • 보관이나 배포가 필요하다면, 독립 실행기 그룹과 보호된 환경 승인을 추가합니다.
  • 여러 저장소가 하나의 맥을 공유한다면, 신뢰 구역·계정·작업 폴더·정리 로그를 분리합니다.
  • 재시작 뒤 작업을 자동 복구할 증거가 없다면, 장기 운영으로 승격하지 말고 개발 시험 단계로 되돌립니다.

현재 사용하는 Linux 실행기는 일반 코드 분석에는 적합하지만 Apple 전용 도구 체인, 시뮬레이터, 그래픽 세션을 처리할 수 없습니다. 반대로 물리 Mac을 직접 구매하면 항상 켜 두어야 하고, 원격 접근·교체·재시작 관리와 초기 하드웨어 비용을 직접 부담해야 합니다. 단기간 검증에는 격리된 원격 맥이 더 유연할 수 있습니다. MACCOME의 원격 맥 환경에서 관리 권한과 제공 방식을 확인한 뒤, 실제 저장소로 시험하는 순서가 적절합니다.

선택지 맞는 상황 실제 단점 먼저 확인할 것
기존 Linux 실행기 일반 코드 수정과 정적 검사 Xcode와 시뮬레이터 사용 불가 애플 도구 의존성 유무
직접 운영하는 Mac mini 서버 장기 고정 부하와 물리 장치 접근 하드웨어 구매, 상시 전원, 복구 관리 필요 원격 전원과 장애 대응
격리된 원격 맥 개발 시험, 팀 검증, 임시 CI 네트워크 지연과 세션 상태 관리 필요 루트 권한, 재시작, 로그 회수
배포 전용 맥 노드 보호된 릴리스 작업 별도 비용과 승인 절차 발생 인증서, 키체인, 환경 승인

여러 지역의 노드를 비교해야 한다면 MACCOME의 맥 미니 주문 안내에서 제공 방식과 관리 조건을 확인하십시오. 가격이나 성능은 저장소의 의존성, 테스트 범위, 실행 빈도에 따라 달라지므로 일반적인 수치만으로 결정하지 않는 편이 안전합니다.

자주 묻는 내용

FAQ는 위의 실행 조건과 별개로, 실제 검색 단계에서 자주 확인하는 운영 문제를 정리한 것입니다.

외부 풀 리퀘스트를 서명 없는 검증 노드로 보내더라도 무조건 안전한 것은 아닙니다. 네트워크 접근, 작업 흐름 수정 권한, 잔여 캐시와 토큰을 함께 점검해야 합니다. 검증 결과가 반환된 뒤에는 로그에 비밀 값이 포함되지 않았는지도 확인하십시오.

복구 작업은 실행기 등록과 애플 도구 체인을 따로 봐야 합니다. 실행기가 온라인으로 돌아와도 시뮬레이터 부팅, 그래픽 로그인, 키체인 잠금 상태가 이전과 다를 수 있습니다. 고정 커밋을 다시 체크아웃하고 결과 묶음을 새로 만들어야 복구 결과를 비교할 수 있습니다.

최종 운영 판단

Claude Code GitHub Actions와 원격 맥을 하나의 거대한 작업으로 묶으면 권한이 섞이고 실패 원인을 찾기 어려워집니다. 에이전트 작업은 코드 변경과 커밋 생성에 한정하고, 맥 작업은 고정 커밋의 Xcode 검증에 한정하십시오. 서명과 배포는 별도 실행기와 사람의 승인을 거쳐야 합니다.

현재 Linux 실행기만 사용하는 방식은 Apple 도구 체인 검증이 불가능하고, 개인 장비를 서버로 전환하는 방식은 상시 운영·접근 제어·재시작 대응을 직접 떠안게 됩니다. MACCOME의 원격 맥을 사용하면 먼저 비생산 환경에서 관리 권한, 재시작, 로그 반환, 실제 프로젝트 빌드를 검증할 수 있습니다. 시험 결과가 통과한 뒤에만 필요한 임대 기간과 독립 배포 노드를 결정하는 편이 비용과 보안 경계를 함께 관리하기 좋습니다.