[GitHub Actions][OIDC] enterprise custom issuer 뒤 GCP Workload Identity에서 repo_property와 immutable sub를 같이 쓸 때 어떤 assertion diff부터 남기나

IT 리서치 노트

[GitHub Actions][OIDC] enterprise custom issuer 뒤 GCP Workload Identity에서 repo_property와 immutable sub를 같이 쓸 때 어떤 assertion diff부터 남기나

GitHub Actions OIDC에서 enterprise custom issuer를 켠 뒤 GCP Workload Identity Provider 조건을 더 좁히려 하면 많은 팀이 repo_property 같은 커스텀 속성부터 condition 식에 넣고 싶어진다. 하지만 2026년 8월 13일 기준 Google Cloud와 GitHub 공식 문서를 같이 보면 GCP는 최소한 google.subject를 assertion.sub에 매핑하라고 하고, GitHub는 include_claim_keys로 subject를 바꿔도 immutable ID가 repo segment에 계속 남는다고 설명한다. 이 글은 enterprise custom issuer 뒤 GCP Workload Identity에서 repo_property와 immutable sub를 같이 쓸 때 어떤 assertion diff부터 남겨야 provider condition drift를 덜 헷갈리게 하는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 GCP branch에서는 첫 assertion diff에 google.subject, raw sub, immutable ID 포함 여부, 그리고 현재 attribute condition을 같이 적는 편이 맞다. repo_property는 그다음 좁히기 층이지 subject baseline을 대신하지 못한다.

즉 첫 질문은 "property가 condition에 들어갔는가"보다 "현재 live sub 형식과 google.subject 매핑이 provider가 기대하는 baseline과 같은가"다. subject 기준선이 흔들리면 custom property 조건을 손대도 incident가 다시 돌아온다.

2. 어디서 실제로 막히는가

실무에서 자주 막히는 패턴은 네 가지다. 첫째, immutable sub 전환을 놓친 채 attribute condition에 repo_property만 더 붙인다. 둘째, provider mapping에는 google.subject만 있고 repository_id나 repository_owner_id 증거를 메모에 남기지 않는다. 셋째, organization scope allowlist와 custom property narrowing을 하나의 condition 식으로 묶어 어느 부분이 false인지 알기 어렵게 만든다. 넷째, GitHub 쪽 include_claim_keys 변경과 GCP provider 조건 수정을 같은 배포에 묶는다.

Google Cloud 문서는 최소한 google.subject를 assertion.sub에 매핑하라고 하고, GitHub OIDC reference는 immutable IDs가 custom subject에서도 repo segment에 남는다고 적고 있다. 따라서 GCP에서 repo_property를 쓰더라도 subject baseline을 먼저 고정해야 한다. 이 단계를 건너뛰면 provider condition이 false인 이유가 owner scope인지, property 누락인지, immutable sub drift인지 분해되지 않는다.

• 증상: 같은 provider인데 일부 저장소만 GCP auth가 실패한다.
• 실패: google.subject와 raw sub를 따로 저장하지 않는다.
• 막힘: repo_property condition을 먼저 넓혔다 좁히며 subject baseline drift를 놓친다.
• 누락: immutable ID 포함 여부를 assertion diff에 넣지 않는다.

3. 실무에서 적용하는 순서

실무 순서는 다섯 단계가 짧다. 첫째, live token에서 raw sub, repository_id, repository_owner_id를 저장한다. 둘째, provider mapping에서 google.subject와 어떤 custom attribute를 쓰는지 적는다. 셋째, 현재 attribute condition을 함께 저장한다. 넷째, organization allowlist와 custom property narrowing을 분리해 어느 식이 false인지 따로 본다. 다섯째, 그다음에야 service account binding이나 principalSet 범위를 다시 본다.

1. raw sub와 immutable ID claim을 저장한다.
2. google.subject와 custom attribute mapping을 저장한다.
3. 현재 attribute condition을 그대로 복사해 둔다.
4. baseline과 custom narrowing을 나눠 어떤 식이 false인지 본다.
5. 그다음 binding과 principalSet 범위를 점검한다.

이 단계에서는 GCP 콘솔 화면에서 provider 설정을 조회하고, attribute condition 필드와 mapping 필드를 확인하고, GitHub workflow YAML 파일과 로그 응답을 같이 열어 비교해야 한다. provider 화면, YAML 코드, 로그 응답, 설정 필드, 서비스 계정 이름, 경로 값을 한 표에 저장하면 어떤 조건을 다시 실행하고 어떤 값을 다시 입력해야 하는지가 선명해진다.

확인 메모 예시

raw_sub=repo:example-org@123456/example-repo@987654:ref:refs/heads/main
google_subject=repo:example-org@123456/example-repo@987654:ref:refs/heads/main
attribute.repo_property_workspace_id=ws-prod
condition_scope=assertion.repository_owner=='example-org'
condition_property=assertion.repo_property_workspace_id=='ws-prod'

