Fullmoon System

GitHub Actions AWS OIDC 배포: 저장소·브랜치·환경별 권한 제한과 검증

AI Editter

장기 AWS 키를 OIDC로 바꿨는데 아무 브랜치에서나 운영 역할을 사용할 수 있다면 자격 증명의 수명만 짧아진 상태입니다. 실제 배포 경계를 정하는 것은 IAM 역할의 신뢰 정책, 역할이 가진 권한, GitHub 환경 보호 규칙입니다.

설정을 세 층으로 나눠 보면 오류도 찾기 쉽습니다. 첫 번째는 GitHub가 토큰을 발급할 수 있는지, 두 번째는 AWS가 그 주체를 신뢰하는지, 세 번째는 발급받은 역할이 필요한 리소스 작업을 허용하는지입니다.

2026년에는 sub 형식을 먼저 확인

GitHub 공식 AWS OIDC 안내는 2026년 7월 15일 이후 생성된 저장소 또는 immutable subject에 참여한 저장소에서 소유자·저장소 ID를 포함하는 형식을 설명합니다. 과거 블로그의 문자열을 그대로 복사하면 새 저장소에서 신뢰 조건이 맞지 않을 수 있습니다.

구분브랜치 기준 sub 형식 예시
이름 기반 형식repo:ORG/REPO:ref:refs/heads/main
ID 포함 형식repo:ORG@OWNER_ID/REPO@REPOSITORY_ID:ref:refs/heads/main

ORG·REPO·ID는 자신의 값으로 바꿉니다. 조직의 subject 사용자 지정 여부도 확인합니다. JWT 전체를 빌드 로그에 출력하지 말고, 저장소 설정과 공식 OIDC 참조에서 적용 형식을 확인합니다.

브랜치와 environment는 같은 조건이 아니다

environment를 사용하지 않는 이름 기반 형식의 main 브랜치를 허용한다면 신뢰 정책 Condition의 한 예는 다음과 같습니다. 전체 IAM 정책이 아닌 조건 부분이며, ID 포함 형식이면 sub를 그 형식에 맞춰야 합니다.

{
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:sub": "repo:ORG/REPO:ref:refs/heads/main"
  }
}

job에 environment를 지정하면 subject에 환경 이름이 들어가는 구성을 사용합니다. 이때 브랜치 제한까지 자동으로 같은 문자열에 포함된다고 가정하지 않습니다. 해당 environment에서 허용 브랜치·태그와 필요한 승인을 설정합니다.

repo:ORG/REPO:*처럼 넓은 패턴은 편하지만 PR·다른 브랜치·환경까지 허용 범위를 넓힐 수 있습니다. 운영과 시험 환경은 별도 역할로 나누고 각각의 subject를 제한합니다.

id-token 권한과 AWS 작업 권한을 분리

permissions:
  contents: read
  id-token: write

위 설정은 OIDC 토큰 요청을 허용하는 설정입니다. S3 업로드나 ECS 배포 권한을 직접 부여하지 않습니다. 토큰 교환에는 검토한 버전의 aws-actions/configure-aws-credentials를 사용하고, 공급망 변경을 관리하려면 확인한 전체 커밋 SHA로 고정합니다.

정책답하는 질문
IAM trust policy누가 이 역할을 맡을 수 있는가
역할 permission policy역할이 어떤 AWS 작업을 할 수 있는가
GitHub environment 규칙어떤 배포가 그 환경에 진입할 수 있는가
리소스 정책·KMS 정책대상 리소스가 추가 조건을 요구하는가

역할 권한은 실제 배포 대상에 한정합니다. 예를 들어 특정 버킷의 배포 경로만 필요하다면 모든 S3 리소스를 허용할 이유가 있는지 검토합니다. KMS 암호화 버킷은 S3 권한 외의 키 권한도 필요할 수 있습니다.

성공 시험과 거절 시험을 함께 수행

시험기대 결과
허용 저장소·main·정상 환경역할 획득과 시험 리소스 작업 성공
같은 저장소의 다른 브랜치정책상 허용하지 않았다면 거절
다른 저장소거절
외부 PR의 테스트 job운영 역할 획득 불가
정상 역할로 범위 밖 리소스 접근거절

첫 시험은 운영 배포 대신 시험용 객체의 조회·업로드처럼 영향이 제한된 작업으로 진행합니다. aws sts get-caller-identity로 계정과 역할을 확인할 수 있지만 이 명령이 성공했다고 배포 권한까지 모두 검증된 것은 아닙니다.

CloudTrail에서 역할 세션과 실제 API 호출을 대조합니다. 실행 번호를 역할 세션 이름에 포함하면 GitHub 실행과 AWS 기록을 연결하기 쉽습니다.

AccessDenied를 세 단계로 추적

토큰 요청 자체가 실패하면 job permissions와 실행 컨텍스트를 확인합니다. AssumeRoleWithWebIdentity가 실패하면 provider·audience·subject와 역할 ARN을 확인합니다. 역할 획득 후 S3나 ECS 작업이 실패하면 permission policy, 리소스 정책, KMS, 조직의 제한 등을 확인합니다.

오류를 없애려고 subject를 와일드카드로 바꾸고 AdministratorAccess를 붙이면 어느 단계가 문제였는지 알 수 없게 됩니다. 실패 단계의 기록을 남기고 필요한 조건만 수정한 뒤, 허용 시험과 거절 시험을 다시 실행합니다.

관련 절차: GitHub Actions 비용 줄이기: 실행 시간·캐시·artifact 점검