GitHub Actions OIDC — AWS 시크릿 없이 배포하는 법

예전에 AWS 배포 워크플로우 짤 때 `AWS_ACCESS_KEY_ID`랑 `AWS_SECRET_ACCESS_KEY`를 GitHub Secrets에 박아두는 방식으로 했거든요. 그런데 이게 장기 자격증명(long-lived credential)이라 유출되면 진짜 위험해요. 로테이션도 귀찮고. 2022년부터 GitHub Actions가 OIDC(OpenID Connect)를 공식 지원하면서 이 문제를 깔끔하게 해결할 수 있게 됐어요.

## OIDC가 뭔가요

OpenID Connect는 OAuth 2.0 위에 올라간 인증 레이어예요. 여기서 핵심은 GitHub Actions가 **워크플로우 실행마다 단기 JWT 토큰을 발급**한다는 거예요. 이 토큰에는 레포 이름, 브랜치, 트리거 이벤트 같은 클레임이 들어있고, AWS가 이 토큰을 검증해서 일시적인 자격증명을 내어줘요.

즉 흐름이 이렇게 됩니다:

```
GitHub Actions 워크플로우 실행
  → GitHub OIDC Provider가 JWT 발급
  → AWS STS의 AssumeRoleWithWebIdentity 호출
  → 임시 자격증명 (15분~1시간) 반환
  → S3 업로드 / ECS 배포 등 실행
```

장기 크리덴셜이 어디에도 저장되지 않아요. 워크플로우가 끝나면 토큰도 만료됩니다.

## AWS에서 설정하는 방법

먼저 AWS IAM에서 OIDC 자격증명 공급자를 등록해야 해요.

**Provider URL**: `https://token.actions.githubusercontent.com`  
**Audience**: `sts.amazonaws.com`

그다음 IAM 역할(Role)을 만들고, 신뢰 정책(Trust Policy)에 이런 조건을 걸어요:

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::ACCOUNT_ID:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:YOUR_ORG/YOUR_REPO:*"
        }
      }
    }
  ]
}
```

`sub` 조건에 특정 브랜치만 허용하거나 (`ref:refs/heads/main:*`) 특정 환경만 허용하는 것도 가능해요. 이게 장기 크리덴셜 방식보다 훨씬 세밀하게 접근 제어가 가능한 이유예요.

## 워크플로우에서 사용하기

```yaml
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write   # OIDC 토큰 발급 필수
      contents: read

steps:
      - uses: actions/checkout@v4

- name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::ACCOUNT_ID:role/github-actions-deploy
          aws-region: ap-northeast-2

- name: Deploy to S3
        run: aws s3 sync ./dist s3://my-bucket --delete
```

`permissions.id-token: write`가 없으면 OIDC 토큰이 발급 안 돼요. 이거 빠뜨리면 `Error: Credentials could not be loaded` 같은 에러가 나서 처음엔 당황할 수 있어요.

## 실제로 써보니

저는 이걸로 CloudFront 배포 + S3 업로드 파이프라인을 구성했는데, 한 가지 주의할 게 있었어요. 여러 AWS 계정(dev/prod)에 배포할 때는 역할 ARN을 environment별로 분리하는 게 깔끔해요. GitHub Environments 기능이랑 같이 쓰면 `production` 환경에서만 prod 계정 역할을 assume하도록 제한할 수 있어요.

GCP도 Workload Identity Federation으로 동일한 개념을 지원하고, Azure도 Federated Identity Credentials로 같은 걸 할 수 있어요. 이제 CI/CD에서 장기 크리덴셜을 쓰는 건 레거시 방식에 가까워지고 있어요.

GitHub Actions OIDC — AWS 시크릿 없이 배포하는 법

// COMMENTS

ON THIS PAGE