[GitHub Actions][OIDC] AWS trust policy에서 repo 이름 기반 sub와 owner_id/repo_id 기반 immutable subject를 언제 나눠야 하나

IT 리서치 노트

[GitHub Actions][OIDC] AWS trust policy에서 repo 이름 기반 sub와 owner_id/repo_id 기반 immutable subject를 언제 나눠야 하나

GitHub Actions OIDC를 AWS에 붙여 쓰다 보면 trust policy를 한 번 정해 두고 오래 재사용하고 싶어진다. 그런데 2026년 7월 19일 기준 GitHub 공식 문서를 다시 보면 저장소 생성 시점, immutable subject opt-in, repository customization 상태에 따라 sub 형식이 달라질 수 있다. 이 글은 AWS trust policy에서 repo 이름 기반 sub와 owner_id/repo_id 기반 immutable subject를 언제 분리해서 보는 편이 빠른지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 AWS trust policy를 짤 때는 먼저 저장소가 이름 기반 sub를 내는지, owner_id/repo_id가 들어간 immutable subject를 내는지부터 나눠야 한다. 2026년 7월 15일 이후 생성 저장소와 immutable subject opt-in 저장소는 같은 organization 안에서도 기본 sub 형식이 다를 수 있다.

AWS는 custom claims를 별도 조건으로 지원하지 않으므로, 결국 실제 sub 문자열과 trust policy 정합성이 핵심이다. workflow에 environment를 붙였는지보다 repository OIDC 상태와 저장소 생성 시점이 더 먼저 갈릴 수 있다.

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

현장에서 자주 막히는 상황은 비슷하다. 같은 GitHub organization 안에서 어떤 저장소는 AWS role assume이 되고 어떤 저장소는 안 된다. workflow YAML은 거의 같고 environment도 붙어 있는데도 sub mismatch가 난다. 이때 많은 팀이 environment 이름이나 include_claim_keys만 계속 바꾼다.

하지만 GitHub OIDC 문서는 2026년 7월 15일 이전과 이후 저장소의 기본 sub 형식이 다를 수 있다고 설명하고, immutable subject를 쓰는 저장소에서는 owner_id와 repo_id가 repo segment에 항상 남는다고 적는다. 여기에 repository customization의 use_default와 use_immutable_subject 상태까지 얹히면, YAML만 보고 실제 sub를 추정하는 것은 위험하다.

• 증상: 같은 org인데 어떤 repo만 AWS trust policy mismatch가 난다.
• 실패: workflow의 environment만 보고 sub 형식을 추정한다.
• 막힘: org template를 바꾼 뒤 repo use_default 상태를 확인하지 않는다.
• 누락: 저장소 생성일과 immutable subject opt-in 여부를 기록하지 않는다.

특히 AWS에서는 custom claims를 기대할 수 없으므로 이름 기반 sub와 immutable subject를 별도 정책 분기 없이 한 줄 wildcard로 덮으려는 시도가 오히려 길을 잃게 만든다. 첫 단계는 더 많은 claim이 아니라, 지금 토큰이 어떤 기본 형식을 내고 있는지 확인하는 것이다.

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

실무 순서는 다섯 단계면 충분하다. 먼저 저장소가 실제로 어떤 sub를 내는지 토큰 예시를 기록한다. 다음으로 repository OIDC customization에서 use_default와 use_immutable_subject를 조회한다. 세 번째로 저장소 생성 시점이 2026년 7월 15일 전인지 후인지 확인한다. 네 번째로 AWS trust policy를 실제 sub 형식에 맞춰 나눈다. 마지막으로 필요하면 organization template까지 올라가서 opt-in 여부를 본다.

1. 실제 토큰의 sub 예시를 먼저 남긴다.
2. repo OIDC customization의 use_default와 use_immutable_subject를 조회한다.
3. 저장소 생성 시점을 2026년 7월 15일 기준으로 나눈다.
4. AWS trust policy는 이름 기반과 immutable 형식을 따로 검토한다.
5. 필요하면 organization template opt-in 여부를 역추적한다.

이렇게 보면 environment context 문제와 immutable subject 전환 문제를 같은 증상으로 섞지 않을 수 있다. 이미 claims를 먼저 검증하는 글이 사전 점검이었다면, 이번 글은 AWS trust policy를 유지보수 가능한 분기 구조로 정리하는 단계다.

gh api repos/OWNER/REPO/actions/oidc/customization/sub \
  --jq '{use_default, include_claim_keys, use_immutable_subject}'

# then compare with the actual AWS trust policy condition
"token.actions.githubusercontent.com:sub": "repo:ORG/REPO:ref:refs/heads/main"

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

첫 화면에서 먼저 볼 문장은 저장소 생성 시점에 따라 기본 sub 형식이 갈릴 수 있다는 점이다. 이 문장을 놓치면 새 저장소와 오래된 저장소를 같은 trust policy 문자열로 묶기 쉽다.

