[GitHub Actions][OIDC] organization template opt-in 직후 immutable subject 저장소에 reusable workflow claim을 붙일 때 repo_id 조건과 environment 보호 규칙을 어떤 순서로 바꾸나

IT 리서치 노트

[GitHub Actions][OIDC] organization template opt-in 직후 immutable subject 저장소에 reusable workflow claim을 붙일 때 repo_id 조건과 environment 보호 규칙을 어떤 순서로 바꾸나

GitHub Actions OIDC에서 organization template opt-in을 켠 뒤 immutable subject 저장소에 reusable workflow와 environment를 얹으면, GitHub 설정과 AWS trust policy를 무엇부터 바꿔야 할지 혼란스러워진다. 2026년 7월 23일 기준 GitHub 공식 문서를 다시 보면 org template, repo use_default, actual token, environment protection rules, AWS custom-claim 제약은 서로 다른 층이다. 이 글은 repo_id 조건과 environment 보호 규칙을 어떤 순서로 바꿔야 rollout이 짧아지는지 정리한다.

목차

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

1. 개요

결론부터 말하면 org template opt-in 이후에도 첫 판단 기준은 actual token이다. organization template는 선언 계층이고, repository의 use_default와 actual token sample이 실제 적용 계층이다. 따라서 repo_id 기반 immutable segment가 유지되는지, environment context가 어디에 붙는지, reusable workflow claim은 audit용인지 access-control용인지 먼저 나눠 봐야 한다.

AWS에서는 custom claim을 직접 trust policy 조건으로 쓰지 못하므로, reusable workflow를 붙였다고 곧바로 클라우드 조건을 job_workflow_ref 중심으로 바꾸면 안 된다. GitHub 쪽 trace는 넓히되, 클라우드 조건은 actual sub와 environment 보호 규칙 중심으로 천천히 옮기는 편이 맞다.

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

실무에서 가장 자주 꼬이는 지점은 네 층이 동시에 움직인다는 점이다. organization template opt-in을 켜면 관리자는 이제 org 전체가 immutable subject를 쓴다고 생각한다. 그런데 repository가 이미 use_default=false 상태로 별도 template를 쓰고 있으면 actual token은 예상과 다를 수 있다. 여기에 environment를 붙이면 sub context가 늘어나고, reusable workflow를 붙이면 custom claim이 추가된다.

이 상태에서 AWS trust policy까지 한 번에 바꾸면 실패 원인을 좁히기 어렵다. GitHub 문서는 template와 actual token sample을 REST API로 관리할 수 있다고 설명하고, AWS 문서는 custom claims를 직접 지원하지 않는다고 못 박고 있다. 즉 org template를 켠 것, repo가 실제로 template를 따르는 것, environment protection rules가 활성화된 것, 클라우드 trust policy가 그 변화를 반영한 것은 서로 다른 사건이다.

또 environment 이름을 sub에 넣는 일과 environment protection rules를 운영하는 일도 혼동하기 쉽다. environment 문서는 job이 environment를 참조하면 관련 protection rules를 따라야 한다고 설명한다. 따라서 sub 조건에만 environment를 넣고 protection rules를 방치하면, branch/tag 제한이 기대와 다르게 남거나 사라질 수 있다. access control과 deployment governance가 분리되지 않으면 rollback도 어려워진다.

• 증상: org template를 켰는데 repo token sample이 기대와 다르다.
• 실패: use_default=false repository를 무시한 채 trust policy를 한 번에 바꾼다.
• 막힘: reusable workflow claim을 곧바로 AWS trust condition에 쓰려 한다.
• 누락: environment protection rules와 sub context 변경을 같은 rollout 카드에 적지 않는다.

