ECS Preview 연동

ECS Preview 연동이란?

ECS Preview 연동은 Vercel을 쓰지 않는 프로젝트에서도 AI Fix PR을 preview URL로 검수할 수 있게 하는 기능입니다.

Vercel은 Git push만으로 preview 배포를 만들지만, ECS/Fargate 프로젝트는 각 팀의 VPC, ALB, Route53, IAM, task definition이 모두 다릅니다. 그래서 QA Note는 AWS 리소스를 직접 만들지 않고, 리포에 있는 GitHub Actions workflow를 표준 계약으로 호출합니다.

동작 방식

AI Fix가 qanote/issue-N 브랜치에 수정사항을 push합니다.
QA Note AI Fix workflow가 구현 완료 후 ECS preview workflow를 workflow_dispatch로 실행합니다.
ECS preview workflow가 컨테이너, target group, listener rule, DNS 등을 만들거나 갱신합니다.
workflow가 GitHub deployment status에 environment_url을 발행합니다.
QA Note가 GitHub webhook을 받아 이슈의 Preview URL을 갱신합니다.

설정

프로젝트 설정 → 연동 → ECS Preview 연결에서 아래 값을 저장합니다.

항목	설명
Workflow file	`.github/workflows/` 아래 preview workflow 파일명. 기본값은 `qanote-ecs-preview.yml`
Workflow ref	preview workflow를 실행할 ref. 운영에서는 default branch를 권장합니다
Preview URL pattern	운영자가 식별하기 위한 URL 패턴 메모

Vercel Preview와 ECS Preview는 같은 프로젝트에서 동시에 켤 수 없습니다. 한 프로젝트는 하나의 preview provider만 선택해야 cleanup, retry, approve 신호가 하나의 경로로 수렴합니다.

ECS Preview를 켜면 AI Fix implement 단계에서 아래 입력으로 workflow가 호출됩니다.

yaml

action: deploy
branch: qanote/issue-N
ai_run_id: <QA Note run id>
callback_url: <QA Note callback URL>
commit_sha: <implementation commit SHA>

Preview 정리 화면에서 삭제 또는 머지를 실행하면 QA Note는 같은 workflow에 아래 입력으로 정리 요청을 보냅니다.

yaml

action: destroy
branch: qanote/issue-N
ai_run_id: <QA Note run id>
callback_url: <QA Note callback URL>

AWS 권한 설정 단계

ECS Preview의 성패는 대부분 IAM 권한에서 결정됩니다. 아래 순서로 제한된 권한을 먼저 만들고, workflow를 실행하며 누락 권한을 좁게 추가하세요.

1. GitHub Actions가 사용할 AWS principal 만들기

권장 방식은 GitHub OIDC입니다.

AWS IAM에서 GitHub OIDC provider token.actions.githubusercontent.com을 등록합니다.
QA Note preview workflow가 있는 repository만 assume할 수 있는 role을 만듭니다.
trust policy의 aud는 sts.amazonaws.com으로 제한합니다.
sub는 repo:<owner>/<repo>:ref:refs/heads/<default-branch> 또는 운영 방식에 맞는 ref로 제한합니다.
장기 access key를 쓴다면 별도 IAM user를 만들고 GitHub secret에 저장하되, 같은 최소 권한 정책만 붙입니다.

2. ECS와 task definition 권한

workflow role에는 preview cluster/service 범위로 아래 권한이 필요합니다.

ecs:RegisterTaskDefinition
ecs:DescribeClusters, ecs:DescribeServices, ecs:DescribeTaskDefinition, ecs:DescribeTasks
ecs:CreateService, ecs:UpdateService, ecs:DeleteService
ecs:TagResource, ecs:UntagResource

Task execution role과 task role을 workflow가 task definition에 넣어야 하므로 iam:PassRole도 필요합니다. 이 권한은 반드시 대상 role ARN과 iam:PassedToService = ecs-tasks.amazonaws.com 조건으로 제한하세요.

3. ECR 권한

