[GitHub Actions][OIDC] reusable workflow를 공용 배포 엔트리로 쓸 때 AWS trust policy에서 sub 형식을 먼저 고정하는 법

IT 리서치 노트

[GitHub Actions][OIDC] reusable workflow를 공용 배포 엔트리로 쓸 때 AWS trust policy에서 sub 형식을 먼저 고정하는 법

GitHub Actions에서 reusable workflow를 공용 배포 엔트리로 쓰기 시작하면, 이전에 branch나 repository 기준으로만 만들었던 AWS OIDC trust policy가 갑자기 넓어지거나 예상과 다르게 실패할 수 있다. 2026년 6월 26일 기준 GitHub 공식 문서를 다시 보면 reusable workflow 환경에서는 `job_workflow_ref`와 subject customization을 같이 읽어야 하고, AWS는 custom claim 직접 매칭을 지원하지 않는다. 그래서 이 문제는 GitHub 템플릿보다 AWS trust policy가 기대할 `sub` 형식을 먼저 고정하는 쪽이 빠르다.

목차

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

1. 개요

결론부터 말하면 reusable workflow 배포를 AWS OIDC로 묶을 때는 GitHub 템플릿보다 AWS trust policy가 기대할 sub 형식을 먼저 정하는 편이 빠르다. AWS는 custom claim 직접 매칭을 지원하지 않으므로, repository와 environment와 reusable workflow 경계를 어떤 문자열로 고정할지 먼저 써 둬야 subject customization이 흔들리지 않는다.

이미 custom subject claim 템플릿 글을 읽었다면 이번 글은 그 다음 단계다. GitHub에서 어떤 claim을 끌어올지보다 AWS trust policy가 결국 어떤 sub 하나를 비교하는지에 초점을 맞춘다.

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

실무에서 흔한 막힘은 세 가지다. 첫째, reusable workflow를 도입했는데 AWS trust policy는 여전히 caller repository나 branch만 보고 있어 배포 범위가 생각보다 넓어진다. 둘째, GitHub 문서에서 job_workflow_ref를 본 뒤 AWS가 그 claim을 직접 읽을 거라고 오해한다. 셋째, subject customization을 바꾼 뒤 이전 sub 형식과 role condition을 같이 갱신하지 않아 토큰 발급은 되는데 assume role이 실패한다.

이 문제는 id-token: write 누락과 다르다. 토큰 발급 자체가 안 되는 것이 아니라, 어떤 workflow가 어떤 role에 들어갈 수 있는지를 문자열로 고정하는 단계에서 어긋나는 문제다. 그래서 id-token: write 실패 글과 같은 원인으로 보면 해결 순서가 어긋난다.

• 증상: caller repository는 맞는데 reusable workflow 변경 뒤 assume role이 실패한다.
• 실패: AWS가 job_workflow_ref를 개별 claim으로 직접 읽을 것이라 가정한다.
• 막힘: GitHub subject customization만 바꾸고 AWS trust policy는 예전 sub 형식으로 둔다.
• 누락: environment를 붙인 뒤 기본 sub 형식이 바뀌는 점을 놓친다.

증상	먼저 볼 곳	판단 기준
reusable workflow 도입 뒤 role assumption 실패	현재 sub 형식과 trust policy	repository 외에 environment와 called workflow가 필요한지 본다
claim은 보이는데 AWS에서 못 쓴다	AWS custom claim 지원 범위	개별 claim 비교가 아니라 sub 설계 문제로 본다
template 적용 후 기존 배포가 깨진다	기존 role condition과 subject customization	예전 sub 예시와 새 형식을 같이 비교한다

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

가장 안전한 순서는 네 단계다. 먼저 허용할 배포 경계를 repository, environment, called workflow 경로 기준으로 문장으로 적는다. 둘째, AWS가 어떤 claim을 직접 읽을 수 없는지 확인한다. 셋째, 그 경계를 sub 형식으로 다시 써 보고 필요한 경우에만 GitHub subject customization REST API를 설계한다. 마지막으로 AWS trust policy와 GitHub workflow를 같이 대조해 토큰 발급 문제와 매칭 문제를 분리한다.

1. 허용할 caller repo, environment, reusable workflow 경계를 문장으로 적는다.
2. AWS가 custom claim 직접 매칭을 지원하지 않는다는 전제를 확인한다.
3. 필요한 값만 sub 형식에 포함되도록 subject customization을 설계한다.
4. AWS trust policy와 GitHub workflow 조건을 함께 다시 본다.

운영 메모 예시

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

이 메모를 먼저 만들면 GitHub 템플릿을 바꾸기 전에도 현재 role condition이 충분히 좁은지 판단할 수 있다. 반대로 메모 없이 API 요청부터 보내면 나중에 어떤 claim이 실제로 필요했는지 다시 되짚기 어렵다.

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

첫 화면은 reusable workflow와 OIDC를 같이 다루는 GitHub 문서다. 여기서 핵심은 공용 deploy workflow를 도입하면 caller repository만 보는 trust policy로는 배포 경계가 충분히 줄어들지 않을 수 있다는 점이다.

GitHub 문서는 reusable workflow 환경에서 `job_workflow_ref`를 trust condition 후보로 따로 설명한다.

