[GitHub Actions][OIDC] custom subject claim 템플릿을 적용하기 전에 repo와 environment 조건을 먼저 정리하는 법

IT 리서치 노트

[GitHub Actions][OIDC] custom subject claim 템플릿을 적용하기 전에 repo와 environment 조건을 먼저 정리하는 법

GitHub Actions OIDC를 이미 붙였는데도 deploy role 경계가 애매하거나, reusable workflow를 도입한 뒤 trust policy를 어디까지 고쳐야 할지 막히는 경우가 있다. 2026년 6월 26일 기준 GitHub 공식 문서를 다시 보면 custom subject claim 템플릿은 claim을 더 많이 넣는 기능이 아니라, provider가 실제로 비교할 문자열을 먼저 설계하는 기능에 가깝다. 이 글은 repo, environment, reusable workflow 경계를 정리한 뒤 custom subject claim 템플릿을 넣는 순서를 다룬다.

목차

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

1. 개요

결론부터 말하면 custom subject claim 템플릿은 OIDC를 더 안전하게 만드는 마법 버튼이 아니다. 먼저 deploy 경계가 branch인지 environment인지, 그리고 reusable workflow 파일까지 고정해야 하는지 정해야 한다. 그다음에야 include_claim_keys로 어떤 값을 sub에 끌어넣을지 결정할 수 있다.

이미 subject claim과 environment 조건 글을 읽었다면 이번 글은 그 다음 단계다. provider가 custom claim을 직접 읽을 수 있는지, 못 읽는다면 GitHub의 subject customization으로 어디까지 보강할지를 다룬다.

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

실무에서 막히는 지점은 대개 네 가지다. 첫째, branch 기준으로 trust policy를 만들었는데 나중에 job에 environment를 붙이며 기본 sub 문자열이 바뀐 사실을 놓친다. 둘째, reusable workflow를 공용 deploy entry로 쓰면서 caller repository만 trust 조건에 넣어 범위가 생각보다 넓어진다. 셋째, provider가 custom claim을 직접 지원하지 않는데도 job_workflow_ref를 바로 비교하려고 든다. 넷째, REST API로 템플릿을 바꾼 뒤에도 기존 trust 문자열과 권한 구성을 같이 갱신하지 않는다.

특히 GitHub OIDC는 토큰 발급 성공과 provider 매칭 성공이 다른 문제다. id-token: write가 있어서 토큰은 받아왔는데 role assumption이 실패한다면 YAML보다 trust 문자열, provider 지원 범위, 현재 sub 형식을 먼저 봐야 한다. 이 점은 id-token: write 실패 글과 구별해서 읽어야 한다.

• 증상: OIDC 토큰은 발급되는데 deploy role이 환경 변경 뒤 갑자기 실패한다.
• 실패: reusable workflow를 쓰는데 caller repository만 trust 정책에 남긴다.
• 막힘: provider가 custom claim을 직접 읽는지 확인하지 않고 템플릿부터 바꾼다.
• 누락: immutable subject opt-in 뒤 기존 name 기반 trust 문자열을 그대로 둔다.

증상	먼저 볼 곳	판단 기준
environment를 붙인 뒤 role assumption 실패	현재 sub 문자열과 trust policy	branch 형식이 environment 형식으로 바뀌었는지 본다
공용 deploy workflow로 범위가 넓다	job_workflow_ref 또는 subject customization	called workflow path까지 묶어야 하는지 판단한다
템플릿을 넣어도 provider 매칭이 안 된다	provider custom claim 지원 범위	AWS처럼 미지원이면 sub 보강 전략으로 바꾼다

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

점검 순서는 다섯 단계가 가장 안전하다. 먼저 deploy 경계를 문장으로 적는다. 둘째, 현재 job이 branch 기준인지 environment 기준인지 확인해 기본 sub 형식을 다시 본다. 셋째, reusable workflow 파일까지 고정할 필요가 있으면 provider가 custom claim을 읽는지 점검한다. 넷째, 그래도 GitHub 쪽 sub 보강이 필요하면 REST API subject customization template를 설계한다. 마지막으로 permissions와 trust policy를 같이 비교해 토큰 발급 문제와 매칭 문제를 분리한다.

1. 허용할 deploy 경계를 branch, environment, reusable workflow 기준으로 적는다.
2. 현재 sub 형식이 어떤 문자열인지 문서 예시와 대조한다.
3. provider가 custom claim을 읽는지 확인한다.
4. 필요하면 GitHub subject customization template를 설계한다.
5. permissions와 trust policy를 한 번 더 분리해서 확인한다.

점검 메모 예시

deploy_boundary:
  repository: octo-org/app
  environment: Production
  reusable_workflow: octo-org/platform/.github/workflows/deploy.yml@refs/heads/main
provider_support:
  custom_claims: false
github_template:
  include_claim_keys:
    - repo
    - context
    - job_workflow_ref

이 메모를 먼저 만들면 GitHub API 요청과 cloud trust policy 수정 범위를 함께 좁힐 수 있다. 반대로 메모 없이 템플릿부터 넣으면 나중에 어떤 claim이 실제로 필요한지 다시 되짚기 어렵다.

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

첫 화면은 GitHub OIDC reference에서 `job_workflow_ref`와 subject customization을 같이 설명하는 구간이다. 여기서 봐야 할 핵심은 reusable workflow를 쓸 때 caller repository만으로는 배포 경계를 충분히 고정하지 못할 수 있다는 점이다.

