Codex CLI 원격 Mac CI는 어떻게 설정할까? 2026 실전 가이드

원격 Mac CI에서는 에이전트 작업, macOS 빌드·테스트, 워크플로 조정을 서로 다른 책임으로 나눠야 합니다. Codex CLI는 지정된 작업을 수행하고, Xcode 단계는 Apple 도구 체인으로 결과를 검증하며, GitHub Actions는 작업의 실행 순서와 Runner를 관리합니다.

GitHub Actions macOS CI에서 Codex CLI를 호출할 수 있지만, 작업이 어느 저장소 복사본에서 수행되는지 확인해야 합니다. 자체 호스팅 Runner는 워크플로에서 사용할 수 있습니다. 단, 그것이 곧 안전한 격리를 보장한다는 뜻은 아닙니다. GitHub 자체 호스팅 Runner를 워크플로에 연결하는 방법과 Runner를 안전하게 사용하는 기준을 함께 검토하세요.

팀에 필요한 환경이 macOS 전용 도구 체인인지, 다른 작업에도 쓰는 개발 환경인지 먼저 정리하려면 원격 Mac 환경 안내를 참고할 수 있습니다. 원격 Mac이 Xcode 작업을 맡아야 하는지 결정하는 것과, Codex CLI가 저장소를 변경하게 허용하는 것은 별개의 판단입니다.

명령을 실행하기 전에 에이전트가 변경할 저장소 사본을 확정하세요. 개발자가 쓰는 로컬 저장소와 Runner가 체크아웃한 CI 저장소가 서로 다르면, 수정은 성공해도 실제 빌드에는 반영되지 않을 수 있습니다.

시작 전에 다음 항목을 기록합니다.

• [ ] 원격 Mac에서 사용할 저장소와 체크아웃 경로를 확정합니다.
• [ ] 작업의 출처가 신뢰된 브랜치인지 외부 풀 리퀘스트인지 확인합니다.
• [ ] Codex 요청에 포함할 작업 범위와 허용할 파일 변경을 지정합니다.
• [ ] 필요한 명령줄 도구와 Xcode 버전을 확인합니다.
• [ ] 로그, 테스트 결과, 빌드 산출물을 저장할 위치를 정합니다.

아래 예시의 경로와 요청 문구는 실제 저장소에 맞게 바꿉니다. 먼저 해당 디렉터리로 이동한 뒤 비대화형 작업을 실행하면, 의도한 체크아웃에서 동작하는지 확인하기 쉽습니다.

cd "<저장소 경로>"
codex exec --sandbox read-only "<저장소를 분석하고 변경 없이 요약>"

저장소 위치, 작업 출처, 필요한 도구를 함께 확인하지 않으면 Agent가 엉뚱한 복사본을 분석하거나 불필요한 접근 권한을 요구할 수 있습니다. 원격 개발 환경의 연결 방식이나 운영 준비 항목은 원격 Mac 이용 도움말에서 확인할 수 있습니다.

codex exec 옵션은 설치된 CLI 버전에서 확인해야 합니다. Codex CLI 명령 참고 문서를 기준으로 codex exec --help를 확인하고, 샌드박스와 승인 관련 옵션이 현재 환경에서 어떤 이름과 동작으로 제공되는지 검증하세요.

작업 공간 쓰기는 저장소 파일을 바꿀 수 있다는 의미이지, 코드가 안전하다는 보증은 아닙니다. 승인 단계를 없애거나 샌드박스를 끄는 방식을 기본값으로 삼지 마세요. 더 넓은 권한이 필요하다면 그 이유와 영향 범위를 먼저 기록하고, CI 자격 증명은 가능한 한 해당 작업에 필요한 최소 범위로 줄입니다.

주의: 승인 설정만으로 외부 코드를 격리할 수는 없습니다. 워크플로가 비밀 정보에 접근하는지와 Runner가 어떤 저장소·네트워크에 연결되는지도 함께 살펴야 합니다.

첫 실행은 저장소를 바꾸지 않는 분석 요청으로 시작합니다. 요청 범위, 실행 위치, 종료 상태가 예상과 맞는지 확인한 뒤에만 제한된 파일 변경을 허용하세요.

시험 과정에서는 다음 항목을 남깁니다.

• 실제 실행 경로와 기준 커밋이 예상한 값인지 확인합니다.
• 명령의 종료 상태와 표준 출력·오류 출력을 기록합니다.
• 변경을 허용한 경우 git diff로 수정 파일과 내용을 확인합니다.
• 작업이 실패했을 때 동일한 입력과 저장소 상태로 재현할 수 있는지 검사합니다.

