GitHub Actions Xcode 서명 실패는 Runner가 실제로 사용하는 macOS 계정과 그 계정의 키체인 상태부터 확인해야 합니다. 그다음 서명 신원과 프로비저닝 프로파일을 대조하세요. SSH로 로그인해 성공한 결과만으로 CI 서명이 가능하다고 판단하거나, 권한을 넓히고 인증서를 반복해서 가져오지는 마세요.
iOS 및 macOS 개발자: 로컬 빌드는 되지만 CI 아카이브나 서명이 실패할 때 증거를 따라 원인을 나눌 수 있습니다.
DevOps 엔지니어: 자체 호스팅 Mac Runner의 실행 계정과 서명 환경을 확인하고 인계할 수 있습니다.
릴리스 및 인증 정보 관리자: 인증서, 개인 키, 키체인, 프로비저닝 프로파일의 책임 범위와 접근 권한을 구분할 수 있습니다.
[ SECTION_01 ] GitHub Actions Xcode 서명 실패의 책임 경계
서명 오류라는 문구만으로 인증서가 손상됐다고 단정할 수 없습니다. 빌드 설정이 예상한 서명 방식과 다른지, Runner가 의도한 계정으로 실행되는지, 그 계정이 서명에 필요한 자료를 사용할 수 있는지 먼저 분리해야 합니다. GitHub의 자체 호스팅 Runner 문제 해결 문서는 Runner 로그와 서비스 상태를 조사하는 근거로 활용할 수 있습니다.
| 담당자 | 먼저 확인할 증거 | 다음 담당자에게 넘길 내용 |
|---|---|---|
| 앱 개발자 | 실제 Workflow의 커밋, Scheme, Target, 서명 방식, 빌드 설정 | 의도한 앱 식별 정보와 CI에서 선택된 서명 설정 |
| Runner 운영자 | 서비스 실행 계정, Runner 로그, 작업이 실행된 환경 | 실제 실행 계정과 키체인 접근 결과 |
| 서명 관리자 | 서명 신원과 개인 키 사용 가능 여부, 프로파일 정보 | 앱 식별 정보와 팀 및 서명 용도가 일치하는지 |
| 릴리스 담당자 | 실제 배포 대상 아카이브와 산출물 확인 결과 | 수정이 깨끗한 Workflow에서도 재현되는지 |
Xcode에서는 서명되는데 GitHub Actions에서는 인증서를 찾지 못하는 이유는 무엇인가요? 흔한 원인 후보는 서로 다른 macOS 계정이나 키체인입니다. 데스크톱에 로그인한 사용자가 접근할 수 있는 서명 자료를 Runner 서비스 계정도 자동으로 사용할 수 있다고 가정하면 안 됩니다. 프로젝트 설정과 CI 로그에서 선택된 서명 항목을 대조한 뒤, Xcode 빌드 설정 문서로 해당 빌드 설정의 의미를 확인하세요.
[ SECTION_02 ] 개발자와 Runner 운영자의 환경 확인
개발자는 로컬과 CI가 같은 커밋 및 동일한 서명 목표를 대상으로 하는지 확인해야 합니다. Scheme과 Target별로 자동 서명 또는 수동 서명 중 어느 경로를 쓰는지 살피세요. Bundle Identifier, 팀 식별 정보, 프로비저닝 프로파일이 같은 앱과 용도를 가리키는지도 함께 대조합니다. Xcode의 빌드와 실행 과정은 Apple의 앱 빌드 및 실행 안내를 참고해 확인할 수 있습니다.
SSH로 Mac에 접속하면 서명되는데 Runner에서는 실패하는 이유는 무엇인가요? SSH 세션과 Workflow가 서로 다른 사용자나 실행 환경을 이용할 수 있기 때문입니다. SSH에서 통과한 확인 결과는 그 SSH 세션의 증거일 뿐입니다. Runner가 서비스로 실행되는지, 실제 작업이 어떤 계정으로 수행되는지, 그 계정에서 키체인에 접근 가능한지는 따로 확인해야 합니다. 서비스 설정과 로그를 함께 조사할 때는 GitHub의 Runner 구성 문서를 기준으로 삼으세요.
| 관찰된 차이 | 우선 확인할 경계 | 오해하기 쉬운 결론 |
|---|---|---|
| 로컬 Xcode에서는 성공, CI에서 신원 없음 | Runner 실행 계정과 해당 계정의 키체인 | 인증서가 반드시 손상됐다는 판단 |
| SSH 점검은 성공, Workflow는 실패 | SSH 사용자와 서비스 실행 사용자의 차이 | SSH 로그인 성공이 CI 접근을 보장한다는 판단 |
| 신원은 보이지만 서명 실패 | 개인 키 사용 가능 여부, 앱 식별 정보, 프로파일 | 인증서가 목록에 있다는 사실만으로 서명 가능하다는 판단 |
| 빌드는 성공, 아카이브에서 실패 | 아카이브에 적용되는 설정과 실제 서명 대상 | 컴파일 성공을 배포 서명 성공으로 보는 판단 |
자체 호스팅 Mac Runner가 사용하는 계정과 키체인은 어떻게 확인하나요? SSH 계정이나 화면에 로그인된 계정을 대신 답으로 삼지 말고, Runner 서비스 상태와 Workflow 로그를 연결해 실행 맥락을 기록합니다. 그 맥락에서 키체인 상태와 접근 여부를 다시 확인하세요. Apple은 서명 신원을 인증서와 키체인의 맥락에서 다루므로, 코드 서명 신원 문서와 코드 서명 인증서 기술 문서를 따라 신원과 사용 가능성을 구분하는 것이 좋습니다.
[ SECTION_03 ] 서명 관리자와 릴리스 담당자의 검증
서명 신원이 표시된다는 것과 그 신원에 대응하는 개인 키를 현재 실행 환경이 사용할 수 있다는 것은 같은 뜻이 아닙니다. 서명 관리자에게는 신원과 개인 키 접근 여부를 각각 확인하고, 변경 전에는 기존 서명 자료와 복구 방안을 기록하도록 요청하세요. 개인 키나 인증서 내용을 로그에 출력해서 확인하는 방식은 피해야 합니다.
프로비저닝 프로파일도 별도로 확인합니다. 앱 식별 정보, 팀, 서명 용도가 현재 빌드 대상과 일치해야 합니다. 인증서가 보이는데도 실패한다면 키체인부터 다시 가져오기 전에 프로파일의 적용 대상과 선택된 서명 신원을 대조하세요. Apple의 앱스토어 배포용 프로비저닝 프로파일 생성 안내는 프로파일을 확인할 때 참고할 공식 기준입니다.
서명 신원은 있는데 Xcode 서명이 되지 않으면 무엇부터 확인하나요? 우선 해당 신원에 필요한 개인 키가 있는지, Runner 실행 계정이 이를 사용할 수 있는지 확인합니다. 그다음 Bundle Identifier와 팀 정보, 프로파일의 앱 식별 정보와 용도를 비교하세요. 서명 자료가 보인다는 이유만으로 키체인 문제가 해결됐다고 보거나, 불일치하는 프로파일을 다시 설치하는 데 그쳐서는 안 됩니다.
| 점검 선택지 | 진단 우선도 | 판단 기준 |
|---|---|---|
| Runner 계정과 키체인부터 확인 | 높음 | SSH와 Workflow의 실행 맥락이 다르거나 키체인 접근이 확인되지 않은 경우 |
| 서명 신원과 개인 키 확인 | 높음 | 현재 실행 맥락에서 원하는 신원을 선택할 수 없는 경우 |
| 앱 식별 정보와 프로파일 대조 | 높음 | 신원은 확인되지만 아카이브 또는 서명이 실패하는 경우 |
| 인증 자료를 다시 가져오기 | 낮음 | 실행 맥락과 자료의 불일치를 먼저 확인한 뒤에도 자료 자체의 문제가 증거로 남는 경우 |
위 표의 우선도는 진단 순서를 위한 판단 기준이지, 성공률이나 측정 결과가 아닙니다. 키체인을 무작정 교체하거나 접근 제어를 완화하면 원인 확인이 어려워지고 인증 자료 노출 범위가 커질 수 있습니다.
[ SECTION_04 ] 접근 통제와 수정 결과의 승인
서명 자격 증명을 사용할 수 있는 Workflow가 무엇인지 먼저 정리해야 합니다. 외부 기여 코드나 신뢰할 수 없는 작업이 생산용 서명 자료에 접근하지 않도록 작업 라우팅과 자격 증명 노출 범위를 제한하세요. 오류를 없애기 위해 보안 통제를 끄는 대신 변경 승인자, 적용 대상, 되돌리는 방법을 기록합니다. GitHub의 Actions 보안 사용 안내는 Workflow와 자격 증명 접근을 검토할 때 참고할 공식 문서입니다.
Workflow 로그에는 계정과 설정을 확인하는 데 필요한 정보만 남기세요. 인증서, 개인 키, 비밀 값 자체를 출력하면 원인 분석보다 자격 증명 노출이라는 더 큰 문제가 생길 수 있습니다.
아래 항목을 모두 확인한 뒤 수정 결과를 승인하세요.
- [ ] 실패한 Workflow의 커밋과 로컬 검증 커밋이 일치하는지 확인합니다.
- [ ] 실패가 빌드, 아카이브, 신원 선택, 실제 서명 중 어느 단계에서 발생했는지 로그로 구분합니다.
- [ ] Runner 서비스의 실제 macOS 실행 계정을 확인하고 SSH 사용자와 별도로 기록합니다.
- [ ] Workflow 실행 환경에서 필요한 키체인에 접근할 수 있는지 확인합니다.
- [ ] 서명 신원과 개인 키의 사용 가능성을 구분해 확인합니다.
- [ ] 앱 식별 정보, 팀 정보, 프로비저닝 프로파일의 적용 대상이 일치하는지 대조합니다.
- [ ] 신뢰할 수 없는 작업이 서명 자료를 읽을 수 없는지 확인하고 권한 변경의 승인자와 되돌리기 방법을 기록합니다.
- [ ] 깨끗한 Workflow에서 실제 릴리스 대상 아카이브와 산출물을 확인하고 결과를 보관합니다.
Runner가 온라인이거나 컴파일이 성공했다는 사실만으로 수정 완료를 선언하지 마세요. 실제 릴리스 대상의 아카이브가 서명되고, 산출물 확인까지 통과해야 승인할 수 있습니다. 실행 계정이나 권한 경계를 안정적으로 확인할 수 없다면 서명 작업을 격리하거나 전용 실행 환경을 다시 구성한 뒤 운영 릴리스에 투입하세요.
[ SECTION_05 ] 임시 Mac 환경과 지속 운영의 선택
현재 CI 환경을 그대로 쓰면 기존 자동화와 통합하기 쉽지만, 실행 계정과 키체인 상태가 불명확할 수 있고 공유 Runner의 권한 범위를 통제하기 어려우며 로컬 SSH 점검 결과를 CI 결과로 오해하기 쉽습니다. 반대로 전용 Mac 환경은 서명 작업을 다른 작업과 분리해 실행 맥락을 재현하기에 적합합니다. 다만 장기간 안정적으로 높은 부하를 계속 처리하거나 물리 인터페이스가 필요한 경우에는 직접 보유한 Mac이 더 맞을 수 있습니다.
이미 보유한 장비를 계속 운영할지, 임시 테스트 환경을 마련할지 판단할 때는 맥 미니 대여 가격 안내에서 이용 조건을 확인할 수 있습니다. 문제의 원인이 Mac 노드의 실행 환경이고 일정 기간 재현 가능한 서명 환경이 필요하다면, NOVAKVM의 원격 Mac을 임시 검증용으로 검토하는 방법도 있습니다. 상시 고정 부하나 직접 연결해야 하는 장치가 있다면 대여보다 자체 장비를 유지하는 편이 적절합니다.
GitHub Actions Xcode 서명 실패를 해결할 때는 Runner 계정과 키체인, 서명 신원, 프로파일을 분리해 확인하고 실제 아카이브 결과로 마무리해야 합니다. 환경을 재현하기 어려운 상황이라면 NOVAKVM 원격 Mac 환경을 살펴보고, 해당 노드에서 실행 계정과 서명 검증을 통제할 수 있는지 먼저 확인하세요.