[GitHub Actions][OIDC] enterprise custom issuer를 켤 때 issuer URL 분기와 subject template·repo override를 어떤 순서로 나누나

IT 리서치 노트

[GitHub Actions][OIDC] enterprise custom issuer를 켤 때 issuer URL 분기와 subject template·repo override를 어떤 순서로 나누나

GitHub Actions OIDC를 운영할 때 대부분의 팀은 subject template와 immutable subject 쪽만 본다. 그런데 2026년 8월 5일 기준 GitHub REST API 문서를 다시 보면, enterprise custom issuer policy가 따로 생겨 issuer URL anchor 자체를 바꿀 수 있다. 이 글은 issuer URL 분기와 subject template·repo override를 어떤 순서로 분리해야 rollout과 rollback이 덜 꼬이는지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 custom issuer는 subject template보다 한 단계 위의 변경이다. issuer는 cloud provider가 신뢰하는 발급자 anchor를 바꾸고, subject template는 그 다음 조건식을 바꾼다. 둘을 한 번에 건드리면 원인 분리가 거의 안 된다.

가장 안전한 순서는 issuer 샘플 확보, org template 확인, repo override 확인, 마지막 cloud trust 조건 변경이다. 실제 토큰 샘플을 남기지 않으면 rollout 속도가 빨라도 복구가 길어진다.

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

현장에서 오래 막히는 이유는 모든 증상이 'OIDC 안 됨'으로 보이기 때문이다. issuer allowlist가 틀려도 403처럼 보이고, repo override가 옛 sub를 쓰고 있어도 비슷한 장애처럼 보인다. custom property claims까지 함께 바꾸면 무엇이 access-control을 깨뜨렸는지 더 복잡해진다.

REST 문서는 enterprise custom issuer policy와 org 또는 repo subject template를 서로 다른 엔드포인트로 제공한다. 이 구조 자체가 rollout 단계를 나눠야 한다는 힌트다. issuer URL anchor를 바꾼 날과 template를 바꾼 날을 같은 change set으로 뭉치면 책임 경계가 없어진다.

여기에 실제 운영에서는 토큰 샘플을 남기지 않는 습관이 더해진다. iss 값을 저장하지 않으면 GitHub 쪽에서 issuer를 바꾼 뒤 cloud trust가 안 따라온 상황을 놓치고, sub 샘플을 저장하지 않으면 repo override opt-out 때문에 특정 저장소만 실패하는 상황을 놓친다. 두 증상은 겉으로는 같은 배포 실패처럼 보여도 조치 순서가 완전히 다르다.

• 증상: 특정 환경에서만 갑자기 OIDC 신뢰가 깨진다.
• 실패: issuer 변경과 sub 변경을 같은 배포 메모로 적는다.
• 막힘: actual issuer sample을 저장하지 않는다.
• 누락: repo opt-out 여부를 cloud-side 조건과 함께 비교하지 않는다.

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

적용 순서는 다섯 단계가 실용적이다. 먼저 enterprise issuer policy 값을 확인하고 issuer 샘플을 저장한다. 두 번째로 org subject template를 읽는다. 세 번째로 repo override가 use_default인지 확인한다. 네 번째로 actual token에서 iss와 sub를 함께 저장한다. 마지막으로 cloud trust policy는 이 증거를 본 뒤에만 바꾼다.

1. issuer policy와 actual issuer를 먼저 기록한다.
2. org subject template 상태를 분리 조회한다.
3. repo override의 use_default와 immutable subject 상태를 기록한다.
4. actual token의 iss와 sub를 함께 저장한다.
5. cloud trust 수정은 마지막 단계로 분리한다.

checklist:
1. issuer policy 조회
2. issuer sample 저장
3. org template 조회
4. repo override 조회
5. iss/sub 샘플 동시 저장
6. cloud trust 변경 분리

이 구조를 잡으면 rollback도 짧다. issuer를 원복할지, repo override만 default로 돌릴지, sub 조건만 완화할지 결정 기준이 바로 생기기 때문이다.

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

첫 자료는 enterprise custom issuer 정책 REST 엔드포인트다. 이제 issuer URL 자체를 enterprise 단위에서 분기할 수 있기 때문에, sub 템플릿 조정과는 다른 rollout 단계를 가져가야 한다.