workflow가 이미지를 빌드해 ECR에 push한다면 아래 권한이 필요합니다.

ecr:GetAuthorizationToken
ecr:BatchCheckLayerAvailability
ecr:InitiateLayerUpload
ecr:UploadLayerPart
ecr:CompleteLayerUpload
ecr:PutImage
ecr:BatchGetImage

repository ARN은 preview 이미지가 올라가는 ECR repository로 제한하고, lifecycle policy를 설정해 오래된 preview image를 자동 삭제하세요.

4. ALB target group과 listener rule 권한

preview URL을 ALB 뒤에 붙이는 구조라면 최초 생성뿐 아니라 rerun에서 수정 권한이 필요합니다.

elasticloadbalancing:CreateTargetGroup, DeleteTargetGroup, DescribeTargetGroups
elasticloadbalancing:RegisterTargets, DeregisterTargets, DescribeTargetHealth
elasticloadbalancing:CreateRule, ModifyRule, DeleteRule, DescribeRules
elasticloadbalancing:DescribeListeners, DescribeLoadBalancers

KIAF 테스트에서는 최초 생성 후 rerun에서 ModifyRule이 없어 실패했습니다. create만 주면 첫 배포는 통과하고 재배포가 실패할 수 있습니다.

5. Route53 권한

preview subdomain을 자동으로 만들려면 hosted zone 단위로 아래 권한을 부여합니다.

route53:ChangeResourceRecordSets
route53:ListResourceRecordSets
route53:GetHostedZone

가능하면 route53:ChangeResourceRecordSets는 preview zone 또는 특정 hosted zone ARN에만 묶고, workflow에서 생성하는 record prefix를 issue-*-preview처럼 고정하세요.

6. CloudWatch Logs 권한

Fargate task가 로그를 쓰려면 log group/stream 권한이 필요합니다.

logs:CreateLogGroup 또는 사전 생성된 log group
logs:CreateLogStream
logs:PutLogEvents
logs:DescribeLogGroups, logs:DescribeLogStreams

KIAF 테스트에서는 log group이 없어 task 시작이 실패했습니다. 운영에서는 /ecs/<preview-task-family> log group을 미리 만들고 retention을 7~14일로 두는 방식을 권장합니다.

7. Cleanup 권한 확인

Preview 삭제와 머지 후 정리를 위해 deploy 권한과 별도로 delete 권한을 빠뜨리지 마세요.

ecs:UpdateService로 desired count를 0으로 낮춤
ecs:DeleteService
elasticloadbalancing:DeleteRule
elasticloadbalancing:DeleteTargetGroup
route53:ChangeResourceRecordSets로 preview record 삭제

Preview workflow 요구사항

리포의 preview workflow는 최소한 아래 workflow_dispatch inputs를 받아야 합니다.

yaml

on:
  workflow_dispatch:
    inputs:
      action:
        required: true
        type: string
      branch:
        required: true
        type: string
      ai_run_id:
        required: false
        type: string
      callback_url:
        required: false
        type: string
      commit_sha:
        required: false
        type: string

preview가 준비되면 GitHub deployment status를 success로 만들고 environment_url 또는 target_url에 preview URL을 넣어야 합니다.

json

{
  "state": "success",
  "target_url": "https://issue-1-preview.example.com",
  "environment_url": "https://issue-1-preview.example.com",
  "auto_inactive": false
}

실패하면 failure 또는 error 상태와 description을 발행하세요. QA Note는 해당 run을 실패 처리하고 PR 상태를 갱신합니다.

운영 체크리스트

Route53 hosted zone에 record 변경 권한이 있어야 합니다.
ALB listener rule은 생성뿐 아니라 rerun에서 ModifyRule 권한이 필요합니다.
task execution role이 log group을 만들지 못하는 경우 preview log group을 미리 생성하세요.
preview마다 Fargate task가 실행되므로 cleanup 정책을 반드시 둡니다.
ECR image lifecycle policy와 CloudWatch Logs retention을 설정합니다.