[GitHub Actions][OIDC] environment를 여러 개로 나눌 때 immutable subject 저장소의 trust policy 조건을 wildcard 없이 어떻게 유지하나

IT 리서치 노트

[GitHub Actions][OIDC] environment를 여러 개로 나눌 때 immutable subject 저장소의 trust policy 조건을 wildcard 없이 어떻게 유지하나

GitHub Actions OIDC를 AWS에 붙인 immutable subject 저장소에서 dev, staging, production 같은 environment를 늘리기 시작하면 많은 팀이 trust policy를 와일드카드로 넓혀 버리고 싶어진다. 하지만 2026년 7월 31일 기준 GitHub 공식 문서를 다시 보면 immutable subject 저장소는 repo 식별부가 ID 기반으로 안정적이고, environment는 subject 뒤에 붙는 분기이며, AWS는 custom claims를 직접 읽지 못한다. 이 글은 environment를 여러 개로 나눌 때 trust policy 조건을 wildcard 없이 유지하는 편이 왜 더 안전한지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 immutable subject 저장소에서 여러 environment를 운영할 때는 repo 식별부를 고정하고 environment별 exact subject를 나열하는 편이 wildcard보다 안전하다. GitHub environment 보호 규칙은 승인과 branch 제어를 맡기고, AWS trust policy는 exact subject 문자열을 맡기면 역할이 선명해진다.

즉 environment 수가 늘어난다고 trust policy를 *로 넓힐 필요는 없다. immutable subject 저장소라면 repo segment가 안정적이기 때문에 environment 이름만 명시적으로 열거해도 충분한 경우가 많다.

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

이 주제가 꼬이는 이유는 environment 수가 늘수록 문자열 관리가 번거로워 보이기 때문이다. dev, staging, production을 한 역할로 묶어 쓰는 팀은 trust policy에서 ref나 environment 부분을 대충 wildcard로 처리하고 싶어진다. 하지만 그러면 어느 환경이 어떤 승인 규칙 아래서 배포됐는지 읽기 어려워진다.

GitHub OIDC reference는 immutable subject 저장소의 기본 repo 식별부가 owner ID와 repo ID를 포함할 수 있다고 설명하고, job이 environment를 참조하면 subject에 environment 이름이 들어간다고 설명한다. AWS 가이드는 custom claims 직접 지원이 없다고 못 박는다. 이 셋을 같이 읽으면 exact subject 설계가 생각보다 단순하다는 점이 보인다. repo 식별 축은 고정하고 environment 이름만 분기하면 되기 때문이다.

많은 팀이 여기서 두 가지를 섞는다. 첫째, trust policy와 GitHub environment 승인 규칙을 같은 문제처럼 본다. 둘째, reusable workflow나 다른 custom claim이 있으니 wildcard 없이 exact subject를 유지하기 어렵다고 생각한다. 하지만 AWS는 custom claim을 직접 읽지 못하므로 결국 actual sub를 명시적으로 적는 쪽이 더 예측 가능하다.

• 증상: environment가 늘자 trust policy를 wildcard로 넓히고 싶어진다.
• 실패: 승인 규칙과 cloud trust 조건을 같은 표 없이 한 번에 바꾼다.
• 막힘: custom claim으로 wildcard 문제를 해결할 수 있다고 기대한다.
• 누락: actual sub 예시를 환경별로 저장하지 않는다.

질문	먼저 볼 곳	판단 기준
repo 식별부가 안정적인가	immutable subject 여부	owner_id/repo_id 기반인지 본다
환경별 분기가 어디서 생기나	environment 포함 sub	exact subject를 환경별로 나눌 수 있는지 본다
승인은 어디서 제어하나	required reviewers, deployment branches	GitHub environment 규칙으로 분리한다

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

실무 순서는 다섯 단계면 충분하다. 먼저 저장소가 immutable subject 형식인지 actual token과 문서 기준으로 확인한다. 다음으로 각 environment의 actual sub 예시를 dev, staging, production 순서로 저장한다. 세 번째로 AWS trust policy에는 그 exact sub 문자열만 넣는다. 네 번째로 GitHub environments에서 required reviewers와 deployment branches를 환경별로 나눈다. 마지막으로 wildcard가 남아 있다면 exact subject 성공을 확인한 뒤 천천히 제거한다.

1. immutable subject 여부와 actual sub 형식을 먼저 확인한다.
2. 환경별 actual sub 예시를 로그에 남긴다.
3. AWS trust policy에는 exact subject만 넣는다.
4. GitHub environment 보호 규칙은 승인과 branch 제어로 분리한다.
5. wildcard는 exact subject 성공 뒤에만 제거한다.

이 순서를 지키면 wildcard를 제거해도 운영이 과하게 복잡해지지 않는다. repo 식별부는 한 번만 적고, 환경 이름만 명시적으로 나누면 되기 때문이다. 또한 승인 규칙을 GitHub environment에 맡기면 cloud trust policy는 짧은 exact subject 목록으로 유지할 수 있다.

운영 메모 예시

repo_subject=repo:octo-org@12345678/octo-repo@987654321
dev_sub=repo:octo-org@12345678/octo-repo@987654321:environment:dev
staging_sub=repo:octo-org@12345678/octo-repo@987654321:environment:staging
prod_sub=repo:octo-org@12345678/octo-repo@987654321:environment:production
reviewers=staging-team,prod-owners
branches=release/*,main

이 정도만 기록해 두면 환경이 추가되더라도 exact subject 하나를 더하는 방식으로 확장할 수 있다. 반대로 wildcard를 남겨 두면 어떤 환경이 실제로 허용됐는지 audit 설명이 길어진다.

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

첫 공식 화면은 GitHub OIDC reference의 최신 immutable subject 구간이다. 여러 environment를 추가하더라도 먼저 고정해야 할 것은 저장소 식별부가 이름 기반인지 ID 기반인지다. 화면의 표와 박스 강조를 같이 보면 어떤 필드가 고정 축인지 바로 읽힌다.

GitHub는 2026년 7월 15일 이후 저장소 또는 immutable subject opt-in 저장소의 기본 sub 형식이 owner ID와 repo ID를 포함한다고 설명한다.

이 형식을 먼저 메모해 두면 environment 개수가 늘어나도 repo 식별 축이 안정적이라는 전제를 놓치지 않게 된다. wildcard를 줄이는 작업도 이 고정된 repo segment 위에서 시작해야 한다.

두 번째 자료는 environment 포함 규칙이다. GitHub는 job이 environment를 참조하면 subject claim에 environment 이름이 들어간다고 설명한다.

GitHub OIDC reference는 environment를 참조한 job의 sub에 environment 이름이 반영된다고 안내한다.

즉 dev, staging, production을 같은 저장소에서 쓰더라도 sub를 완전히 wildcard로 열 필요는 없다. 실제로는 repo 식별부는 고정하고 environment 이름만 명시적으로 나누는 쪽이 더 읽기 쉽다.

세 번째 화면은 AWS 제약을 못 박는 구간이다. GitHub 쪽 claim이 많아도 AWS는 custom claim을 직접 조건으로 쓰지 못한다.

GitHub의 AWS OIDC 가이드는 AWS에서 OIDC custom claims를 직접 지원하지 않는다고 설명한다.

그래서 여러 environment를 운영할 때도 핵심은 actual sub를 정확히 적는 것이다. reusable workflow나 다른 custom claim으로 우회하기보다 신뢰 문자열 자체를 명시적으로 분기하는 편이 안전하다.

네 번째 자료는 GitHub environment 보호 규칙이다. trust policy만 줄인다고 끝이 아니라, environment 자체의 승인 규칙과 배포 브랜치 제한도 같이 써야 wildcard 의존이 줄어든다.

GitHub environments 문서는 required reviewers와 deployment protection rules를 별도로 둘 수 있음을 보여 준다.

즉 trust policy는 exact subject 조건, GitHub environment는 승인과 branch 제어라는 서로 다른 역할을 맡는다. 이 둘을 섞지 않으면 환경이 늘어나도 규칙을 더 짧은 표와 비교 가능한 상태로 유지할 수 있다.

다섯 번째 자료는 wildcard 없는 trust policy 예시다. 환경이 세 개여도 repo 식별부를 하나로 두고 environment별 subject를 명시적으로 추가하는 편이 audit 읽기가 좋다.

immutable subject 저장소에서 dev·staging·prod를 exact sub로 나눈 예시다.

이미 organization template와 environment 보호 규칙 글이 rollout 순서를 다뤘다면, 이번 코드는 exact 환경 열거를 통해 wildcard를 없애는 운영판이다.

마지막 자료는 여러 environment 운영표다. trust policy exact subject, environment 보호 규칙, branch 제한을 다른 칸에 남기면 wildcard를 쓰지 않고도 운영이 가능하다.

multi-environment OIDC 운영에서 exact subject와 environment 보호 규칙을 나눠 적는 표다.

둘째 화면의 environment 표시, 셋째 화면의 note 박스, 넷째 화면의 메뉴와 상태, 다섯째 표 비교를 차례로 보면 wildcard 없이도 운영 규칙을 나눌 수 있다는 흐름이 보인다.

또 environment를 붙였는데 sub가 그대로일 때 보는 글이나 name 기반 sub와 immutable subject 분기 글과 같이 보면 exact subject 설계가 더 선명해진다.

여기서 environment별 exact subject를 분리했다면, 다음 판단은 environment별 IAM role을 따로 둘지 sub 목록을 한 trust policy에 둘지 고르는 글에서 이어서 보는 편이 맞다. 같은 immutable subject 가지 안에서 wildcard 제거 다음의 구조 선택을 다룬다.

5. 주의사항과 리스크

첫 번째 리스크는 environment가 늘자마자 trust policy를 wildcard로 넓혀 버리는 것이다. 두 번째는 exact subject를 만들지 않고 environment 보호 규칙만 믿는 것이다. 세 번째는 required reviewers와 deployment branch 규칙을 따로 두지 않아, cloud trust는 맞는데 GitHub 쪽 통제가 약해지는 것이다.

운영 전에 확인할 때는 최소한 각 environment의 actual sub, required reviewers, deployment branches를 한 표에 남기는 편이 좋다. 그래야 어떤 환경이 어떤 통제로 보호되는지 바로 설명할 수 있다.

• environment 수 증가와 wildcard 확장은 같은 뜻이 아니다.
• exact subject와 environment 보호 규칙을 서로 다른 역할로 둔다.
• custom claim보다 actual sub를 먼저 믿는다.

6. 결론

immutable subject 저장소에서 여러 environment를 운영할 때 trust policy를 wildcard 없이 유지하는 핵심은 repo 식별부를 고정하고 environment별 exact subject를 명시적으로 나누는 일이다. GitHub environment는 승인과 branch 제어를 맡기고, AWS trust policy는 exact subject만 맡기면 환경이 늘어나도 규칙을 더 짧은 표와 비교 가능한 상태로 유지할 수 있다.

• repo 식별부는 한 번 고정한다.
• environment별 exact subject를 따로 적는다.
• wildcard 제거는 exact subject 검증 뒤에 한다.

7. 참고 링크

1. https://docs.github.com/actions/reference/openid-connect-reference
2. https://docs.github.com/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services
3. https://docs.github.com/actions/deployment/targeting-different-environments/using-environments-for-deployment