[GitHub Actions][OIDC] custom property inclusion을 토큰에 넣을 때 subject template와 org override·repo override를 어떤 순서로 나누나

IT 리서치 노트

[GitHub Actions][OIDC] custom property inclusion을 토큰에 넣을 때 subject template와 org override·repo override를 어떤 순서로 나누나

GitHub Actions OIDC를 운영하다 보면 subject claim template와 immutable subject만 신경 쓰기 쉽다. 그런데 2026년 8월 5일 기준 GitHub REST API 문서를 다시 보면, repository custom properties를 OIDC token에 포함시키는 별도 inclusion API가 organization과 enterprise 계층에 생겨 있다. 이 글은 custom property inclusion을 token에 넣을 때 subject template, org override, repo override를 어떤 순서로 나눠 봐야 rollout이 덜 꼬이는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 custom property inclusion은 subject template와 다른 변경이다. inclusion은 token payload를 넓히는 단계이고, subject template는 sub 문자열을 바꾸는 단계다. 따라서 두 계층을 한 번에 바꾸면 access control 문제와 observability 문제를 같은 증상으로 오해하기 쉽다.

가장 안전한 순서는 payload 확장부터다. 먼저 어떤 property가 token에 실리는지 org 또는 enterprise 계층에서 확인하고, 그다음 subject template와 immutable subject, repo override를 따로 비교해야 실제 trust 정책과 감사 로그를 분리할 수 있다.

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

현장에서 오래 끄는 이유는 모두 OIDC 설정처럼 보이기 때문이다. property inclusion을 추가했는데도 cloud 쪽 조건은 그대로인데, 팀은 sub까지 바뀌었다고 오해한다. 반대로 subject template를 바꿨는데 token payload 확장까지 된 것으로 착각하기도 한다.

GitHub REST API 문서는 custom property inclusion 조회·생성 API를 별도로 제공하고, subject claim customization template 조회·수정 API도 따로 제공한다. 또 use_default, include_claim_keys, use_immutable_subject는 sub 구성 레이어에만 직접 닿는다. 이 구조를 모르면 repo override와 org 선언, token payload와 trust policy를 한 번에 바꾸는 실수를 하기 쉽다.

여기에 reusable workflow 환경까지 얹히면 혼선이 더 커진다. OIDC with reusable workflows 문서는 job_workflow_ref 같은 custom claim을 설명하지만, 이것 역시 property inclusion과 subject template와는 별도 층이다. 즉 token에 무엇이 실리는가와 cloud provider가 실제로 무엇을 비교하는가는 다시 나눠 봐야 한다.

• 증상: 토큰에 새 속성을 넣었는데 trust policy 문제처럼 보인다.
• 실패: property inclusion과 subject template를 같은 변경으로 기록한다.
• 막힘: org 선언, repo override, actual token 샘플을 따로 저장하지 않는다.
• 누락: cloud_trust_changed 여부를 별도 필드로 남기지 않는다.

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

가장 짧은 적용 순서는 다섯 단계다. 먼저 organization 또는 enterprise에서 어떤 custom property가 token에 포함되는지 조회한다. 두 번째로 subject template 상태를 분리 조회한다. 세 번째로 repository override가 use_default인지, use_immutable_subject를 켰는지 본다. 네 번째로 actual token sample을 저장한다. 마지막으로 cloud trust policy는 정말 바꾼 경우에만 별도 변경으로 기록한다.

1. property inclusion 목록을 먼저 조회한다.
2. subject template와 repo override를 따로 조회한다.
3. use_default와 use_immutable_subject 상태를 기록한다.
4. actual token의 sub와 custom properties 존재 여부를 샘플로 남긴다.
5. cloud trust 변경은 별도 rollout으로 분리한다.

이 순서가 중요한 이유는 rollback이 쉽기 때문이다. token에 속성만 더 실으려던 변경이 trust policy 실패로 번졌다면, 실제 원인이 template 변경인지 cloud-side policy 변경인지 바로 분리할 수 있다. 반대로 inclusion만 바꿨다면 access-control failure가 아니라 downstream parser나 감사 로그 누락일 가능성이 높다.

checklist:
1. property inclusion list 조회
2. subject template 조회
3. repo override 조회
4. actual token sample 저장
5. cloud trust 변경 여부 분리 기록

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

첫 자료는 organization 단위 custom property inclusion 목록 API다. GitHub는 이제 repository custom properties를 OIDC token에 포함시키는 별도 계층을 제공한다.

organization 단위로 어떤 repository custom property가 OIDC token에 포함되는지 조회할 수 있다.

