infra · app · ai

PaperTutor 배포 파이프라인

코드가 main에 들어간 뒤 dev를 거쳐 prod에 올라가기까지의 경로와, 그 과정에서 GitHub Actions가 AWS에 들어가는 방법(OIDC)을 2026-10-01 실제 배포 기록으로 정리했다.

1. 전체 그림

원칙은 하나다. prod에서는 빌드하지 않는다. dev 배포가 만든 산출물(이미지, FE tar)을 SHA로 골라 그대로 prod에 올린다.

dev main push

app: be/**·fe/** 변경 시
ai: 모든 push

dev 배포 워크플로

빌드 → 이미지 push → ECS 배포
FE는 빌드 → S3 sync
산출물 보관→

dev ECR

backend·ai 이미지
태그 = commit SHA
최근 30개 보관

산출물 버킷

papertutor-fe-artifacts
fe/<sha>.tar.gz
365일 보관
SHA 지정→

prod Deploy prod

infra 레포, 수동 실행
verify → AI → BE → FE

prod ECR · ECS · S3

이미지 복사 → 새 revision
tar 풀어서 S3 → 무효화

왼쪽은 자동, 오른쪽은 사람이 버튼을 누른다. 가운데 보관소가 두 세계를 잇는다.

2. dev 배포 자동

레포 세 곳에 워크플로가 하나씩 있다. main에 push되면 돌고, 끝나면 그 커밋 SHA 이름으로 산출물이 남는다.

Deploy BE (dev) app

  • 트리거: main push, be/** 변경 시
  • Gradle 빌드 → 이미지 → dev ECR push (태그 SHA)
  • 현재 task definition 복제, 이미지만 교체 → 새 revision → 서비스 갱신 → 안정화 대기
  • Role: papertutor-dev-app-deploy

Deploy FE (dev) app

  • 트리거: main push, fe/** 변경 시
  • Vite 빌드 → dist/
  • tar로 산출물 버킷에 보관 (같은 SHA면 건너뜀)
  • dev S3 sync → CloudFront 무효화

Deploy AI (dev) ai

  • 트리거: main push 전부
  • 이미지 하나 → dev ECR push
  • api·parser-worker·compile-worker 3개 서비스에 같은 이미지로 배포
  • Role: papertutor-dev-ai-deploy

왜 tar를 따로 보관하나. BE·AI는 ECR에 이미지가 남지만 FE는 S3에 파일을 뿌리고 끝이라 "그때 빌드한 결과"가 남지 않았다. prod가 재빌드 없이 같은 것을 쓰려면 보관소가 필요했다. (YMC-399)

3. prod 배포 수동

infra 레포 Actions의 Deploy prod를 main 브랜치에서 실행한다. 입력은 세 개, 전부 선택이다. 채운 것만 배포하고 순서는 항상 AI → BE → FE다. 승인 단계는 없다. 실행하는 사람이 승인자다.

job하는 일건너뛰는 조건
verify입력한 SHA의 이미지(dev ECR)·tar(산출물 버킷)가 실제로 있는지 확인. 하나라도 없으면 여기서 끝.—
ai-imagedev ECR → prod ECR 복사 (docker pull·tag·push, ARM runner). 이미 있으면 복사 생략.ai_sha 비움
deploy-ai ×3서비스 3개에 동시에 새 revision 배포, 안정화 대기.같음
be-image / deploy-be위와 같은 방식, backend 1개.be_sha 비움, 또는 AI 실패
deploy-fetar 다운로드 → asset sync → index.html 마지막에 교체 → CloudFront 무효화.fe_sha 비움, 또는 앞 단계 실패

2026-10-01 실제 실행 (셋 다 입력)

총 19분. 막대 길이는 실제 소요 시간에 비례한다.

시간의 대부분은 ECS 안정화 대기다. 새 태스크가 뜨고 헬스체크를 통과할 때까지 워크플로가 기다린다. 워크플로가 느린 게 아니라 ECS 설정(헬스체크 간격, 최소 healthy 비율)의 영역이다.

롤백

전용 워크플로가 없다. 같은 워크플로에 이전 SHA를 넣으면 된다. 이미지가 prod ECR에 이미 있으면 복사를 건너뛰고 revision만 새로 등록한다. BE는 Flyway가 기동 시 돌기 때문에 마이그레이션이 expand/contract를 지켰을 때만 되돌릴 수 있다.

4. OIDC: 워크플로가 AWS에 들어가는 방법 인증

워크플로는 GitHub 서버에서 돌면서 AWS의 ECR·ECS·S3를 조작해야 한다. 예전 방식은 AWS 액세스 키를 발급해 GitHub Secrets에 넣는 것인데, 영구 비밀번호라 유출되면 끝이고 주기적으로 바꿔야 한다. OIDC는 저장된 비밀번호 없이 매 실행마다 임시 자격을 받는 방식이다.

아래 단계를 누르면 그림의 해당 화살표가 강조된다.

GitHub Actions 워크플로 GitHub 토큰 발급소 AWS STS AWS 자원 1 토큰 달라 2 서명된 토큰 (repo·branch 기재) 3 이 토큰으로 Role X 맡게 해달라 4 서명 검증 (provider) 5 신뢰 조건 통과 → 임시 자격 (1시간) 6 임시 자격으로 ECR·ECS·S3 호출 (권한 정책 범위 안에서)
  1. 1
    워크플로가 GitHub에 토큰을 요청한다
    워크플로 파일의 permissions: id-token: write가 이 요청을 허용한다.
  2. 2
    GitHub가 서명된 토큰을 준다
    토큰 안에 "이 실행은 repo:team-ymc/infra:ref:refs/heads/main에서 왔다"가 적혀 있고 GitHub의 서명이 붙어 있다. 위조하면 서명이 깨진다.
  3. 3
    워크플로가 AWS에 Role을 맡겠다고 한다
    aws-actions/configure-aws-credentials가 토큰과 Role ARN을 STS에 보낸다.
  4. 4
    AWS가 서명을 검증한다
    계정에 등록된 OIDC provider가 "GitHub의 서명을 믿는다"는 설정이다. 발급처 URL마다 하나만 등록할 수 있다.
  5. 5
    Role의 신뢰 조건과 맞으면 임시 자격을 준다
    Role의 신뢰 정책에 "infra 레포 main 브랜치만"이 적혀 있다. app 레포에서 온 토큰으로는 이 Role을 못 맡는다. 자격은 1시간 뒤 만료된다.
  6. 6
    임시 자격으로 AWS를 조작한다
    Role의 권한 정책에 적힌 것만 된다. prod 배포 Role은 dev ECR 읽기, prod ECR 쓰기, prod ECS 갱신, 버킷, CloudFront 무효화까지다.

provider와 Role의 역할 분담

provider 발급처 신뢰

  • "token.actions.githubusercontent.com의 서명을 믿는다"
  • 계정에 하나. dev·prod가 공유
  • bootstrap Terraform이 소유

Role 직책

  • 신뢰 정책: 누가 맡을 수 있나 (레포·브랜치)
  • 권한 정책: 맡으면 뭘 할 수 있나
  • 용도마다 하나. dev app, dev ai, prod deploy
Role맡을 수 있는 곳할 수 있는 것
papertutor-dev-app-deployteam-ymc/app maindev ECR backend 쓰기, dev BE 배포, dev FE 버킷, 산출물 버킷 fe/* 쓰기
papertutor-dev-ai-deployteam-ymc/ai maindev ECR ai 쓰기, dev AI 서비스 3개 배포
papertutor-prod-deployteam-ymc/infra maindev ECR 읽기, prod ECR 쓰기, prod ECS 4개 갱신, PassRole, 산출물 버킷 읽기, prod FE 버킷, CloudFront 무효화

왜 prod Role을 infra 레포에 묶었나. app·ai 레포 코드가 아무리 바뀌어도 prod에는 손댈 수 없다. prod를 바꾸는 건 infra main에서 사람이 실행한 워크플로뿐이다.

5. Terraform 구성과 state

Terraform은 "이런 자원이 있어야 한다"는 코드와, "내가 만든 자원이 AWS에서 어떤 ID를 가졌나"를 적은 장부(state)로 동작한다. 코드에 있고 장부에 없으면 만들고, 코드에 없고 장부에 있으면 지운다. 이 마지막 줄이 위험한 지점이다.

infra에는 묶음(root)이 세 개 있다. OIDC provider는 원래 dev 묶음에 있었는데, prod도 같은 provider가 필요해서 공용 자리인 bootstrap으로 옮겼다.

bootstrap

장부: 로컬 파일 (사용자 PC)
  • Terraform 장부 S3 버킷
  • FE 산출물 버킷

dev

장부: S3 papertutor/dev/…
  • VPC·ECS·RDS·ALB… dev 전부
  • GitHub OIDC provider
  • dev app·ai 배포 Role

prod

장부: S3 papertutor/prod/…
  • VPC·ECS·RDS·ALB… prod 전부

AWS는 그대로, 장부만 옮기기

코드에서 provider 블록을 dev에서 빼고 bootstrap에 넣은 뒤 그냥 apply하면, dev는 "코드에 없다"며 provider를 지우고 bootstrap은 "새로 만든다"며 실패한다. 그 순간 dev 배포가 끊긴다. 그래서 장부만 직접 고쳤다.

순서명령기대 결과
1bootstrap: terraform importbootstrap 장부에 기존 provider 등록. AWS 변화 없음
2bootstrap: terraform plan태그만 1건 변경 (dev 태그 → bootstrap 태그)
3dev: terraform state rmdev 장부에서 기록만 삭제. AWS 변화 없음
4dev: terraform planNo changes
5bootstrap: terraform apply태그 갱신
6prod: terraform applyRole·정책 2개 추가, 기존 자원 변경 없음

import를 먼저 하는 이유는 "어느 장부에도 없는 순간"을 만들지 않기 위해서다. 잠깐 두 장부에 같이 있는 건 안전하지만, 어디에도 없으면 실수로 apply했을 때 새로 만들려다 실패한다.

6. 올릴 SHA는 어떻게 고르나

산출물 이름은 main에 push된 커밋의 SHA다. 우리는 PR을 merge 커밋으로 합치기 때문에, 파일을 실제로 고친 커밋과 main에 push된 커밋이 다르다.

27b0609 6c8b2f5 10060c3 main PR 브랜치 fe/ 파일을 고친 커밋 · 산출물 없음 main에 push된 merge 커밋 · 산출물 있음

git log -1 -- fe/는 왼쪽 위 커밋을 돌려주고, 그 이름의 tar는 없다. 그래서 runbook은 git 명령 대신 app·ai 레포 Actions의 dev 배포 실행 이력에서 성공한 실행의 커밋을 고르라고 안내한다. 산출물 버킷의 tar 이름이나 dev ECR 태그를 직접 봐도 같은 답이다. 없는 SHA를 넣어도 verify가 걸러 준다.

7. 오늘 배운 것

FE만 올리면 생기는 일

첫 시나리오로 FE만 최신(10060c3)으로 올렸더니 실패한 논문에 재시도 버튼이 없었다.

FE 10060c3 + BE 195e8e6

FE
failReason === 'PROCESSING_FAILED' 이면 버튼
BE 응답
failReason 필드 없음 → undefined
결과
"실패"만 표시, 버튼 없음

FE 10060c3 + BE 10060c3

FE
같음
BE 응답
failReason: 'PROCESSING_FAILED'
결과
재시도 버튼, 실화면 확인

버그가 아니라 세대 불일치다. BE·FE는 API 응답 필드를 같이 바꾸는 일이 많으니 같은 SHA로 함께 올리는 것을 기본으로 runbook에 적었다.

prod에 지금 뭐가 있는지 보는 법

대상어디서지금 값
BE·AIECS 서비스 → task definition → 이미지 태그BE 10060c3 · AI 94b5037
FES3에는 SHA가 안 남는다. infra Actions의 Deploy prod summary가 기록10060c3

파킹