[GitHub Actions][OIDC] subject claim과 environment 조건을 같이 묶어 배포 범위를 줄이는 법

IT 리서치 노트

[GitHub Actions][OIDC] subject claim과 environment 조건을 같이 묶어 배포 범위를 줄이는 법

GitHub Actions OIDC를 붙였는데도 deploy role이 예상보다 넓게 열리거나, 반대로 production environment를 붙인 뒤 갑자기 인증이 실패하는 경우가 있다. 2026-06-22 기준 GitHub Docs를 다시 보면 핵심은 id-token: write 자체보다 sub 안에 어떤 metadata가 들어가고, reusable workflow를 쓸 때 job_workflow_ref를 어디까지 조건으로 묶는지에 있다. 이 글은 environment, subject claim, reusable workflow, repository customization template를 어떤 순서로 맞춰야 trust policy를 덜 흔들리게 유지할 수 있는지 정리한다.

목차

1. 개요
2. 어디서 어긋나는가
3. 조건을 다시 묶는 순서
4. 문서 화면으로 확인할 항목
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

OIDC 설정에서 자주 생기는 오해는 id-token: write를 추가하면 배포 보안이 끝난다고 보는 것이다. 실제 운영에서는 토큰을 발급받는 단계와, 그 토큰이 어떤 repository, branch, environment, reusable workflow에서 왔는지 cloud provider가 검증하는 단계가 분리되어 있다. 전자는 GitHub Actions YAML 문제이고, 후자는 trust policy 문자열 문제다.

GitHub OIDC의 기본 sub는 trigger와 job metadata에 따라 달라진다. branch run이라면 ref:refs/heads/...가 들어가고, environment를 참조한 job이라면 environment:NAME가 들어간다. reusable workflow를 쓰면 별도의 custom claim인 job_workflow_ref도 생긴다. 그래서 같은 deploy job이라도 environment를 붙이는 순간 subject 조건이 달라져 갑자기 인증이 깨질 수 있다.

• environment를 참조한 job은 기본 sub 문자열이 branch 기준과 달라질 수 있다.
• reusable workflow를 쓰면 caller repository만 보는 조건으로는 범위가 지나치게 넓거나 좁아질 수 있다.
• provider가 aud와 sub만 읽는다면 subject customization template까지 검토해야 한다.

2. 어디서 어긋나는가

현장에서 막히는 지점은 크게 네 가지다. 첫째, main branch 기준으로 trust policy를 만들어 놓고 나중에 job에 environment: Production을 붙인 뒤 subject 문자열이 바뀐 사실을 놓친다. 둘째, organization 안의 reusable workflow를 공통 deploy entry로 쓰는데 cloud role은 caller repository만 묶거나, 반대로 called workflow path를 전혀 보지 않는다. 셋째, provider가 custom claim을 못 읽는데도 job_workflow_ref만 믿고 설계한다. 넷째, repository rename, workflow file rename, subject template opt-in 같은 변경을 반영하지 않고 문자열을 오래 고정해 둔다.

• id-token: write는 들어갔는데 environment를 붙인 뒤 role assumption이 실패한다.
• 같은 deploy workflow를 여러 repository가 재사용하는데 특정 reusable workflow 파일까지는 제한하지 못한다.
• provider가 aud와 sub만 검증하는데 claim 분리를 GitHub 쪽에서 안 해서 조건이 과하게 넓다.
• permissions를 일부만 선언한 뒤 나머지 scope가 none이 된 사실을 놓쳐 토큰 요청 자체가 실패한다.

이 문제를 로그만 보고 해결하려 하면 대개 cloud 권한을 넓히는 쪽으로 흘러간다. 그런데 그 방식은 배포는 통과시켜도 trust boundary는 무너뜨린다. OIDC는 '토큰을 받을 수 있느냐'보다 '어떤 상황에서 받은 토큰만 신뢰하느냐'가 더 중요한 기능이다. 그래서 배포 실패를 줄이는 순서도 permissions, subject 형식, environment, reusable workflow, provider trust 순으로 나눠 보는 편이 낫다.

3. 조건을 다시 묶는 순서

OIDC trust policy를 다시 정리할 때는 먼저 '무엇을 최소 단위로 허용할지'를 문장으로 적는 것이 좋다. 예를 들어 같은 repository의 main branch만 허용할지, production environment를 거친 deploy job만 허용할지, 특정 reusable workflow 파일에서 호출된 배포만 허용할지부터 정해야 한다. 그 문장이 없으면 나중에 sub와 claim을 어디까지 묶어야 하는지 결정이 흔들린다.

1. 먼저 deploy job이 branch 기준인지, environment 기준인지, reusable workflow 기준인지 정한다.
2. environment가 핵심이면 job에 environment를 명시하고 기본 sub 형식이 environment:NAME로 바뀌는지 문서 예시와 대조한다.
3. reusable workflow까지 고정해야 하면 provider가 custom claim을 읽는지 확인하고, 가능하면 job_workflow_ref를 별도 조건으로 둔다.
4. provider가 aud와 sub만 지원하면 repository subject customization template로 repo, context, job_workflow_ref를 sub에 포함시키는 구성을 검토한다.
5. 마지막으로 GitHub Actions permissions를 다시 보고 토큰이 필요한 workflow나 job에만 id-token: write를 남긴다.

배포 경계	먼저 볼 claim	권장 trust 포인트	흔한 실패
같은 repository의 특정 branch	sub의 ref 부분	branch 문자열이 그대로 남는지 확인	environment를 붙인 뒤에도 branch 형식일 것이라 가정
production environment를 거친 deploy	sub의 environment:NAME	environment 이름이 정확히 일치하는지 확인	environment 추가 뒤 subject 조건 미수정
특정 reusable workflow 파일만 허용	job_workflow_ref	workflow path와 ref를 고정	caller repository만 보고 called workflow는 보지 않음

예제 YAML도 최소한으로 나누는 편이 좋다. 아래처럼 deploy job에만 OIDC 권한을 주고, environment를 명시한 뒤 필요한 경우 caller에서 reusable workflow를 부른다. 토큰이 필요한 job이 하나라면 workflow 전체가 아니라 job 단위 선언이 더 안전하다.

안전한 예제 코드

name: deploy-production
on:
  push:
    branches: [main]

jobs:
  deploy:
    permissions:
      contents: read
      id-token: write
    environment: Production
    uses: octo-org/platform/.github/workflows/deploy.yml@refs/heads/main
    secrets: inherit

이 단계까지 왔는데 토큰 요청이 안 되면 먼저 id-token: write가 없을 때 토큰 요청이 실패하는 이유를 다시 보는 편이 낫다. workflow 전체 권한 구조를 더 넓게 정리하고 싶다면 GITHUB_TOKEN 권한과 OIDC를 workflow별로 줄이는 방법이 바로 이어진다. npm Trusted Publishing처럼 repository, workflow, environment 문자열이 정확히 맞아야 하는 사례는 Trusted Publishing으로 npm token 없이 배포하는 절차에서 감각을 잡기 쉽다.

4. 문서 화면으로 확인할 항목

아래 화면은 GitHub Docs에서 실제로 다시 본 순서다. 각 화면에서는 heading, 예시 문자열, 요청 본문, permissions 표, 상태 설명을 따로 본다. 문서 첫 화면만 훑지 말고 어떤 메뉴 경로에서 어떤 문자열을 클릭해 내려왔는지, 어떤 필드와 표에서 결과를 비교해야 하는지 같이 적어 두는 편이 좋다.

먼저 OIDC reference의 subject claim 예시를 본다. GitHub Actions OIDC는 토큰을 발급하는 것보다, 어떤 metadata가 sub에 들어가는지 이해하는 단계가 더 중요하다.

Example subject claims 화면에서는 branch, tag, pull_request, environment에 따라 sub 형식이 어떻게 달라지는지 확인한다.

production 같은 deployment environment를 trust 조건에 넣고 싶다면 이 섹션을 같이 봐야 한다. job이 environment를 참조하면 기본 sub 형식 안에 environment 이름이 들어간다.

Filtering for a specific environment 화면은 environment 이름이 sub에 어떤 문자열로 반영되는지 확인하는 기준이다.

reusable workflow까지 배포 경계를 고정하려면 caller repository만 보는 것으로 부족할 수 있다. 이 문서는 job_workflow_ref를 어떤 식으로 trust 조건에 묶는지 설명한다.

Reusable workflow 문서에서는 특정 workflow 파일과 ref를 job_workflow_ref로 고정하는 예시를 확인할 수 있다.

cloud provider가 aud와 sub만 읽는다면 repository customization template를 검토한다. include_claim_keys로 repo, context, job_workflow_ref를 sub에 넣도록 바꾸는 흐름이 여기서 나온다.

OIDC REST API 화면에서는 repository 단위 subject customization과 include_claim_keys, use_immutable_subject 옵션을 확인한다.

subject claim을 다 맞췄는데도 토큰 요청 자체가 안 되면 permissions를 먼저 다시 본다. GitHub 문서 기준으로 permissions를 하나라도 명시하면 적지 않은 권한은 none으로 떨어질 수 있다.

Workflow syntax 화면은 permissions 일부만 선언했을 때 나머지 권한이 none으로 계산된다는 점을 다시 확인하는 위치다.

이 순서로 보면 subject 형식이 언제 바뀌는지, provider가 custom claim을 읽지 못할 때 어디서 sub를 보강해야 하는지, permissions를 넓히지 않고도 문제를 좁힐 수 있는지를 한 번에 대조할 수 있다. 화면마다 확인할 핵심은 예시 문자열, context 값, workflow 파일 경로, REST 요청 body, permissions 결과 표다. 버튼을 누르거나 YAML을 수정하기 전에 이 다섯 가지를 먼저 비교해야 오류 원인을 덜 넓게 잡게 된다.

5. 주의사항과 리스크

trust policy를 너무 넓게 두는 실수와, subject 형식 변경을 뒤늦게 반영하는 실수는 같이 온다. 특히 environment를 기준으로 배포 보호를 설계했는데 branch 기준 sub 문자열만 남겨 두면 policy는 통과해도 보호 의도가 무너진다. 반대로 reusable workflow까지 고정해야 하는데 caller repository만 본다면 공용 deployment workflow를 누구나 같은 role로 태우는 셈이 될 수 있다.

• provider가 custom claim을 지원하지 않는데 job_workflow_ref만 믿고 설계하면 조건이 실제로 적용되지 않을 수 있다.
• use_immutable_subject를 organization 또는 repository에서 opt-in하면 sub 형식이 repository ID 기반으로 바뀔 수 있으므로 기존 trust 문자열을 그대로 두면 배포가 깨질 수 있다.
• repository rename, workflow file rename, environment 이름 변경은 모두 trust policy 문자열 재검토 사유다.
• permissions를 일부만 선언했다면 나머지가 none으로 계산되는지 같이 봐야 토큰 미발급 원인을 놓치지 않는다.

실무에서는 문자열을 policy에 바로 박아 넣기 전에 '허용할 repository, environment, workflow path 목록'을 별도 메모로 관리하는 편이 좋다. 그래야 배포 실패가 났을 때 cloud role을 넓히는 대신 어떤 문자열이 바뀌었는지 먼저 비교할 수 있다.

6. 결론

GitHub Actions OIDC는 토큰을 발급받는 순간보다, 어떤 metadata를 가진 토큰만 허용할지 정하는 순간에 품질이 갈린다.

• environment를 보호 경계로 쓴다면 기본 sub가 그 이름을 반영하는지 먼저 확인한다.
• reusable workflow까지 배포 범위에 넣고 싶다면 job_workflow_ref 또는 subject customization을 같이 설계한다.
• permissions, subject, provider trust policy를 한 번에 넓히지 말고 순서대로 고친다.

이 세 가지만 지켜도 deploy role을 필요 이상으로 넓히지 않으면서 production 배포 실패를 훨씬 빠르게 좁힐 수 있다. OIDC는 secret을 없애는 기능이기도 하지만, 실제로는 배포 경계를 문자열로 명확히 고정하는 기능이라는 점을 잊지 않는 편이 좋다.

7. 참고 링크

1. https://docs.github.com/en/actions/reference/security/oidc
2. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-with-reusable-workflows
3. https://docs.github.com/en/rest/actions/oidc?apiVersion=2026-03-10
4. https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
5. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-cloud-providers