층	GitHub에서 확인할 값	왜 따로 봐야 하나
Organization template	include_claim_keys, use_immutable_subject	org 기본값일 뿐 repo override 가능성이 있다
Repository state	use_default, actual token sample	실제 적용 계층이라 rollout 실패 원인을 좁힌다
Environment governance	environment name, protection rules	sub context와 배포 보호가 같이 움직여야 한다
Reusable workflow trace	job_workflow_ref claim	AWS에선 audit log 용도로 보는 편이 현실적이다

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

가장 짧은 rollout 순서는 여섯 단계다. 첫째, org template의 include_claim_keys와 use_immutable_subject 값을 저장한다. 둘째, 대상 repo의 use_default와 include_claim_keys를 다시 조회한다. 셋째, environment를 붙이기 전과 후의 actual token sample을 각 한 번씩 저장한다. 넷째, environment protection rules를 branch/tag 정책과 같이 기록한다. 다섯째, reusable workflow를 붙인 뒤 job_workflow_ref가 늘어났는지만 audit log에 남긴다. 여섯째, AWS trust policy는 actual sub 예시와 environment context를 먼저 반영하고, 오래된 name-based 조건은 성공을 본 뒤 제거한다.

1. org template의 include_claim_keys와 use_immutable_subject를 저장한다.
2. repo별 use_default와 override 상태를 다시 확인한다.
3. actual token sample을 environment 전후로 각각 남긴다.
4. environment protection rules를 같은 rollout 문서에 적는다.
5. job_workflow_ref는 audit log 확장으로만 다룬다.
6. AWS trust policy는 actual sub와 environment context부터 옮긴다.

이 순서가 중요한 이유는 rollback이 쉬워지기 때문이다. trust policy 실패가 났을 때 org template가 문제인지, repo override가 문제인지, environment 보호 규칙이 막은 것인지, reusable workflow trace만 늘어난 것인지 한 번에 나눌 수 있다. 특히 immutable subject 저장소에서는 repo segment가 repo_id 기반으로 안정적이므로, 환경이 늘어나더라도 그 안정적인 중심축 위에 context만 덧붙는 구조로 이해하는 편이 덜 흔들린다.

# 1) org template
gh api orgs/ORG/actions/oidc/customization/sub

# 2) repo state
gh api repos/OWNER/REPO/actions/oidc/customization/sub

# 3) token sample after attaching environment
sub=repo:ORG@OWNER_ID/REPO@REPO_ID:environment:production

# 4) audit reusable workflow claim
job_workflow_ref=ORG/platform/.github/workflows/deploy.yml@refs/heads/main

# 5) AWS trust policy still keys off actual sub + aud
"token.actions.githubusercontent.com:sub": "repo:ORG@OWNER_ID/REPO@REPO_ID:environment:production"

이미 name 기반 sub와 immutable subject 분기 글, use_default drift 글, immutable subject 뒤 reusable workflow/environment 글을 읽었다면, 이번 순서는 그 셋을 실제 rollout 카드로 엮는 단계다.

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

첫 화면은 OIDC reference가 organization 또는 repository subject template을 REST API로 관리할 수 있다고 설명하는 구간이다. 여기서 template와 actual token은 다른 층이라는 전제를 먼저 고정해야 한다.

GitHub OIDC reference는 subject claim customization template을 REST API로 관리할 수 있다고 설명한다.

즉 organization template opt-in은 선언 계층이고, 실제로 repo가 그 템플릿을 따르는지는 repository 상태와 actual token을 따로 확인해야 한다. template를 켰다고 바로 sub가 바뀌었다고 가정하면 rollout 순서가 꼬인다.

두 번째 자료는 REST OIDC 엔드포인트 문서다. org template과 repo template에서 어떤 필드를 읽어야 하는지 여기서 명확해진다.

GitHub REST OIDC 문서는 organization template의 include_claim_keys와 use_immutable_subject, repository 상태의 use_default를 따로 돌려준다고 보여 준다.

이 차이가 핵심이다. org template가 immutable subject를 켜도, repo가 use_default=false로 별도 설정을 쓰고 있으면 actual token이 기대와 다를 수 있다.

