[GitHub Actions][OIDC] immutable subject로 이미 전환된 저장소에 reusable workflow나 environment claim을 추가할 때 trust policy 교체 순서를 어떻게 좁히나

IT 리서치 노트

[GitHub Actions][OIDC] immutable subject로 이미 전환된 저장소에 reusable workflow나 environment claim을 추가할 때 trust policy 교체 순서를 어떻게 좁히나

GitHub Actions OIDC를 AWS에 붙여 둔 저장소가 이미 immutable subject 형식으로 전환된 뒤, reusable workflow나 environment claim을 새로 붙일 때 trust policy가 다시 흔들리는 경우가 있다. 2026년 7월 23일 기준 GitHub 공식 문서를 다시 보면 environment는 sub에 들어가지만, immutable repo segment는 그대로 유지되고, reusable workflow는 job_workflow_ref 같은 custom claim을 추가한다. 이 글은 이미 immutable subject를 쓰는 저장소에서 새 claim을 얹을 때 trust policy 교체 순서를 어떻게 좁혀야 하는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 immutable subject 저장소에 environment나 reusable workflow를 추가할 때도 첫 단계는 actual token의 sub를 다시 보는 일이다. repo segment가 이미 ID 기반인지 확인한 뒤, environment가 뒤에 붙는지, reusable workflow 때문에 custom claim만 늘어난 것인지를 분리해야 한다.

AWS에서는 custom claims를 trust policy에서 직접 해석하지 않으므로, GitHub 쪽 설정을 늘리는 것보다 actual sub 예시와 AWS 조건을 먼저 맞추는 편이 빠르다. 그다음에야 org template, repo customization, reusable workflow 구조를 세밀하게 다듬는 순서가 된다.

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

실무에서 오래 끄는 이유는 세 층이 한 증상처럼 보이기 때문이다. immutable subject 저장소에 environment를 붙이면 sub 문자열이 달라지고, reusable workflow를 붙이면 토큰에 job_workflow_ref가 추가된다. 여기서 organization template까지 손대면 GitHub 쪽 상태와 AWS 쪽 문자열이 동시에 움직인다.

많은 팀이 environment를 붙였으니 기존 repo 이름 기반 조건만 살짝 바꾸면 된다고 생각하거나, reusable workflow를 썼으니 cloud provider도 job_workflow_ref를 직접 읽을 수 있을 것이라고 기대한다. 하지만 GitHub 문서는 immutable repo segment와 environment 포함 규칙을 따로 설명하고, AWS 가이드는 custom claims 미지원을 분명히 적고 있다.

• 증상: immutable 저장소에 environment를 붙인 뒤 role assume이 다시 흔들린다.
• 실패: environment 추가와 immutable repo segment를 같은 변경으로 본다.
• 막힘: reusable workflow 도입 뒤 job_workflow_ref만 보고 cloud 조건을 넓힌다.
• 누락: repo customization과 org template를 따로 기록하지 않는다.

질문	GitHub에서 보는 값	AWS에서 보는 값
repo 식별부가 무엇인가	immutable subject 여부	actual sub의 repo segment
environment가 반영됐는가	job environment 설정	sub의 environment suffix
reusable workflow를 좁힐 수 있는가	job_workflow_ref custom claim	AWS는 custom claims 직접 미지원

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

운영 순서는 다섯 단계면 충분하다. 첫째, 현재 저장소가 immutable subject 형식인지 API와 actual token으로 확인한다. 둘째, environment를 붙인 뒤 새 actual sub 예시를 로그에 남긴다. 셋째, reusable workflow를 붙였다면 job_workflow_ref 존재는 기록하되 AWS 신뢰 조건은 actual sub 중심으로 유지한다. 넷째, AWS trust policy는 새 sub 형식을 먼저 추가하고 성공을 확인한 뒤 오래된 조건을 제거한다. 다섯째, org template와 repo customization은 마지막에 정리한다.

1. immutable subject 여부를 actual token과 REST API로 확인한다.
2. environment 추가 뒤 새 sub 예시를 남긴다.
3. reusable workflow는 job_workflow_ref 기록용으로 보고, AWS 조건은 actual sub를 중심으로 둔다.
4. 새 trust policy 조건을 먼저 추가하고 성공을 본다.
5. 마지막에 old 조건과 rollout 메모를 정리한다.

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

# capture one actual token sample after adding environment
"token.actions.githubusercontent.com:sub":
"repo:ORG@OWNER_ID/REPO@REPO_ID:environment:production"

이 메모가 있으면 reusable workflow 추가와 environment 추가를 같은 원인으로 섞지 않을 수 있다. 특히 AWS가 custom claims를 직접 읽지 않는다는 점을 전제로 두면 job_workflow_ref는 감사용 단서이고, access control의 핵심은 여전히 actual sub라는 점이 분명해진다.

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

첫 화면은 GitHub OIDC reference의 immutable subject 구간이다. 이미 owner_id와 repo_id 기반 sub 형식으로 넘어간 저장소라면 이후 environment나 reusable workflow를 붙여도 이 기본 repo segment는 사라지지 않는다는 전제를 먼저 잡아야 한다.

GitHub는 immutable subject 저장소가 안정적인 owner_id와 repo_id 기반 sub 형식을 사용한다고 설명한다.

이 전제를 빼먹으면 environment를 붙였는데 왜 sub가 기대와 다르냐는 질문을 계속 반복하게 된다. 기본 뼈대와 추가 claim은 다른 층이다.

두 번째 자료는 environment 규칙이다. GitHub는 job이 environment를 참조하면 subject claim에 environment 이름이 들어간다고 적고 있다.

GitHub OIDC reference는 environment가 붙은 job의 sub에 environment 이름이 반영된다고 설명한다.

하지만 이 문장만 보고 repo 식별부까지 새 형식으로 바뀐다고 오해하면 안 된다. immutable 저장소라면 repo segment는 여전히 ID 기반이고, environment는 그 뒤에 붙는 추가 문맥에 가깝다.

세 번째 화면은 reusable workflow 문서다. GitHub는 reusable workflow가 들어가면 calling workflow 정보와 함께 job_workflow_ref라는 custom claim도 토큰에 들어간다고 설명한다.

reusable workflow를 쓰면 토큰에 calling workflow 외에 <code>job_workflow_ref</code> custom claim이 추가된다고 GitHub가 안내한다.

여기서 중요한 점은 AWS가 이 custom claim을 그대로 trust condition에 쓸 수 없다는 것이다. reusable workflow를 도입했더라도 AWS에서는 먼저 actual sub와 cloud-side 조건을 다시 좁혀야 한다.

네 번째 자료는 REST API다. 저장소 customization 상태를 볼 때는 use_default, include_claim_keys, use_immutable_subject를 같이 적어 두는 편이 낫다.

GitHub Actions OIDC REST API는 immutable subject opt-in 상태와 customization 필드를 따로 돌려준다.

같은 organization 안에서도 저장소별 opt-in과 template 적용 상태가 다를 수 있으므로, actual token이 왜 다른지 추정할 때 이 세 값을 한 번에 보는 편이 빠르다.

다섯 번째 화면은 AWS 제약을 못 박는 문장이다. GitHub가 reusable workflow와 custom claim을 설명해도 AWS는 custom claims를 직접 trust condition으로 쓰는 구조가 아니다.

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

그래서 AWS에서는 job_workflow_ref를 늘리기보다 actual sub 예시와 trust policy 문자열을 먼저 맞추는 편이 현실적이다.

운영팀이 가장 빨리 필요로 하는 것은 변경 순서표다. immutable 저장소에 environment나 reusable workflow를 더할 때 어떤 층을 먼저 바꾸고 어떤 층은 나중에 바꾸는지 정리해 두어야 한다.

immutable subject 저장소에서 environment와 reusable workflow 추가 시점을 나누는 점검표다.

이미 rename·transfer 뒤 immutable subject 전환 글이 이벤트 기반 전환을 다뤘다면, 이번 표는 이미 전환된 저장소 위에서 새 claim을 얹는 운영판이다.

5. 주의사항과 리스크

첫 번째 리스크는 immutable repo segment를 지우는 방향으로 trust policy를 바꾸려는 것이다. 두 번째는 reusable workflow를 넣었다는 이유로 cloud provider가 job_workflow_ref를 바로 조건으로 읽어 줄 것이라고 기대하는 것이다. 세 번째는 org template와 repo 상태를 한 메모에 섞어 저장해 어떤 변경이 실제 원인이었는지 잃어버리는 것이다.

• immutable subject 저장소에서는 repo segment의 owner_id와 repo_id가 계속 남을 수 있다.
• AWS에서는 custom claims보다 actual sub와 trust policy 정합성이 먼저다.
• environment 추가, reusable workflow 추가, template 변경은 각각 다른 기록 칸에 남기는 편이 안전하다.

6. 결론

immutable subject로 이미 전환된 저장소에 environment나 reusable workflow를 더할 때도, trust policy 복구의 첫 단서는 actual token의 sub다. 기본 repo segment와 추가 claim을 다른 층으로 나누면 롤아웃이 훨씬 짧아진다.

선행 글로는 name 기반 sub와 immutable subject 분기 글, use_default false drift 글, rename·transfer 뒤 전환 글, org template opt-in 뒤 immutable subject 저장소에 reusable workflow claim과 environment 규칙을 붙이는 최신 글을 같이 보면 좋다.

7. 참고 링크

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