[GitHub Actions][OIDC] organization template를 repo에 opt-in하기 전에 현재 sub 형식과 immutable subject 시점을 같이 검증하는 법

IT 리서치 노트

[GitHub Actions][OIDC] organization template를 repo에 opt-in하기 전에 현재 sub 형식과 immutable subject 시점을 같이 검증하는 법

GitHub Actions OIDC subject customization을 organization 단위로 밀기 시작하면 많은 팀이 `include_claim_keys`만 보고 바로 cloud trust policy를 바꾼다. 하지만 2026년 7월 2일 기준 GitHub 공식 문서를 다시 보면, repository 생성 시점과 immutable subject opt-in 여부에 따라 실제 `sub` 형식이 달라질 수 있고, repository는 `use_default` 상태를 따로 가진다. 이 글은 organization template를 repo에 opt-in하기 전에 현재 `sub` 형식과 2026년 7월 15일 전후 규칙을 같이 검증하는 순서를 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 organization template를 넣기 전에 먼저 각 repository가 지금 어떤 sub를 내보내는지 메모해야 한다. 2026년 7월 15일 이후 생성 저장소는 immutable subject 기본 형식이 적용될 수 있고, 그 이전 저장소는 opt-in 전까지 이름 기반 형식을 유지할 수 있다. 여기에 repository의 use_default, use_immutable_subject 상태까지 얹히면, 조직 템플릿만 보고 실제 claims를 추정하는 것은 위험하다.

이미 custom subject claim 템플릿을 적용하기 전에 repo와 environment 조건을 정리하는 글이 claim key 설계를 다뤘다면, 이번 글은 rollout 시점과 실제 sub 검증 순서에 더 가깝다. 또 실제 claims 로그와 trust policy를 같이 검증하는 글은 이미 바뀐 뒤를 보는 글이고, 오늘은 그 바꾸기 전 점검이다.

organization template rollout 전에 실패 복구 문서까지 같이 잡고 싶다면 오늘 발행한 CI 배포 토큰을 OIDC로 바꿀 때 rollback 계획을 어디까지 남겨야 하는지 정리한 글이 자연스럽게 이어진다. preflight와 rollback 기준을 같은 사다리로 보면 첫 전환 장애 대응이 짧아진다.

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

현장에서 흔한 실패는 세 가지다. 첫째, organization template를 만들자마자 모든 repository가 같은 형식의 sub를 낼 것이라고 가정한다. 둘째, immutable subject opt-in 여부를 빼먹고 cloud trust policy에 이름 기반 문자열만 남긴다. 셋째, 2026년 7월 15일 전후 생성 시점을 무시해 신규 repo와 기존 repo의 기본값이 같다고 본다.

GitHub OIDC reference는 immutable subject claim 형식을 별도 섹션으로 설명하고, 저장소 생성 날짜와 opt-in 여부를 같이 적고 있다. REST API 문서는 organization과 repository 모두 customization template endpoint를 제공하지만, repository 쪽에는 use_default와 use_immutable_subject 상태가 따로 나온다. 이 두 출처를 같이 읽으면 rollout 판단은 'org template 존재 여부'가 아니라 'repo가 어떤 상태로 그 템플릿을 실제 반영하는가'의 문제라는 점이 보인다.

AWS처럼 custom claims 지원이 없는 provider에서는 이 차이가 더 크게 드러난다. GitHub의 AWS guide는 custom claims 지원이 없다고 명시하므로, 실제 배포 허용 여부는 결국 sub 문자열과 aud에 더 많이 걸린다. 그래서 claim key 설계를 조직 차원에서 바꾸더라도, trust policy는 현재 sub 형식 기준으로 먼저 검증해야 한다.

• 증상: organization template rollout 뒤 일부 repo만 role assume에 실패한다.
• 실패: repo의 use_default 상태를 확인하지 않고 org 설정만 읽는다.
• 막힘: immutable subject opt-in 뒤에도 기존 이름 기반 trust 문자열을 남겨 둔다.
• 누락: 2026년 7월 15일 전후 생성 시점 차이를 메모하지 않는다.

상황	먼저 볼 곳	판단 기준
기존 repo rollout	repo use_default, 현재 sub	org template만으로 현재 토큰 형식을 추정하지 않는다
새 repo 도입	생성 시점과 immutable subject 기본값	2026-07-15 이후 repo는 ID 포함 형식을 기대한다
AWS trust 검증	sub 문자열과 aud	claim key 확대보다 현재 sub diff를 먼저 본다

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