세 번째 화면은 reusable workflow OIDC 문서다. reusable workflow를 붙이면 actual token에 어떤 custom claim이 늘어나는지 여기서 확인한다.

GitHub는 reusable workflow를 쓸 때 job_workflow_ref 같은 custom claim이 token에 들어간다고 설명한다.

하지만 AWS는 이 custom claim을 직접 trust condition으로 쓰지 못한다. 따라서 actual sub, repo_id 기반 immutable segment, environment context를 먼저 보고 나서 audit용 claim을 따로 남겨야 한다.

네 번째 자료는 environments 문서다. environment 이름을 subject에 넣는 일과 environment protection rules를 운영하는 일은 묶여 있지만 같은 단계는 아니다.

GitHub environments 문서는 environment를 참조한 job이 protection rules를 따라야 한다고 설명한다.

그래서 environment를 sub 조건에 반영할 때는 trust policy와 함께 protection rules도 같은 rollout 카드에 적는 편이 안전하다. sub만 바꾸고 rules를 그대로 두면 기대한 branch/tag 보호가 빠질 수 있다.

다섯 번째 화면은 AWS 제약을 못 박는 문장이다. 실제 trust policy에서는 sub와 aud가 중심이라는 사실을 다시 확인하는 단계다.

GitHub의 AWS OIDC 가이드는 AWS에서 OIDC custom claims를 직접 지원하지 않는다고 명시한다.

이 때문에 reusable workflow claim rollout은 GitHub 쪽 trace 확장으로 보고, AWS 조건은 repo_id 기반 sub와 environment context 중심으로 유지하는 편이 현실적이다.

운영팀이 제일 필요한 것은 rollout 순서표다. org template opt-in, repo use_default, reusable workflow claim, environment protection rules, AWS trust policy를 어떤 순서로 만질지 한 장으로 보여 줘야 한다.

organization template opt-in 뒤 immutable subject 저장소에 reusable workflow와 environment를 얹을 때의 rollout 순서표다.

이미 organization template opt-in 검증 글과 immutable subject 뒤 reusable workflow/environment 글을 읽었다면, 이 표는 그 둘을 한 장으로 연결하는 운영판이다.

5. 주의사항과 리스크

첫 번째 리스크는 org template opt-in을 실제 토큰 적용과 동일시하는 것이다. 두 번째는 environment context를 trust policy에 넣으면서 protection rules 변경을 빼먹는 것이다. 세 번째는 reusable workflow claim이 생겼다고 곧바로 AWS 조건도 그 claim 중심으로 다시 쓰는 것이다.

운영 전에는 최소한 org template 값, repo override 값, actual token sample, environment protection rules, AWS trust policy 문자열을 한 표에 두는 편이 좋다. 이렇게 해야 이름 기반 조건 제거 시점과 rollback 지점을 놓치지 않는다.

• org template와 repo actual state를 분리해서 기록한다.
• environment context 변경과 protection rules 변경을 같은 카드에 넣는다.
• AWS에서는 custom claim보다 actual sub 정합성을 먼저 본다.

6. 결론

organization template opt-in 직후 immutable subject 저장소에 reusable workflow와 environment를 붙일 때는 GitHub 설정을 한 번에 믿지 않는다. org template, repo override, actual token, environment protection rules, AWS trust policy를 서로 다른 단계로 나누고, actual sub를 중심으로 rollout하면 실패 범위를 훨씬 빨리 좁힐 수 있다.

같은 GitHub OIDC 가지의 선행 글로는 organization template opt-in 검증 글, name 기반 sub와 immutable subject 분기 글, immutable subject 뒤 reusable workflow/environment 글을 같이 보면 좋다.

7. 참고 링크

1. https://docs.github.com/actions/reference/openid-connect-reference
2. https://docs.github.com/en/rest/actions/oidc
3. https://docs.github.com/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows
4. https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
5. https://docs.github.com/actions/deployment/targeting-different-environments/using-environments-for-deployment