GitHub Actions OIDC 체크리스트: 배포 키 없애기 전 permissions와 trust policy 점검

배포용 cloud key를 GitHub Secrets에 오래 넣어둔 팀이라면, 먼저 OIDC 전환 가능 여부부터 확인해두는 편이 좋습니다. GitHub Actions OIDC는 workflow가 cloud provider에 직접 인증해 짧은 수명의 access token을 받는 방식이라, 장기 배포 키를 줄일 때 쓰입니다.

기준일: 2026년 6월 19일. GitHub Actions와 cloud security 문서는 수시로 바뀝니다. 아래 체크리스트는 공식 문서 기준으로 배포 전 점검할 순서를 잡아주는 용도이며, 실제 role 이름이나 provider별 condition 문법은 각 cloud 계정의 최신 콘솔과 문서에서 다시 확인해야 합니다.

먼저 무엇을 결정해야 하나요?

작은 팀에서는 OIDC 설정 자체보다 경계 정리가 더 오래 걸립니다. 어느 repository, 어느 branch, 어느 environment에 production role을 허용할지 먼저 정해야 trust policy가 깔끔해집니다.

OIDC readiness checklist

아래 항목이 정리되어야 OIDC가 단순한 보안 장식이 아니라 실제 배포 경계가 됩니다. 전부 새로 만들기보다, 현재 배포 workflow를 열어놓고 하나씩 지우거나 바꾸는 방식이 덜 헷갈립니다.

• Cloud provider가 GitHub Actions OIDC를 지원하는지 확인: GitHub 문서는 cloud provider가 GitHub의 OIDC를 federated identity로 신뢰하도록 구성한 뒤, workflow에서 token을 받아 cloud access token으로 교환하는 흐름을 설명합니다.
• 장기 deploy key 사용처 정리: repository secrets, organization secrets, environment secrets, 외부 CI 변수까지 같은 key가 흩어져 있지 않은지 봅니다. 이미 secret 관리가 꼬여 있다면 AI API 키 유출 방지 체크리스트처럼 저장 위치부터 줄이는 쪽이 먼저입니다.
• 배포 단위를 role로 쪼개기: staging과 production이 같은 role을 쓰면 OIDC로 바꿔도 피해 범위가 넓습니다. 최소한 environment별 role 분리를 검토합니다.
• 공식 cloud login action 또는 검증된 token 교환 절차 확인: provider가 공식 action을 제공하면 그 경로를 우선 보고, 직접 JWT를 요청하는 custom step은 감사와 유지보수 부담까지 같이 계산합니다.
• 기존 key 폐기 시점 정하기: OIDC 전환 직후 바로 삭제할지, 짧은 rollback 기간을 둘지 정하고 만료일을 티켓에 남깁니다.

minimal workflow permissions checklist

OIDC를 쓰려면 배포 job 또는 workflow에 id-token: write가 필요합니다. 다만 이 권한은 외부 서비스 인증용 OIDC token 요청을 허용하는 것이지, repository에 쓰기 권한을 자동으로 주는 의미는 아닙니다.

• 배포 job에 필요한 permission만 적습니다. 예를 들어 source checkout만 필요하면 contents는 read 수준부터 봅니다.
• workflow 전체에 넓게 주기보다, 가능하면 배포 job 단위에서 좁게 둡니다.
• permissions 키에 일부 항목을 명시하면, 명시하지 않은 permission은 none이 되는 동작을 확인합니다.
• read-all이나 write-all은 임시 진단용으로도 production workflow에 남기지 않습니다.
• pull request에서 배포가 실행되지 않도록 event와 condition을 같이 봅니다. 특히 fork나 외부 contributor 흐름이 있으면 더 보수적으로 잡습니다.

운영 기준으로는 id-token: write 하나를 추가하는 데서 멈추지 말고, 주변에 남아 있는 write permission과 배포 trigger까지 줄여야 사고 범위가 좁아집니다.

branch와 environment 경계는 어디서 막아야 하나요?

GitHub 문서는 environment를 workflow나 OIDC policy에 사용할 때, 추가 보안을 위해 environment protection rules를 권장합니다. 작은 팀에서도 production은 environment로 분리하고, 허용 branch와 reviewer 규칙을 같이 묶어두면 실수 배포가 줄어듭니다.

• production 배포 job에는 production environment를 붙입니다.
• production environment에서 배포 가능한 branch나 tag를 제한합니다.
• main, release tag, hotfix branch처럼 실제 배포 경로만 남기고 실험 branch는 제외합니다.
• 승인이 필요한 조직이라면 environment reviewer를 둡니다. 1인 개발자라도 수동 승인 step을 rollback 전 확인 지점으로 쓰면 됩니다.
• environment secret이 남아 있다면 OIDC 전환 후 계속 필요한지 따로 표시합니다.

trust policy claim checklist

Cloud role trust policy에서 OIDC 전환의 실제 경계가 정해집니다. GitHub 쪽 workflow가 token을 받을 수 있어도, cloud provider가 claims를 너무 넓게 받아주면 다른 repository나 branch에서 같은 role을 요청할 여지가 생깁니다.