실무 검증 순서는 다섯 단계가 가장 짧다. 먼저 organization template 응답을 읽어 어떤 claim key를 목표로 하는지 정리한다. 두 번째로 각 repository의 use_default와 use_immutable_subject 상태를 조회한다. 세 번째로 현재 cloud trust policy가 이름 기반 문자열을 기대하는지, ID 포함 문자열을 기대하는지 메모한다. 네 번째로 repository 생성 시점이 2026년 7월 15일 전인지 후인지 구분한다. 마지막으로 이 네 값을 맞춰 본 뒤에야 rollout과 opt-in 순서를 정한다.

1. organization template 응답을 먼저 기록한다.
2. repository별 use_default, use_immutable_subject를 조회한다.
3. 현재 trust policy가 기대하는 sub 형식을 적어 둔다.
4. repository 생성 날짜를 2026년 7월 15일 기준으로 나눈다.
5. 그다음에 rollout 순서와 opt-in 대상을 정한다.

핵심은 organization의 '의도'와 repository의 '실제 상태'를 분리하는 것이다. organization template는 방향을 정하지만, repository가 어떤 상태로 그 설정을 따라가는지는 별도 체크가 필요하다. REST API 문서가 organization endpoint와 repository endpoint를 따로 제공하는 것도 같은 이유로 읽는 편이 맞다. 이 부분은 문서 구조를 바탕으로 한 운영 해석이다.

rollout 메모 예시

org_template=repo,context
repo_a.use_default=true
repo_a.use_immutable_subject=false
repo_b.use_default=false
repo_b.use_immutable_subject=true
trust_policy_expected_sub=name_based
new_repo_cutoff=2026-07-15

이렇게 메모를 먼저 남겨 두면 rollout 뒤 문제를 봤을 때도 'org template가 잘못됐나'보다 'repo state와 trust policy가 어떤 조합이었나'를 더 빨리 좁힐 수 있다.

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

첫 화면은 GitHub OIDC reference의 immutable subject claims 구간이다. 여기서는 기본 `sub` 형식이 이름 기반에서 owner ID와 repository ID를 포함하는 형식으로 바뀌고 있다는 점을 먼저 확인해야 한다.

GitHub OIDC reference는 immutable subject claim 형식과 이름 기반 형식의 차이를 직접 보여 준다.

조직 템플릿을 넣기 전에 이 차이를 먼저 보는 이유는 간단하다. trust policy가 아직 이름 기반 `sub` 문자열을 기대하는데 immutable subject가 들어오면, 템플릿 설계가 맞아도 배포는 막힐 수 있다.

두 번째 자료는 시점 규칙이다. 2026년 7월 2일 기준 GitHub 문서는 2026년 7월 15일 이전에 만들어진 저장소는 opt-in 전까지 기존 형식을 유지한다고 설명한다.

GitHub 문서는 2026년 7월 15일 이전 저장소와 이후 저장소의 기본 `sub` 형식이 달라질 수 있다고 적고 있다.

즉 지금 rollout을 준비하는 팀은 '우리 저장소가 언제 만들어졌는가'와 '이미 opt-in 했는가'를 같이 확인해야 한다. 날짜만 보고 넘기거나, 반대로 템플릿만 보고 날짜를 무시하면 검증 순서가 어긋난다.

세 번째 화면은 organization OIDC subject customization template를 읽는 REST API다. rollout 전에 현재 조직 템플릿이 무엇을 포함하려는지 읽어 두어야 repo별 검증 결과와 비교할 수 있다.

GitHub REST 문서는 organization 단위 OIDC customization template 조회 경로를 제공한다.

여기서 중요한 점은 organization template가 '있다'는 사실 자체보다, repo가 그 설정을 따라가는 상태인지 별도로 확인해야 한다는 점이다. 이 판단은 바로 다음 repository endpoint에서 갈린다.

네 번째 자료는 repository 단위 확인 메모다. REST 문서의 필드를 그대로 옮겨 적어 두면 repo별 opt-in 상태를 조회할 때 어떤 값을 저장해야 하는지 명확해진다.

Repository OIDC customization 확인 메모 예시다.

문서에 따르면 repository 응답에는 use_default 상태가 남고, 설정 API는 use_default와 use_immutable_subject를 따로 받는다. 따라서 repo opt-in 여부와 immutable subject 여부를 동시에 메모하지 않으면 현재 sub를 잘못 추정하기 쉽다. 이 부분은 repository-level 상태와 org-level 의도를 같이 읽어야 하는 해석이다.

다섯 번째 화면은 AWS guide의 주의 문구다. AWS에서는 custom claims 지원이 없다고 문서가 직접 적고 있으므로, 결국 trust policy 검증은 `sub`와 `aud`를 더 엄격하게 보는 쪽으로 귀결된다.

GitHub의 AWS OIDC guide는 AWS에서 custom claims 지원이 없다고 명시한다.

그래서 조직 템플릿 rollout을 AWS trust policy와 연결하는 팀이라면, claim key를 늘리는 일보다 현재 `sub` 문자열이 이름 기반인지 immutable 기반인지부터 분리해야 한다. 이미 실제 claims 로그와 trust policy를 같이 검증하는 글을 읽었다면 이번 글은 그보다 한 단계 앞선 rollout 판단이다.

이 표는 현재 `sub` 형식과 rollout 뒤 `sub` 형식을 한 번에 비교하기 위한 것이다. 실제 검증 메모 없이 템플릿만 바꾸면 여기서 가장 많이 어긋난다.

이름 기반 `sub`, immutable `sub`, repo opt-in 여부를 함께 보는 비교표다.

팀 문서에 이 표를 남겨 두면 cloud trust policy, GitHub repo state, 조직 rollout 일정을 서로 다른 화면에서 따로 기억하지 않아도 된다. post 48이 claim key 설계를 설명했다면 이번 표는 rollout 전후 diff 메모에 더 가깝다.

마지막 자료는 rollout 전에 남겨 둘 REST API 점검 메모다. org와 repo 응답을 나란히 남기면 실제 rollout 전후 차이를 추적하기 쉽다.

org와 repo의 OIDC customization 응답을 함께 기록하는 메모 예시다.

이 메모가 있으면 repo별 `use_default` 상태, immutable subject opt-in 여부, trust policy 수정 시점을 한 번에 연결할 수 있다. 이미 subject template를 바꾸기 전 claims를 먼저 검증하는 글을 읽었다면, 이번 로그는 그 preflight를 조직 rollout 단위로 확장한 것이다.

5. 주의사항과 리스크

첫 번째 리스크는 organization template를 바꾸면 기존 repository가 자동으로 같은 형식의 sub를 낼 것이라고 보는 것이다. 두 번째 리스크는 immutable subject opt-in과 trust policy 갱신을 따로 배포해 중간 상태를 남기는 것이다. 세 번째 리스크는 AWS처럼 custom claims를 직접 못 쓰는 provider에서도 claim key 설계만 바꿔 해결될 것이라고 기대하는 것이다.

운영 전에는 최소한 현재 sub 예시 한 줄, repository 상태, 생성 시점, trust policy 기대값 네 가지를 남겨 두는 편이 좋다. 이 네 가지가 없으면 rollout 이후 에러가 template 문제인지, 날짜 규칙 문제인지, immutable subject opt-in 문제인지 분리하기 어렵다.

• organization template와 repository 상태를 같은 것으로 보지 않는다.
• 2026년 7월 15일이라는 날짜 조건을 문서화한다.
• trust policy는 실제 sub 예시로 검증한다.

6. 결론

GitHub Actions OIDC organization template rollout은 claim key 설계만의 문제가 아니라 현재 repository의 sub 형식과 immutable subject 시점을 같이 읽는 작업이다. 2026년 7월 15일 전후 규칙, repo의 use_default와 use_immutable_subject, cloud trust policy 기대값을 먼저 맞춰 두면 rollout 뒤 claims mismatch를 크게 줄일 수 있다.

• org template보다 먼저 repo 상태와 현재 sub를 확인한다.
• immutable subject는 날짜와 opt-in 상태를 같이 본다.
• trust policy는 실제 예시 문자열로 검증한다.

7. 참고 링크

1. https://docs.github.com/en/actions/reference/security/oidc
2. https://docs.github.com/en/rest/actions/oidc?apiVersion=2026-03-10
3. https://docs.github.com/actions/security-for-github-actions/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services