GitHub OIDC 문서는 2026년 7월 15일 전후와 immutable subject opt-in 여부에 따라 sub 기본 형식이 갈릴 수 있다고 적는다.

즉 AWS에서 같은 워크플로를 붙여도 어떤 저장소는 이름 기반 sub를 내고, 어떤 저장소는 owner_id와 repo_id가 들어간 immutable 형식을 낼 수 있다. environment만 봐서는 설명이 안 되는 이유가 여기서 생긴다.

두 번째 화면은 immutable subject를 조금 더 직접적으로 보여 준다. GitHub는 immutable 형식에서 owner_id와 repo_id를 빼지 못한다고 설명한다.

immutable subject를 쓰는 저장소는 custom claim 조합을 바꿔도 owner_id와 repo_id가 repo segment에 남는다.

그래서 기존에 repo 이름 문자열만 맞추던 AWS trust policy는 immutable 전환 뒤 그대로 실패할 수 있다. 커스텀 claim을 더 넣는 문제가 아니라, sub 뼈대 자체가 달라지는 문제다.

세 번째 자료는 REST API에서 repository OIDC 상태를 읽는 구간이다. 여기서 use_default와 use_immutable_subject를 별도로 보지 않으면 조직 template와 저장소 opt-in 상태를 한 덩어리로 오해하게 된다.

GitHub REST API는 repository customization에서 use_default와 use_immutable_subject를 별도 필드로 둔다.

실무에서는 이 두 값이 실제 sub 형식 추정의 출발점이다. environment를 붙였는데 AWS 조건이 안 맞을 때 YAML만 뒤집지 말고 저장소 OIDC 상태부터 조회해야 하는 이유다.

네 번째 화면은 AWS 쪽 제약을 못 박아 준다. AWS에서는 GitHub OIDC custom claims를 별도 조건으로 해석해 주지 않는다는 점을 먼저 인정해야 설계가 덜 돌아간다.

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

즉 AWS에서는 실제 sub 문자열과 aud 같은 표준 claim 정합성이 더 중요하다. claim key를 늘려서 해결할 수 있다고 생각하면 trust policy 설계가 과해지고 디버깅만 길어진다.

마지막 표는 이름 기반 sub와 immutable subject를 언제 다르게 다뤄야 하는지 정리한 비교표다. 이 표가 있으면 저장소 생성일, opt-in 여부, AWS 정책 문자열을 한 장에서 같이 볼 수 있다.

repo 이름 기반 sub와 immutable subject를 AWS trust policy 관점에서 비교한 표다.

이미 environment를 붙였는데 sub가 그대로일 때 보는 글을 읽었다면, 이번 글은 그보다 한 단계 넓은 trust policy 선택 기준이다. 또 organization template opt-in 글과 같이 보면 org 설정과 repo 상태를 분리하기 쉽다.

5. 주의사항과 리스크

첫 번째 리스크는 environment를 붙였다는 사실만으로 sub 형식도 원하는 방향으로 바뀌었다고 생각하는 것이다. 두 번째는 immutable subject로 바뀐 저장소에 예전 이름 기반 trust policy를 그대로 두는 것이다. 세 번째는 AWS가 custom claims를 지원하지 않는데도 claim key를 늘리면 해결될 것이라고 기대하는 것이다.

운영 전에는 저장소별로 현재 sub 예시, repo OIDC 상태, immutable subject 여부, AWS trust policy 문자열을 한 표로 남기는 편이 좋다. 그래야 rename, transfer, 새 저장소 생성 같은 이벤트 뒤에도 어디부터 다시 봐야 하는지 분명해진다.

6. 결론

AWS trust policy에서 이름 기반 sub와 immutable subject를 나누는 기준은 workflow 문법보다 저장소 OIDC 상태에 더 가깝다. 2026년 7월 15일 이후 생성 여부, immutable subject opt-in, repo customization 상태를 먼저 기록하면 같은 sub mismatch를 훨씬 짧게 분리할 수 있다.

관련 글로는 environment를 붙였는데 sub가 그대로일 때 보는 글, organization template opt-in 글, rollback 계획 글을 같이 보면 좋다.

같은 GitHub OIDC AWS 흐름에서 use_default를 false로 바꿨는데도 include_claim_keys와 actual subject가 계속 어긋난다면 어느 API 응답과 trust policy부터 다시 맞출지 정리한 후속 글을 이어서 보면 좋다. 이번 글이 name 기반 sub와 immutable subject를 나누는 큰 분기라면, 그 글은 그다음 단계인 REST 응답값과 actual token drift를 다룬다.

7. 참고 링크

1. https://docs.github.com/en/actions/reference/security/oidc
2. https://docs.github.com/en/rest/actions/oidc
3. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws