[GitHub Actions][OIDC] subject 템플릿과 reusable workflow claim을 바꾸기 전에 OIDC claims를 먼저 검증하는 법

IT 리서치 노트

[GitHub Actions][OIDC] subject 템플릿과 reusable workflow claim을 바꾸기 전에 OIDC claims를 먼저 검증하는 법

GitHub Actions OIDC를 이미 쓰고 있는데 reusable workflow를 도입하거나 environment를 붙인 뒤 trust policy가 흔들리는 경우가 많다. 2026년 7월 1일 기준 GitHub 공식 문서를 다시 보면, 이 문제는 subject 템플릿을 먼저 바꾸는 일이 아니라 현재 JWT claim이 어떻게 생겼는지부터 검증하는 일에 가깝다. 이 글은 `job_workflow_ref`, `sub` customization, OIDC debugger를 기준으로 검증 순서를 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 GitHub Actions OIDC는 subject 템플릿을 바꾸기 전에 현재 JWT claim을 먼저 확인해야 한다. reusable workflow를 쓰면 job_workflow_ref가 관여하고, environment를 붙이면 기본 sub 형식이 달라질 수 있다. 그래서 OIDC debugger로 현재 claim을 먼저 보고, 그다음에 deploy 경계와 trust 조건을 정리한 뒤 subject customization을 적용하는 편이 안전하다.

이미 subject claim과 environment 조건 글이 기본 sub 변화를 다뤘다면, 이번 글은 거기서 한 걸음 더 들어간다. 또 reusable workflow와 AWS trust policy 글을 봤다면 오늘 글은 그 전에 어떤 claim이 실제로 나오는지 검증하는 단계다.

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

현장에서 가장 자주 막히는 지점은 세 가지다. 첫째, branch 기준으로만 trust policy를 잡아 두고 environment를 붙인 뒤 기본 sub 문자열이 달라진 사실을 놓친다. 둘째, reusable workflow를 중앙 배포 엔트리로 바꿨는데 caller repository만 믿고 있어 실제 호출 workflow 파일 경계를 검증하지 못한다. 셋째, provider가 custom claim을 직접 읽는지 확인하지 않은 채 subject 템플릿만 바꾼다.

이때 토큰 발급 문제와 trust 매칭 문제를 분리하지 않으면 같은 곳을 계속 돈다. id-token: write가 없으면 아예 JWT를 못 받지만, JWT는 잘 받아도 provider 쪽 조건과 맞지 않으면 role assumption은 실패할 수 있다. GitHub 문서가 github/actions-oidc-debugger를 별도로 소개하는 이유도 바로 여기 있다.

또 claim 배열을 늘리는 것만으로 배포 경계가 자동으로 안정화되지는 않는다. 어떤 저장소, 어떤 environment, 어떤 reusable workflow ref를 허용할지 문장으로 먼저 정리하지 않으면 include_claim_keys만 복잡해지고 운영 팀은 어느 조건이 실제로 필요한지 설명하지 못하게 된다.

• 증상: environment를 붙인 뒤 role assumption이 갑자기 실패한다.
• 실패: reusable workflow를 쓰는데 caller repository 조건만 유지한다.
• 막힘: OIDC debugger 없이 claim 구조를 추측으로만 바꾼다.
• 누락: REST API subject customization 적용 뒤 trust policy 문자열을 같이 갱신하지 않는다.

증상	먼저 볼 곳	판단 기준
JWT는 나오는데 cloud login 실패	현재 sub와 role condition	branch 형식인지 environment 형식인지 다시 본다
중앙 reusable workflow로 범위가 넓다	job_workflow_ref와 caller repository	called workflow path까지 묶을 필요가 있는지 본다
템플릿을 바꿨는데 여전히 실패	provider custom claim 지원 범위	custom claim 직접 비교인지 sub 보강인지 갈라 본다

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

실무에서는 다섯 단계로 가져가면 된다. 먼저 OIDC debugger로 현재 JWT claim을 출력한다. 두 번째로 branch, environment, reusable workflow 경계를 문장으로 적는다. 세 번째로 provider가 custom claim을 직접 읽는지 확인한다. 네 번째로 필요한 경우에만 subject customization template를 바꾼다. 마지막으로 변경 전후 sub 문자열과 role condition을 같이 대조한다.

1. OIDC debugger로 현재 claim을 먼저 본다.
2. 허용할 저장소, environment, reusable workflow ref를 문장으로 적는다.
3. provider가 custom claim을 직접 읽는지 확인한다.
4. 필요할 때만 REST API subject customization template를 바꾼다.
5. 변경 후 sub와 trust policy를 다시 같은 표로 비교한다.

검증 메모 예시

current_sub=repo:owner/app:environment:prod
current_job_workflow_ref=owner/platform/.github/workflows/deploy.yml@refs/heads/main
provider_supports_custom_claims=false
template_include_claim_keys=repo,context,job_workflow_ref
trust_policy_updated=true

이 메모를 남겨 두면 subject 템플릿 변경이 실제로 어떤 문자열 변화를 만들었는지 바로 비교할 수 있다. 반대로 메모 없이 claim 배열만 바꾸면 실패 원인이 permissions인지, OIDC claim인지, provider 조건인지 다시 처음부터 좁혀야 한다.

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

첫 화면은 reusable workflow와 OIDC를 같이 다루는 GitHub 문서의 핵심 구간이다. 여기서는 reusable workflow 기준 trust 조건을 만들려면 `job_workflow_ref`를 보거나, cloud provider가 그 claim을 못 읽으면 `sub` customization으로 끌어와야 한다는 점을 먼저 확인한다.

GitHub 문서는 reusable workflow trust 조건에서 `job_workflow_ref`와 `sub` customization을 나눠 설명한다.

즉 caller repository만 본다고 끝나지 않는다. 공용 deploy workflow를 여러 저장소가 함께 부르면, 실제로 어떤 workflow 파일을 허용할지까지 검증해야 범위가 흔들리지 않는다. 이 지점이 기존의 reusable workflow와 AWS trust policy 글보다 한 단계 앞선 검증 단계다.

두 번째 자료는 GitHub OIDC reference의 디버깅 구간이다. 문서는 `github/actions-oidc-debugger` 액션으로 실제로 발급될 claim을 시각화해 볼 수 있다고 설명한다.

OIDC reference는 `github/actions-oidc-debugger`로 JWT claim을 먼저 확인하라고 안내한다.

이 문장이 중요한 이유는 subject 템플릿을 바꾸기 전에 현재 토큰에 어떤 claim이 들어오는지부터 확인할 수 있기 때문이다. trust policy가 실패할 때 YAML을 고치기 전에 claim을 보는 편이 훨씬 빠르다.

세 번째 화면은 repository subject customization endpoint 설명이다. `sub` customization은 저장소별 REST API 설정이므로, 요청 본문을 바꾸는 순간 이후 JWT 형식도 달라질 수 있다.

OIDC reference는 repository subject customization endpoint와 request body 흐름을 같이 보여 준다.

그래서 `include_claim_keys`를 늘리기 전에 현재 trust policy가 어떤 문자열을 기대하는지 문장으로 먼저 적어 두는 편이 좋다. 그렇지 않으면 claim은 늘었는데 role condition은 옛 형식을 계속 비교하는 상황이 생긴다.

네 번째 자료는 Example subject claims 구간이다. GitHub는 branch, environment, pull request 같은 실행 맥락에 따라 기본 `sub` 형식이 달라진다는 점을 예시로 보여 준다.

GitHub의 example subject claims 표는 같은 저장소라도 실행 맥락에 따라 `sub`가 달라진다는 점을 보여 준다.

이 예시를 먼저 봐야 environment 도입 뒤 왜 role assumption이 갑자기 깨졌는지 설명이 된다. branch 기준 문자열을 믿고 있었다면 environment 추가만으로 매칭이 달라질 수 있다.

다섯 번째 자료는 OIDC debugger를 별도 job으로 붙이는 예시다. 검증 단계에서는 cloud provider에 바로 로그인하지 말고, 먼저 JWT claim만 출력해 현재 `sub`와 `job_workflow_ref`가 어떻게 보이는지 확인하는 편이 안전하다.

OIDC debugger workflow 예시는 claim을 먼저 출력해 subject 템플릿 변경 전후를 비교하게 만든다.

이렇게 해 두면 `id-token: write`가 빠진 문제와 trust 문자열이 맞지 않는 문제를 분리해 볼 수 있다. 이미 id-token: write 실패 글을 봤다면, 이번 글은 그 다음인 claim 검증 순서다.

마지막 자료는 실제 검증 순서다. subject 템플릿을 곧바로 바꾸기보다 현재 claim 확인, deploy 경계 정의, provider 지원 범위, REST API 변경, trust policy 반영을 순서대로 두면 수정 범위가 작아진다.

subject 템플릿 변경 전 검증 순서는 claim 확인과 trust 조건 설계를 같은 표에서 보게 한다.

이 순서를 따르면 기존 글인 subject claim과 environment 조건 글과 custom subject claim 템플릿 글을 더 좁은 문제에 다시 연결할 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 OIDC debugger 없이 claim 구조를 추측으로 바꾸는 것이다. 두 번째 리스크는 environment 도입 뒤 branch 기준 trust 문자열을 그대로 두는 것이다. 세 번째 리스크는 provider가 custom claim을 못 읽는데 GitHub 템플릿만 바꾸고 끝내는 것이다.

운영 전에 확인할 때는 최소한 branch 실행, environment 실행, reusable workflow 호출 세 경우의 claim을 각각 저장해 두는 편이 좋다. 그래야 어떤 변경이 어느 claim을 바꿨는지와, cloud provider가 실제로 무엇을 비교하는지 분리할 수 있다.

• JWT 발급 성공과 trust 매칭 성공을 같은 문제로 보지 않는다.
• job_workflow_ref는 reusable workflow 경계 검증에 유용하다.
• subject customization은 claim 확인 뒤에 적용한다.

6. 결론

GitHub Actions OIDC에서 subject 템플릿과 reusable workflow claim 문제는 템플릿을 먼저 바꾸기보다 현재 JWT claim을 먼저 보는 쪽이 빠르다. OIDC debugger로 sub와 job_workflow_ref를 확인하고, deploy 경계와 provider 지원 범위를 정리한 뒤 subject customization을 적용하면 trust policy가 덜 흔들린다.

• claim을 먼저 본다.
• deploy 경계를 먼저 적는다.
• 그다음 subject customization을 바꾼다.

7. 참고 링크

1. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows
2. https://docs.github.com/en/actions/reference/security/oidc
3. https://docs.github.com/en/rest/actions/oidc#set-the-customization-template-for-an-oidc-subject-claim-for-a-repository