이렇게 baseline과 narrowing을 나눠 기록하면 repo_property 실수와 immutable sub 전환을 따로 자를 수 있다. 이미 immutable sub 전환 글이 subject 형식 자체를 다뤘다면, 이번 글은 그 subject를 GCP provider condition에 어떻게 연결해 읽을지에 더 가깝다.

4. 공식 문서와 예시 화면으로 확인하기

첫 실제 자료는 GitHub의 GCP OIDC 가이드다. 이 가이드는 GitHub OIDC token을 Workload Identity Federation으로 Google Cloud access token으로 바꾸는 흐름 자체를 먼저 보여 준다.

GitHub Docs는 GitHub OIDC token을 Google Cloud access token으로 바꾸는 흐름을 Workload Identity Federation 맥락에서 설명한다.

즉 repo_property 같은 추가 attribute를 붙이더라도 출발점은 여전히 기본 subject와 provider exchange 흐름이다. 첫 assertion diff를 남길 때 sub를 빼먹고 custom property부터 보면 trust condition이 왜 거부됐는지 분리가 늦어진다.

두 번째 자료는 GitHub GCP 예제 YAML이다. provider 경로와 service account 입력이 실제 workflow 파일에서 어떻게 드러나는지 먼저 확인해야 한다.

GitHub Docs의 GCP 예제는 workload_identity_provider와 service_account 입력을 workflow 설정에서 직접 보여 준다.

그래서 GCP branch는 provider 경로, service account, subject baseline을 같은 메모에 저장해야 한다. workflow 설정 값과 provider condition 메모를 분리하지 않으면 repo_property와 immutable sub가 뒤섞인다.

세 번째 자료는 GitHub OIDC reference의 immutable subject 문장이다. include_claim_keys를 쓰더라도 immutable ID는 repo segment에 계속 남는다.

GitHub OIDC reference는 include_claim_keys로 subject를 커스터마이즈해도 immutable ID가 repo segment에 계속 포함된다고 설명한다.

이 문장 덕분에 GCP에서 첫 assertion diff를 무엇부터 볼지 정할 수 있다. custom property 조건이 붙었더라도 live sub 형식이 먼저 바뀌었는지 확인해야 provider condition을 잘못 고치지 않는다.

GCP에서 특히 자주 섞이는 값은 google.subject, attribute.repository_owner, repo_property, immutable ID 포함 여부다. 비교표로 고정해 두면 반복 triage가 빨라진다.

GCP Workload Identity에서 assertion diff를 남길 때 먼저 구분할 축을 정리한 비교표다.

이미 cross-cloud allowlist 글이 GCP condition을 큰 그림으로 다뤘다면, 이번 표는 그 안에서 immutable sub와 repo_property를 따로 자르는 후속편이다.

마지막 자료는 실제 운영 메모 형식이다. GCP는 provider mapping과 condition을 같이 적어 두는 편이 재현성이 높다.

repo_property와 immutable sub를 함께 볼 때 남기면 좋은 GCP assertion diff 메모 예시다.

이 메모를 남겨 두면 sub 형식 전환 문제인지, provider condition이 repo_property를 아직 못 받는 문제인지 빠르게 분리할 수 있다. 이후 principalSet이나 service account binding을 보는 순서가 된다.

5. 주의사항과 리스크

첫 번째 리스크는 repo_property condition을 더하는 순간 subject baseline도 자동으로 맞을 것이라고 생각하는 것이다. 두 번째 리스크는 owner allowlist와 custom property narrowing을 하나의 긴 condition 식으로만 남겨 false 지점을 못 찾는 것이다. 세 번째 리스크는 immutable ID 포함 여부를 빼고 repository 이름만 메모하는 것이다.

• google.subject baseline을 빼면 provider condition drift 원인이 섞인다.
• immutable ID 전환 뒤에도 이름 기반 추정만 하면 false condition을 반복한다.
• condition 식은 scope와 property narrowing으로 나눠 적는 편이 회고 품질이 높다.

6. 결론

enterprise custom issuer 뒤 GCP Workload Identity를 더 좁힐 때도 첫 기준선은 여전히 sub와 google.subject다. immutable sub 형식과 provider condition을 먼저 맞춘 뒤 repo_property를 얹는 순서를 지켜야, 같은 provider 조건 오류를 여러 번 고치지 않게 된다.

• raw sub와 google.subject를 먼저 고정한다.
• immutable ID 포함 여부를 assertion diff에 넣는다.
• 그 뒤 repo_property narrowing을 별도 식으로 붙인다.

7. 참고 링크

1. https://cloud.google.com/iam/docs/workload-identity-federation-with-deployment-pipelines
2. https://docs.github.com/actions/reference/openid-connect-reference
3. https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-google-cloud-platform