• issuer 확인: AWS IAM OIDC provider를 만들 때 provider URL은 https로 시작해야 하며, discovery document와 issuer, JWKS 정보를 확인해야 합니다.
• audience 확인: AWS IAM OIDC provider에는 audience, 즉 client ID를 등록합니다. GitHub Actions에서 cloud provider가 기대하는 audience 값과 role 조건이 맞는지 봅니다.
• subject 경계 확인: repository, branch, tag, environment처럼 배포 주체를 구분하는 claims가 trust policy 조건에 반영되는지 확인합니다. provider별 문법이 다르므로 예제 복사 전에 실제 token의 claims와 공식 문서를 맞춰봅니다.
• environment 조건 확인: production environment를 쓴다면 trust policy도 production 경계를 따라가야 합니다. workflow 파일에만 environment가 있고 role 조건이 넓으면 절반만 막은 셈입니다.
• wildcard 줄이기: organization 전체, repository 전체, 모든 branch를 허용하는 pattern은 처음에는 편하지만 사고 범위도 같이 넓어집니다.
• AWS custom claims 주의: GitHub 보안 문서는 AWS에서 OIDC custom claims 지원이 없다고 안내합니다. AWS를 쓰는 경우 custom claim 전제를 두고 설계하지 말고, AWS가 지원하는 조건 키와 audience, subject 경계를 기준으로 잡아야 합니다.

Secret Scanning fallback은 왜 남겨야 하나요?

OIDC로 전환해도 과거에 들어간 deploy key, 로그에 찍힌 token, 외부 도구에 남은 key까지 자동으로 사라지지는 않습니다. 그래서 Secret Scanning은 OIDC 전환 후에도 fallback으로 남기는 쪽이 안전합니다.

• OIDC 전환 전후로 repository와 organization secrets를 감사하고, 더 이상 쓰지 않는 secret은 제거합니다.
• 과거 배포 key가 commit history나 issue, workflow log에 노출됐는지 확인합니다.
• Secret Scanning alert가 발생하면 알림 닫기보다 key 폐기, 영향 범위 확인, 재발 방지 순서로 처리합니다. 자세한 대응 순서는 GitHub Secret Scanning 알림 대응 체크리스트와 이어서 보면 좋습니다.
• 외부 SaaS나 self-hosted runner에 남은 credential은 GitHub 안에서만 보이지 않을 수 있으므로 별도 inventory에 남깁니다.

failure와 rollback checklist

OIDC 배포 실패는 대부분 권한이 부족하거나 claim 조건이 맞지 않을 때 발생합니다. 바로 production key를 되살리기보다, 어떤 경계에서 막혔는지 확인하면 rollback도 더 작게 끝납니다.

1. workflow permissions 확인: 배포 job에 id-token: write가 있는지, 필요한 contents 또는 package 권한이 너무 좁게 닫히지 않았는지 봅니다.
2. environment 조건 확인: job이 기대한 environment로 실행됐는지, branch protection이나 required reviewer에서 멈춘 것은 아닌지 확인합니다.
3. cloud provider trust policy 확인: issuer, audience, subject 조건이 실제 workflow 실행 맥락과 맞는지 봅니다.
4. role 권한 확인: OIDC 인증은 성공했지만 role policy가 배포 대상 리소스 권한을 막는 경우가 있습니다. 인증 실패와 권한 실패를 나눠서 기록합니다.
5. 임시 rollback key 사용 조건 확인: 꼭 필요할 때만 짧은 만료일과 제한된 권한으로 되살리고, 사용 후 폐기 티켓을 닫기 전에 삭제 여부를 확인합니다.
6. 재시도 전 로그 정리: 실패 로그에 token, account ID, 내부 endpoint가 불필요하게 남지 않았는지 봅니다.

작은 팀용 운영 순서

처음부터 모든 배포를 한 번에 바꾸면 원인 분리가 어렵습니다. staging role 하나로 OIDC를 검증하고, production은 같은 구조를 복사하기보다 environment와 trust policy 조건을 더 좁힌 뒤 옮기는 편이 낫습니다.

1. 현재 deploy key와 배포 workflow를 표로 정리합니다.
2. staging role에 OIDC provider와 trust policy를 붙입니다.
3. workflow permissions를 필요한 범위로 줄이고 id-token: write만 필요한 job에 둡니다.
4. staging 배포 로그에서 token 교환 성공과 권한 실패를 분리해 봅니다.
5. production environment protection rule과 role trust policy를 맞춥니다.
6. 기존 deploy key는 rollback 기간을 정한 뒤 폐기합니다.
7. Secret Scanning alert와 secret inventory를 한 번 더 봅니다.

발행 전 최종 확인

GitHub Actions OIDC 체크리스트의 목적은 장기 key를 없애는 데서 끝나지 않습니다. workflow permissions, claims, environment, role trust policy가 같은 경계를 가리키는지 확인해야 실제 배포 보안이 좋아집니다.

• permissions는 필요한 범위로 좁혔는가?
• id-token: write는 배포 job에만 있는가?
• production environment는 branch와 reviewer로 보호되는가?
• cloud role trust policy는 repository, branch 또는 environment 경계를 반영하는가?
• 기존 deploy key의 폐기일과 rollback 조건이 문서화됐는가?
• Secret Scanning alert 대응 경로가 남아 있는가?