이 기능은 subject template와 목적이 다르다. sub 문자열을 바꾸는 것이 아니라, 토큰에 추가 속성을 싣는 계층이기 때문에 rollout 기록도 따로 가져가야 한다.

두 번째 공식 화면은 GitHub Actions OIDC 개요 문서의 token claims 설명이다. GitHub는 token claim을 조직 수준에서 커스터마이즈할 수 있고, sub와 다른 claims를 구분해 읽어야 한다는 전제를 제공한다.

GitHub OIDC 문서는 token claims와 subject customization을 같은 문단에서 구분해 설명한다.

즉 팀, environment, cost-center 같은 속성을 토큰에 태우고 싶다면 먼저 payload에 어떤 claim이 들어가는지 읽고, 그다음 sub 문자열 변경과 분리해서 rollout 메모를 적어야 한다.

세 번째 공식 화면은 reusable workflow와 OIDC token 관계를 다루는 문서다. 여기서는 job_workflow_ref 같은 추가 claim이 subject template나 property inclusion과 또 다른 층이라는 점을 확인할 수 있다.

reusable workflow claim은 subject template나 property inclusion과 다른 레이어로 읽어야 한다.

subject template는 sub 문자열을 어떻게 만들지 다루고, property inclusion은 토큰에 어떤 추가 속성을 담을지 다룬다. reusable workflow claim까지 같은 변경으로 묶으면 rollback 지점이 사라진다.

네 번째 자료는 rollout 순서 카드다. property inclusion, subject template, immutable subject, reusable workflow claim을 어떤 순서로 분리 기록할지 한 장으로 묶었다.

GitHub OIDC 변경은 payload 확장과 sub 변경을 서로 다른 단계로 굴리는 편이 안전하다.

그래서 property inclusion rollout과 sub template rollout을 같은 커밋 메모 한 줄로 끝내면 안 된다. 어떤 레이어가 실제 trust policy를 바꾸는지, 어떤 레이어가 감사용 속성만 늘리는지 따로 적어야 한다.

다섯 번째 자료는 레이어 분리표다. custom property inclusion, subject template, immutable subject, reusable workflow claim은 서로 비슷해 보이지만 역할이 다르다.

GitHub OIDC에서 property inclusion과 subject template를 섞지 않기 위한 레이어 표다.

이미 org template opt-in 뒤 repo_id와 environment 보호 규칙 글과 prod role 분리 rollout 글이 trust policy 쪽을 다뤘다면, 이번 표는 token payload 자체를 넓힐 때의 구조 정리다.

마지막 자료는 운영 메모 예시다. property inclusion과 subject template 변경을 한 레코드에 섞되, 필드는 서로 분리하는 편이 안전하다.

GitHub OIDC custom property inclusion rollout에서 남겨야 할 최소 메모 예시다.

이 정도만 기록해도 변경 실패가 org 설정인지 repo override인지, 아니면 cloud-side trust mismatch인지 빨리 가른다. token payload 확장과 access-control 변경은 분리 기록이 핵심이다.

5. 주의사항과 리스크

첫 번째 리스크는 property inclusion을 늘리면서 subject template까지 한 번에 바꾸는 것이다. 두 번째는 use_default=true 상태에서 include_claim_keys가 실제로 무시될 수 있다는 점을 놓치는 것이다. 세 번째는 job_workflow_ref 같은 custom claim을 cloud provider가 그대로 읽을 거라고 기대하는 것이다.

운영 전에 확인할 때는 최소한 inclusion scope, template 상태, repo override, actual sub sample, cloud trust change 여부를 각각 독립 필드로 남기는 편이 좋다. 그래야 실패 원인이 한 줄에서 섞이지 않는다.

6. 결론

GitHub OIDC custom property inclusion은 subject template의 확장이 아니라 token payload의 별도 레이어다. 먼저 어떤 속성이 token에 실리는지 확인하고, 그다음 sub 구성과 repo override를 따로 보면 rollout과 rollback이 모두 짧아진다.

여기서 issuer anchor까지 손대는 enterprise 운영이라면 custom issuer rollout 분리 글을 함께 보는 편이 맞다. 이 글이 token payload와 repo override를 분리하는 기준이라면, 새 글은 그보다 위 레이어인 issuer URL과 cloud trust anchor를 언제 따로 바꿔야 하는지까지 이어 준다.

• property inclusion과 subject template를 같은 변경으로 취급하지 않는다.
• org 선언, repo override, actual token sample을 따로 저장한다.
• cloud trust 변경은 마지막 단계로 분리한다.

7. 참고 링크

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