OIDC reference 문서는 `job_workflow_ref`를 custom claim으로 설명하고 subject customization과 연결한다.

즉 deploy role을 특정 workflow 파일까지 제한하고 싶다면 branch나 environment만 보는 것으로는 부족할 수 있다. 이 점이 기존의 subject claim과 environment 조건 글 다음 단계다.

두 번째 자료는 GitHub Actions OIDC REST API 문서다. custom subject claim 템플릿은 UI에서 몇 번 클릭하는 설정이 아니라, repository 또는 organization 단위 REST API로 관리되는 구성이므로 요청 body와 권한 범위를 먼저 읽어야 한다.

OIDC REST API 문서는 `include_claim_keys`와 `use_immutable_subject`를 어떤 권한으로 바꾸는지 보여 준다.

특히 immutable subject를 opt-in하면 기존 name 기반 `sub` 문자열이 repository ID 기반으로 바뀔 수 있다. 그래서 템플릿을 넣기 전에 현재 trust policy가 어떤 문자열을 기대하는지 먼저 메모해야 한다.

세 번째 화면은 reusable workflow와 OIDC를 같이 다루는 문서다. 이 구간은 custom template를 넣어야 하는 상황과, provider가 custom claim을 직접 읽을 수 있을 때 `job_workflow_ref`를 trust 조건으로 분리하는 상황을 나눠 읽게 해 준다.

reusable workflow 문서는 trust condition을 branch, caller, called workflow 관점으로 다시 나눠 보게 한다.

이 자료를 보면 템플릿을 곧바로 넣기보다 먼저 어떤 deploy 경계를 고정하려는지 문장으로 적는 편이 낫다. 배포 범위를 정의하지 않고 claim부터 늘리면 조건만 길어지고 운영은 더 헷갈린다.

네 번째 자료는 AWS OIDC 가이드의 제한 사항이다. 모든 cloud provider가 custom claim을 같은 방식으로 읽는다고 가정하면 템플릿 구성은 맞는데 정작 provider 쪽 매칭이 안 되는 문제가 생긴다.

AWS 가이드는 custom claim을 직접 지원하지 않는다고 분명히 적고 있어 provider 차이를 먼저 확인하게 만든다.

그래서 AWS처럼 custom claim 직접 매칭이 안 되는 환경에서는 GitHub 쪽 `sub` customization으로 필요한 값을 끌어들일지, 아니면 branch와 environment 조합만으로 경계를 충분히 줄일지 먼저 정해야 한다.

REST API 요청 본문은 길게 쌓지 말고 현재 필요한 claim만 남기는 편이 안전하다. repo, context, job_workflow_ref를 한 번에 넣을 수 있어도 실제로 provider가 비교하는 필드와 GitHub에서 변하지 않는 필드를 분리해서 보는 편이 좋다.

repository subject customization 요청 예시는 `include_claim_keys`와 `use_default`를 어떻게 보낼지 정리한다.

이 요청은 실행 전 메모와 짝을 이뤄야 한다. 어떤 branch, 어떤 environment, 어떤 reusable workflow를 허용할지 먼저 적어 두지 않으면 claim 배열만 바뀌고 trust policy는 그대로 남는 경우가 많다.

마지막 자료는 템플릿 적용 전에 보는 점검표다. deploy role이 실패한다고 바로 claim 배열을 바꾸기보다, provider 지원 범위와 현재 sub 문자열, environment 사용 여부, reusable workflow 경로를 먼저 대조해야 수정 범위가 작아진다.

custom subject claim 템플릿 적용 전 점검표는 provider 지원 범위와 현재 경계를 함께 확인하게 만든다.

이 순서를 따르면 기존 글인 workflow별 OIDC 권한 분리 글과 id-token: write 실패 글을 더 작은 범위에서 재사용할 수 있다.

5. 주의사항과 리스크

첫 번째 리스크는 provider 지원 범위를 확인하지 않고 custom claim 설계를 시작하는 것이다. 두 번째 리스크는 environment나 reusable workflow를 도입한 뒤 기본 sub 형식이 바뀐 사실을 놓치는 것이다. 세 번째 리스크는 REST API에서 템플릿을 바꾸고도 cloud trust policy나 immutable subject 영향 범위를 같이 갱신하지 않는 것이다.

운영 전에는 최소한 branch 기준, environment 기준, reusable workflow 기준 세 경우를 각각 표로 적어 두는 편이 좋다. 그래야 실패 시점이 YAML 문제인지 trust 문자열 문제인지 빠르게 갈라진다.

• custom subject claim 템플릿은 deploy 경계 정의 뒤에 온다.
• provider 미지원 환경에서는 sub 보강 전략을 먼저 정한다.
• immutable subject opt-in은 기존 trust 문자열과 함께 검토한다.

6. 결론

GitHub Actions OIDC custom subject claim 템플릿은 claim을 더 많이 넣는 설정이 아니라 deploy 경계를 문자열로 다시 고정하는 단계다. repo, environment, reusable workflow 기준을 먼저 정하고 provider가 읽을 수 있는 범위를 확인한 뒤 템플릿을 적용해야 배포 실패와 과한 권한 확장을 같이 줄일 수 있다.

• branch와 environment 기준을 먼저 나눈다.
• reusable workflow를 고정할지 여부를 별도로 본다.
• provider 지원 범위와 GitHub template를 같이 설계한다.

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/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows
4. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws