2026년 7월 15일 이후 생성된 저장소는 GitHub Actions OIDC의 불변 subject 형식을 기본으로 사용할 수 있습니다. GitHub 공식 OIDC 문서에 따르면 새 형식에는 저장소 소유자 ID와 저장소 ID가 포함됩니다. 따라서 GitHub Actions OIDC 실패를 해결할 때는 워크플로 파일보다 실제 토큰의 sub를 먼저 확인해야 합니다. 그다음 클라우드 신뢰 정책을 고치고, 마지막으로 원격 Mac의 생산 서명 경계를 검증해야 합니다. 장기 클라우드 키로 즉시 되돌리는 방식은 피해야 합니다.
이 글은 GitHub Actions OIDC와 클라우드 역할 신뢰 정책을 관리하는 플랫폼 엔지니어와 기업 IT 팀을 위한 글입니다. 자체 호스팅 Mac Runner, Xcode 빌드, 생산 배포를 운영하는 개발 생산성 책임자와 기술 책임자도 대상입니다. 저장소 이름 변경이나 조직 공통 OIDC 템플릿 도입을 앞둔 보안 담당자에게도 필요한 점검 항목을 담았습니다.
마지막 업데이트: 2026년 9월 11일. 날짜, 기본 subject 형식, 설정 범위는 GitHub OIDC 공식 문서와 OIDC REST API 문서로 확인했습니다.
01실제 토큰의 신원 지표
GitHub Actions OIDC 실패는 다음 다섯 필드를 기록하는 것에서 시작합니다.
iss: 토큰 발급자aud: 대상 서비스 또는 audiencesub: 클라우드 신뢰 정책이 가장 자주 비교하는 주체repository_id: 저장소의 고정 식별자owner_id: 저장소 소유자의 고정 식별자
저장소 이름만 보고 sub를 추정하면 안 됩니다. 실패한 작업에서 실제 OIDC 토큰을 안전하게 추출하고, 계정 이름과 역할 이름을 가린 뒤 보관해야 합니다. 토큰 전체를 이슈나 채팅에 붙여 넣으면 안 됩니다.
| 구분 | subject에 반영되는 기준 | 진단 의미 | 우선 확인할 대상 |
|---|---|---|---|
| 기존 형식 | 저장소와 참조 이름 중심 | 저장소 이름 변경에 영향을 받을 수 있음 | 기존 클라우드 조건 |
| 불변 형식 | 소유자 ID와 저장소 ID를 포함 | 이름 변경과 이전 뒤에도 주체를 구분 | 새 sub와 ID 조건 |
| 사용자 정의 템플릿 | 조직 또는 저장소 설정이 정한 형식 | 기본 형식과 다를 수 있음 | 조직 템플릿과 적용 상태 |
토큰은 iss, aud, sub를 한 묶음으로 비교해야 합니다. aud만 맞고 sub가 다르면 인증은 실패할 수 있습니다. 반대로 sub가 맞아도 audience가 클라우드 공급자 기대값과 다르면 역할 교환이 거부됩니다.
신뢰 정책의 일치 지표
실제 수정 위치는 대개 GitHub workflow가 아니라 클라우드 역할 또는 내부 게이트웨이입니다. 신뢰 정책이 전체 sub를 비교하는지, 브랜치와 Environment를 함께 제한하는지, 재사용 가능한 워크플로의 주체를 별도로 허용하는지 확인해야 합니다.
다음 자료를 한 묶음으로 남기면 원인과 수정 결과를 추적하기 쉽습니다.
- 실패한 작업의 로그
- 탈취하지 않은 상태로 정리한 토큰 필드
- 현재 클라우드 신뢰 정책
- 변경 전후 정책 버전
- 허용 브랜치와 Environment 승인 기록
주의: 연결을 복구하려고
sub조건을 삭제하거나 모든 저장소를 허용하는 와일드카드를 넣으면 안 됩니다. 로그인 성공은 보안 검증의 완료가 아니라, 더 넓은 권한이 열렸다는 신호일 수도 있습니다.
저장소 이름을 바꾼 뒤 문제가 시작됐다면 기존 조건과 새 조건을 동시에 비교합니다. 이전 저장소의 sub, 변경 후 sub, 실제 실행 브랜치, Environment 이름을 각각 기록합니다. 한 번에 생산 역할을 수정하지 말고 테스트 역할에서 새 조건을 검증한 뒤 단계적으로 적용해야 합니다.
조직 설정과 변경 범위
새 저장소가 불변 subject를 기본으로 사용하는지, 기존 저장소가 직접 선택했는지, 조직 템플릿이 적용됐는지를 나눠서 확인해야 합니다. 세 상태를 하나로 취급하면 영향을 받는 저장소 수와 역할 수를 잘못 계산하게 됩니다.
| 확인 상태 | 확인할 설정 | 위험 | 권장 조치 |
|---|---|---|---|
| 새 저장소 | 생성 시 기본 subject 형식 | 기존 역할 조건과 불일치 | 테스트 역할에서 새 토큰 검증 |
| 기존 저장소 | 불변 형식 선택 여부 | 일부 파이프라인만 실패 | 저장소별 영향 목록 작성 |
| 조직 템플릿 적용 | 템플릿과 예외 저장소 | 여러 저장소가 동시에 변경 | 적용 전 저장소와 역할을 대조 |
조직 템플릿을 바꾸기 전에는 영향을 받는 저장소, Environment, 클라우드 역할을 모두 목록화해야 합니다. 특히 같은 역할을 여러 저장소가 공유하면 한 저장소의 변경이 다른 배포 파이프라인에 영향을 줄 수 있습니다.
이 과정에서 Mac mini 원격 운영 환경을 검토할 수 있습니다. 다만 OIDC 설정이 정상이어도 Mac의 로그인 계정, Runner 레이블, Keychain 권한이 그대로 공유되면 생산 서명 위험은 줄어들지 않습니다.
04권한 경계와 Mac Runner
OIDC는 지원되는 클라우드나 내부 서비스가 단기 접근 토큰을 발급받게 하는 방법입니다. GitHub Actions OIDC가 Apple 서명 인증서나 App Store Connect API 키를 대체한다는 뜻은 아닙니다. Apple API 키 생성 절차는 Apple Developer 공식 문서에서 별도로 관리됩니다.
Apple의 클라우드 관리 인증서도 OIDC 토큰과 다른 자격 증명 체계입니다. 관련 지원 범위는 Apple 클라우드 관리 인증서 안내에서 확인해야 합니다. 다음 권한을 같은 작업에 넣지 않는 것이 안전합니다.
- 신뢰할 수 없는 풀 리퀘스트 실행
- 클라우드 배포 역할 교환
- Xcode 빌드
- App Store 배포
- 생산 서명용 Keychain 접근
자체 호스팅 Runner는 저장소 간 작업 공간, 캐시, 환경 변수, Keychain 잔여물을 분리해야 합니다. GitHub도 자체 호스팅 Runner의 보안 경계를 별도로 설명하며, 신뢰할 수 없는 코드를 실행할 때 주의를 요구합니다. 자체 호스팅 Runner 보안 안내를 기준으로 공개 풀 리퀘스트와 생산 배포를 같은 노드에 배치하지 않는 편이 좋습니다.
장기 공유 Mac은 비용과 관리 편의성이 있지만 권한 잔여물이 남기 쉽습니다. 일회성 Runner는 잔여물을 줄이는 대신 재등록과 라우팅 검증이 필요합니다. 전용 배포 Mac은 생산 서명에 적합하지만 유휴 비용과 장애 시 대체 노드 문제가 생깁니다. 따라서 클라우드 역할을 얻는 Runner와 서명 Keychain을 가진 Mac을 같은 신뢰 영역으로 취급하면 안 됩니다.
팀의 Mac 접근 권한을 정리할 때는 Mac 개인정보 보호와 접근 제한 안내도 함께 확인하는 것이 좋습니다. 원격 접속 계정과 CI 작업 계정이 같은 관리자 자격을 공유하지 않는지 점검해야 합니다.
05생산 복구와 감사 지표
수정이 끝났다는 판단은 로그인 성공만으로 내릴 수 없습니다. 다음 순서로 허용과 거부를 모두 확인해야 합니다.
- 테스트 저장소에서 실제 OIDC 토큰을 생성합니다.
iss,aud,sub,repository_id,owner_id를 기록합니다.- 허용된 브랜치와 Environment가 단기 클라우드 토큰을 받는지 확인합니다.
- 허용되지 않은 저장소와 브랜치가 거부되는지 확인합니다.
- 재사용 가능한 워크플로의 호출 주체가 별도 조건과 일치하는지 확인합니다.
- 자체 호스팅 Mac Runner를 재시작하고 작업 라우팅을 확인합니다.
- 작업 공간과 Keychain을 정리한 뒤 서명 작업을 별도 노드에서 실행합니다.
- 주 노드 장애 시 대체 노드가 같은 권한 경계로 이어지는지 확인합니다.
복구 기록에는 허용 주체, 거부 주체, 단기 토큰의 사용 범위, Environment 승인, Runner 재시작, 작업 공간 정리, 서명 노드 격리 결과를 남겨야 합니다. 클라우드 신뢰 정책과 조직 템플릿의 버전도 함께 보관하면 감사 시 변경 원인을 설명하기 쉽습니다.
최종 점검 목록
- 실제 토큰의
sub를 추출했습니까? aud가 대상 서비스 조건과 일치합니까?- 저장소 이름만으로 주체를 추정하지 않았습니까?
id-token: write가 필요한 Job에만 부여됐습니까?contents와 Environment 승인이 과도하게 열리지 않았습니까?- 클라우드 역할과 Apple 서명 키를 같은 Runner에 노출하지 않았습니까?
- 공개 풀 리퀘스트가 생산 Keychain에 접근하지 못합니까?
- 실패와 성공 로그를 계정 및 내부 자원 식별자가 가려진 상태로 보관했습니까?
현재 공유 Mac을 계속 쓰는 방식은 초기에는 단순하지만, 클라우드 역할과 서명 Keychain이 한 호스트에 남고 작업 공간 정리 누락이 생기며 장애 시 영향 범위도 넓어집니다. 반대로 전용 원격 Mac을 임시로 분리하면 노드 비용, 운영 점검, 대체 노드 준비가 필요하지만 권한 경계를 검증하기 쉽습니다. 기존 환경에서 분리를 구현하기 어렵다면 VpsMesh의 원격 Mac 환경을 이용해 전용 빌드와 서명 노드 구성을 시험하는 편이 현실적입니다. 장기 고정 부하나 물리 장비 접근이 필요하다면 직접 Mac을 구매하는 편이 더 적합할 수 있고, 짧은 검증이나 장애 대응 노드가 필요할 때 원격 Mac 임대의 선택 가치가 커집니다.
06자주 확인하는 운영 질문
저장소를 옮기면 OIDC 조건도 자동으로 안전하게 따라옵니까?
자동으로 안전하다고 보면 안 됩니다. 이전 뒤 토큰의 sub, owner_id, repository_id를 다시 추출해야 합니다. 클라우드 정책이 이전 전 저장소의 전체 subject를 고정하고 있다면 새 주체가 거부될 수 있습니다. 반대로 조건을 지나치게 넓히면 의도하지 않은 저장소가 역할을 얻을 수 있습니다.
OIDC 오류가 나면 장기 액세스 키로 되돌려도 됩니까?
장기 키로 즉시 되돌리는 것은 권장하지 않습니다. 먼저 토큰과 신뢰 정책의 불일치를 확인하고, 필요하다면 짧은 시간 동안 제한된 테스트 역할만 사용해야 합니다. 장기 키를 저장소 비밀에 넣으면 만료, 회수, 사용 추적이 별도 문제가 됩니다. 복구 중에도 브랜치와 Environment 조건은 유지해야 합니다.
자체 호스팅 Mac을 한 대만 운영해야 한다면 무엇부터 분리해야 합니까?
먼저 공개 코드가 실행되는 작업과 생산 서명 작업을 분리해야 합니다. 가능하면 Runner 레이블과 Environment 승인을 나누고, 서명 Keychain은 생산 배포 Job에서만 잠시 사용할 수 있도록 구성합니다. 작업 후 Keychain 잠금, 작업 공간 삭제, 캐시 검토를 수행해야 합니다. 한 대 운영은 임시 구조로 문서화하는 편이 안전합니다.