이 확인 절차는 팀의 운영 권고입니다. Codex CLI 문서에 명시된 옵션 동작과, 팀이 시험 실행을 위해 추가한 기록·검토 절차를 구분해 관리하세요. 결과 요약이 그럴듯해도 저장소의 실제 변경 내역을 확인하지 않았다면 작업을 통과 처리하지 않는 편이 안전합니다.

• GitHub Actions의 macOS 작업에서 Codex CLI를 실행할 수 있나요?
  실행 환경에 Codex CLI를 준비하고 워크플로 단계에서 codex exec를 호출할 수 있습니다. 자체 호스팅 Mac을 연결한다면 Runner 접근 범위와 저장소 권한을 별도로 검토하세요. 워크플로 성공 여부는 Codex 단계뿐 아니라 Xcode 검증 단계까지 확인해야 합니다.

• 원격 Mac에서 작업 디렉터리와 실행 권한을 어떻게 정하나요?
  CI가 체크아웃한 저장소 경로를 작업 기준으로 고정하고, 읽기 전용 분석부터 시작하세요. 수정이 필요할 때는 작업 공간 쓰기 범위로 한정하고, 더 높은 권한은 이유를 확인한 뒤 검토합니다. 옵션 이름과 지원 범위는 설치된 CLI의 도움말 및 공식 명령 문서에서 확인해야 합니다.

• Codex CLI가 수정한 코드는 어떤 절차로 검증하나요?
  별도 단계에서 Xcode 빌드와 프로젝트 테스트를 실행합니다. 커밋 식별자, 사용한 도구 체인, 테스트 상태, 산출물 저장 위치를 로그에 남기세요. 에이전트가 작업 완료라고 응답한 사실만으로 빌드 성공이나 배포 가능 상태를 판단하지 않습니다.

• 필요하지 않은 비밀 정보나 네트워크에 접근하지 않게 하려면 어떻게 하나요?
  작업에 필요한 비밀 정보만 필요한 단계에 제공하고, 외부 기여 코드가 실행될 수 있는 작업에는 배포 자격 증명을 전달하지 않는 방식부터 검토하세요. Runner 접근 제어와 네트워크 정책도 확인해야 합니다. 작업 폴더를 지우는 것만으로 실행된 코드를 격리할 수는 없습니다.

Codex 작업이 끝난 뒤에는 프로젝트가 요구하는 Xcode 빌드와 테스트를 별도 CI 단계로 실행해야 합니다. Xcode와 macOS 호환 여부는 사용하는 버전 조합에 따라 확인해야 하므로, Apple의 Xcode 시스템 요구 사항과 Xcode 27 릴리스 노트를 기준으로 실제 설치 환경을 점검하세요. 버전명만 확인하고 호환성을 추정하지 마세요.

빌드가 성공했더라도 테스트가 생략되었거나 산출물이 다른 작업에서 만들어졌다면 완료 증거가 부족합니다. 작업 결과를 검토할 때는 에이전트의 변경 내역과 Xcode의 검증 기록을 나란히 보관하세요.

자체 호스팅 Runner는 저장소나 작업이 실행되는 동안 영향을 받을 수 있는 환경입니다. GitHub는 자체 호스팅 Runner 사용과 워크플로 보안을 별도로 안내합니다. 특히 외부 기여 코드와 비밀 정보가 함께 노출되지 않도록 해야 합니다. GitHub의 pull_request_target 보안 주의 사항을 확인하고, 외부 풀 리퀘스트를 비밀 정보에 접근 가능한 지속형 Mac Runner에서 실행하지 않도록 설계하세요.

내부 작업부터 시험하고, 실제 실행 위치와 변경 범위, Xcode 결과를 재현할 수 있으면 사용 범위를 늘립니다. 외부 코드와 자격 증명을 분리하지 못하거나 작업 후 환경을 신뢰할 수 없는 상태라면 해당 Runner 도입을 미루세요. 지속적인 고부하 작업이나 물리 장치 연결이 필요한 경우에는 원격 임대가 항상 적합한 것은 아니며, 자체 Mac 운용이나 필요한 물리 환경을 비교하는 편이 낫습니다.

현재 Linux 클라우드 환경은 Xcode 작업을 직접 수행할 수 없고, 개발자 로컬 Mac은 계속 켜 두고 관리해야 하며, 직접 장비를 구매하면 초기 비용과 유지 관리 책임이 생깁니다. 반면 원격 Mac 임대는 필요한 기간에 macOS 환경을 마련할 선택지입니다. 장기간 고정 부하가 있거나 물리 인터페이스가 필수라면 구매·자체 운영과 비교하고, 단기 검증이나 분리된 CI 노드가 필요하다면 NUKCLOUD 이용 구성과 요금을 확인해 작업 방식에 맞는지 판단하세요.