GitHub는 enterprise 단위 custom issuer policy 설정 엔드포인트를 제공한다.

즉 issuer 변경은 subject claim 변경의 하위 옵션이 아니다. cloud provider의 trust anchor를 건드리는 상위 레이어이기 때문에 배포 순서를 따로 잡아야 한다.

두 번째 공식 화면은 include_enterprise_slug 파라미터 설명이다. 이 값 하나가 issuer URL 형태를 바꾸므로, sub 구성이나 custom property inclusion과 같은 표에 적으면 헷갈리기 쉽다.

include_enterprise_slug는 issuer URL 형태를 바꾸는 enterprise 정책 필드다.

운영자는 이 값을 토글한 시점과 실제 issuer 샘플을 별도 메모로 남겨야 한다. 그래야 cloud-side issuer allowlist 문제를 repo override 문제와 섞지 않는다.

세 번째 자료는 repository template와 repo override 분기 카드다. custom issuer를 켜더라도 repo별 opt-in과 opt-out은 여전히 별도 레이어라는 점을 짧게 묶었다.

repo override는 issuer 정책과 다른 저장소 단위 분기다.

즉 issuer를 바꾸는 일과 sub를 바꾸는 일은 같은 OIDC 변경처럼 보여도 관리 레이어가 다르다. rollout 메모도 그 구조를 따라야 한다.

네 번째 자료는 레이어 분리표다. enterprise issuer, org subject template, repo override를 한 장에서 보되, rollback 지점은 따로 두는 방식이다.

custom issuer rollout에서는 issuer, subject template, repo override를 분리해야 한다.

이미 immutable subject 글과 custom property inclusion 글을 봤다면, 이번 표는 그보다 한 단계 위인 issuer anchor 분기다.

마지막 자료는 최소 rollout 메모 예시다. issuer와 subject를 서로 다른 필드로 남기면 cloud trust 오류가 훨씬 빨리 갈린다.

enterprise custom issuer rollout에서 남겨야 할 최소 메모 예시다.

이 메모는 access-control 경로를 짧게 만든다. issuer mismatch, sub mismatch, repo opt-out 중 어디가 원인인지 바로 볼 수 있기 때문이다.

5. 주의사항과 리스크

첫 번째 리스크는 include_enterprise_slug를 켜고도 issuer allowlist를 안 바꾸는 것이다. 두 번째는 issuer가 바뀌었는데도 org template나 repo override를 먼저 의심하는 것이다. 세 번째는 custom property claims 확장을 access-control 변경과 같은 단계로 넣는 것이다.

운영 전에 확인할 때는 issuer sample, sub sample, repo override 상태, cloud trust 변경 여부를 각각 독립 필드로 남겨 두는 편이 좋다. 그래야 같은 OIDC 장애처럼 보여도 원인을 쉽게 가른다.

업데이트 메모 · 2026-08-07

custom issuer 분기 자체는 이미 정리했지만, 실제 운영에서는 Vault의 bound_issuer와 oidc_discovery_url를 어떤 순서로 바꿀지에서 더 자주 막힌다. 그 후속 정리는 [GitHub Actions][OIDC] enterprise custom issuer를 켠 뒤 Vault bound_issuer와 oidc_discovery_url를 어느 순서로 바꾸나에 따로 정리했다.

6. 결론

enterprise custom issuer rollout은 subject template rollout과 다른 종류의 변경이다. issuer를 먼저 고정하고 그다음 sub와 repo override를 보면, GitHub 쪽 설정과 cloud provider 쪽 trust 조건을 훨씬 짧게 분리할 수 있다.

• issuer URL과 subject template를 같은 변경으로 취급하지 않는다.
• actual issuer sample과 sub sample을 같이 저장한다.
• cloud trust 수정은 마지막 단계로 남긴다.

7. 참고 링크

1. https://docs.github.com/en/enterprise-cloud@latest/rest/actions/oidc
2. https://docs.github.com/en/enterprise-cloud@latest/actions/reference/security/oidc
3. https://docs.github.com/en/actions/concepts/security/openid-connect

반응형