즉 reusable workflow를 중앙 배포 엔트리로 쓰는 순간 repository, environment, called workflow 경로를 어떤 문자열로 cloud provider에 전달할지 다시 정해야 한다. 이미 발행한 custom subject claim 템플릿 글이 GitHub 쪽 설계라면, 이번 글은 AWS trust policy 쪽 고정 순서다.

두 번째 자료는 OIDC reference의 claim 설명이다. `job_workflow_ref`는 called workflow 파일 경로와 ref를 같이 담기 때문에, reusable workflow를 묶고 싶은지 caller repository만 묶고 싶은지 판단 기준을 분명하게 만들어 준다.

OIDC reference는 reusable workflow 실행에서 `job_workflow_ref`가 어떤 값을 담는지 설명한다.

반대로 이 값을 읽지 않는 provider에서는 claim 존재 자체가 의미를 갖지 못한다. 그래서 claim 이름을 먼저 아는 것보다, provider가 그 claim을 어디서 비교할 수 있는지가 더 중요하다.

세 번째 화면은 GitHub의 AWS OIDC 가이드다. 이 문서가 중요한 이유는 AWS가 custom claim 직접 매칭을 지원하지 않는다고 분명히 적고 있기 때문이다.

AWS OIDC 가이드는 custom claim 직접 지원이 없다고 적어 `sub` 형식 설계를 먼저 하게 만든다.

즉 AWS에서 reusable workflow 범위를 줄이려면 `job_workflow_ref`를 개별 claim으로 비교하려 하기보다, GitHub 쪽 subject customization으로 필요한 문자열을 `sub` 안에 넣고 그 형식을 trust policy와 같이 맞추는 편이 현실적이다.

네 번째 자료는 repository 단위 subject customization REST API다. reusable workflow 경계를 `sub`에 넣으려면 결국 이 API에서 `include_claim_keys`를 어떻게 보낼지 결정해야 한다.

OIDC REST API 문서는 subject customization을 repository나 organization 단위로 바꾸는 경로를 보여 준다.

다만 여기서 템플릿을 먼저 바꾸면 안 된다. 먼저 AWS trust policy가 기대할 문자열과 현재 workflow 구조를 메모로 정리한 뒤 API 요청을 보내야 실패 범위를 줄일 수 있다.

실무에서는 claim 표보다 trust policy 예시가 더 빨리 감을 준다. AWS는 결국 `token.actions.githubusercontent.com:sub` 한 줄에서 비교하므로, reusable workflow를 어디까지 포함할지 문자열로 먼저 써 보는 편이 낫다.

AWS trust policy 예시는 environment와 reusable workflow 경계를 `sub` 형식으로 어떻게 고정할지 보여 준다.

이 예시는 branch 하나를 하드코딩하려는 뜻이 아니라, 현재 배포 경계를 사람이 읽을 수 있는 문자열로 먼저 분해해 보자는 뜻이다. 이 작업이 되어 있어야 subject claim과 environment 조건 글과 id-token: write 실패 글을 어디에 다시 참고할지 바로 잡힌다.

마지막 자료는 실제 점검 순서를 정리한 표다. reusable workflow 배포는 caller repository, environment, called workflow 세 축이 섞여 있기 때문에 어떤 값을 `sub`에 넣고 무엇을 AWS trust policy가 기대하는지 먼저 고정해야 한다.

reusable workflow OIDC 점검표는 `sub` 형식, AWS trust policy, GitHub subject customization을 같은 순서에서 보게 만든다.

이 표를 기준으로 보면 OIDC 범위 설계는 항상 workflow별 권한 분리 글보다 한 단계 뒤에 있다. 토큰 발급 권한을 줄이는 일과, 발급된 토큰이 어떤 배포 엔트리에만 통하도록 묶는 일은 서로 다른 단계다.

5. 주의사항과 리스크

첫 번째 리스크는 GitHub 문서의 claim 목록을 그대로 AWS trust policy로 옮길 수 있다고 오해하는 것이다. 두 번째 리스크는 environment와 reusable workflow를 도입한 뒤에도 예전 branch 중심 sub 형식을 그대로 두는 것이다. 세 번째 리스크는 subject customization을 변경하면서 기존 배포 role을 순차적으로 검증하지 않는 것이다.

운영 전에는 최소한 branch 기준, environment 기준, reusable workflow 기준 세 경우의 sub 예시를 따로 남겨 두는 편이 좋다. 그래야 실패가 YAML 권한 문제인지, role condition 문제인지 바로 갈라진다.

• AWS에서는 job_workflow_ref보다 sub 형식 고정이 먼저다.
• subject customization은 trust policy 설계 뒤에 온다.
• environment 도입 시 기존 sub 예시를 같이 재검토한다.

6. 결론

GitHub reusable workflow를 AWS OIDC로 묶을 때는 job_workflow_ref를 안다고 해결되지 않는다. AWS trust policy가 어떤 sub 문자열을 기대할지 먼저 정하고, 그다음 GitHub subject customization으로 필요한 값을 끌어오는 순서가 가장 안정적이다.

• repository, environment, called workflow 경계를 먼저 적는다.
• AWS custom claim 미지원 전제를 먼저 확인한다.
• sub 형식과 trust policy를 함께 갱신한다.

7. 참고 링크

1. https://docs.github.com/actions/deployment/security-hardening-your-deployments/using-openid-connect-with-reusable-workflows
2. https://docs.github.com/actions/reference/openid-connect-reference
3. https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws
4. https://docs.github.com/en/rest/actions/oidc?apiVersion=2026-03-10