GitHub Actions로 FastAPI Docker 이미지 AWS ECR에 자동 배포하기

 개요

이번 글에서는 GitHub Actions를 활용해 FastAPI 프로젝트를 AWS ECR에 자동으로 Docker 이미지로 빌드 & 푸시하는 전체 과정을 소개합니다.

CI/CD 파이프라인을 처음 구성하는 분들이라면, 이 글을 따라 하면서 다음을 배울 수 있습니다:

• FastAPI 프로젝트에 Docker 적용하기
• AWS ECR에 리포지터리 만들기
• GitHub Secrets 설정
• GitHub Actions Workflow 구성하기

---

 1. FastAPI 프로젝트 생성

mkdir fastapi-app && cd fastapi-app
python -m venv venv
source venv/bin/activate
pip install fastapi uvicorn

📄 app/main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "Hello from FastAPI!"}

📄 requirements.txt

fastapi
uvicorn[standard]

---

 2. Dockerfile 작성

📄 Dockerfile

FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY ./app /app

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "80"]

---

 3. AWS ECR 리포지터리 생성

aws ecr create-repository --repository-name fastapi-demo

생성된 ECR 리포지터리 주소는 다음과 같은 형태입니다:

[계정ID].dkr.ecr.[리전].amazonaws.com/fastapi-demo

예시:

123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/fastapi-demo

---

 4. GitHub Secrets 등록

GitHub 레포지토리 → Settings > Secrets and variables > Actions에서 다음 값 등록:

 

이름	설명
AWS_ACCESS_KEY_ID	AWS IAM 사용자 Access Key
AWS_SECRET_ACCESS_KEY	Secret Access Key
AWS_REGION	ex) ap-northeast-2
ECR_REGISTRY	ex) 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com
ECR_REPOSITORY	ex) fastapi-demo

 

---

 5. GitHub Actions Workflow 구성

📄 .github/workflows/deploy.yml

name: Deploy to AWS ECR

on:
  push:
    branches:
      - main  # main 브랜치에 push될 때 실행

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout code
      uses: actions/checkout@v4

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v3
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: ${{ secrets.AWS_REGION }}

    - name: Login to Amazon ECR
      id: login-ecr
      uses: aws-actions/amazon-ecr-login@v2

    - name: Build, tag, and push image to ECR
      env:
        ECR_REGISTRY: ${{ secrets.ECR_REGISTRY }}
        ECR_REPOSITORY: ${{ secrets.ECR_REPOSITORY }}
      run: |
        IMAGE_TAG=${{ github.sha }}
        docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
        docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG

    - name: Print Image URI
      run: |
        echo " Image pushed to: ${{ secrets.ECR_REGISTRY }}/${{ secrets.ECR_REPOSITORY }}:${{ github.sha }}"

---

 6. Push 후 자동 배포 확인

코드를 main 브랜치에 push 하면 GitHub Actions가 실행되고,
이미지가 ECR에 자동으로 업로드됩니다.

예시 로그:

 Image pushed to: 123456789012.dkr.ecr.ap-northeast-2.amazonaws.com/fastapi-demo:f2d9cd...

ECR 콘솔에서 확인하면 해당 이미지가 등록되어 있을 것입니다.

---

 마무리

이제 FastAPI로 작성한 코드를 GitHub에 push만 하면 자동으로 AWS ECR에 Docker 이미지로 배포됩니다.
다음 단계에서는 이 이미지를 AWS EKS에 자동 배포하거나,
ArgoCD 또는 Helm과 연동해 GitOps 형태로 확장할 수도 있습니다.