🎯GitHub Actions로 모노레포 Lerna 프로젝트 배포 자동화

Yarn workspace + Lerna + GitHub Actions + S3 + CloudFront

✅ 들어가며

현재 참여 중인 프로젝트는 Yarn workspace + Lerna 기반 모노레포 구조로 관리되고 있으며,
GitHub Actions를 이용한 CI/CD 자동화 파이프라인이 구성되어 있습니다.

직접 처음부터 작성한 스크립트는 아니지만,
전체적인 구조를 이해하고, 실무에서 발생한 문제를 해결하거나
환경 변수 자동화, 알림 조건 처리 등 일부 로직을 톺아보고 개선·확장했습니다.

이 글에서는 이 CI/CD 파이프라인의 구조와 작동 방식, 그리고 제가 이해한 포인트를 공유하려 합니다.

📦 프로젝트 구조

root
├── packages
│   ├── admin
│   ├── common
│   ├── design-system
│   └── ...
├── .github
│   └── workflows
│       └── deploy.yml

⚙️ 모노레포 패키지별 빌드 전략

Lerna의 --scope 옵션을 사용하여, 병합되는 release-* 브랜치에 따라 해당 패키지만 빌드되도록 구성했습니다.

run: yarn lerna run build:prod --scope=@fe/${{ steps.extract.outputs.PACKAGE_NAME }}

PACKAGE_NAME은 브랜치명에서 자동 추출
release-{package_name} → PACKAGE_NAME

🌐 환경 변수 자동 생성

GitHub Actions에서 브랜치명을 기준으로 production / stage 환경을 판단하고, 각 환경에 맞는 secret 값을 .env 파일로 작성합니다.

 echo "PACKAGE_NAME=$(echo ${{ github.ref_name }} | cut -d '-' -f2)" >> $GITHUB_OUTPUT
 
if [[ ${{ github.ref_name }} == master ]]; then
  echo "env=production" >> $GITHUB_OUTPUT
else
  echo "env=stage" >> $GITHUB_OUTPUT
fi

🚀 배포: S3 + CloudFront

 run: aws s3 sync ${{ steps.extract.outputs.PACKAGE_NAME }}/dist s3://{PACKAGE_NAME}-prod
- run: aws cloudfront create-invalidation --paths "/*"

release-* 브랜치는 stage로 master 병합 시, production으로 배포
배포 후 CloudFront 캐시 무효화까지 자동 처리하여 즉각 변경이 반영되도록 처리

🔔 Slack 알림 연동

- if: failure()
  uses: ./.github/actions/slack-notify
  with:
    slack_incoming_url: ${{ secrets.SLACK_INCOMING_URL }}

- if: success()
  uses: ./.github/actions/slack-notify
  with:
    status: success

성공/실패에 따라 슬랙으로 알림을 보냅니다.
실패 시에는 빌드 로그를 함께 확인할 수 있도록 설정할 수도 있습니다.

🧹 Release 브랜치 자동 삭제

if [[ "$BRANCH_NAME" == release-* ]]; then
  git push origin --delete $BRANCH_NAME

release-* 브랜치가 master에 병합되면 자동으로 삭제되어
브랜치 정리를 수동으로 하지 않아도 됩니다.

🤔 아쉬운 점

브랜치명에 의존하는 환경 및 패키지명 파악

echo "PACKAGE_NAME=$(echo ${{ github.ref_name }} | cut -d '-' -f2)" >> $GITHUB_OUTPUT

항상 release-*-* 형태의 브랜치명을 고수해야 CI/CD가 동작합니다.
브랜치명이 release로 시작하면 stage 환경,master이면 prod 환경.
*-*의 조합은 패키지명

그렇지만 실수(?)로 오타가 생길 수도 있고, 네이밍 컨벤션 변경을 고려할때 CI/CD도 수정이 필요하게 됩니다. 실제로 업무 중 급한 일이 있어 해당 컨벤션명을 따르지 않은 브랜치를 배포한 적이 있었고 배포가 실패해서 당황했던 적이 있었습니다.

그럼 어떻게 ?!
1. github PR Label 활용하기
현재 PROD-release, DEV-release 라는 태그를 쓰고 있습니다.
하나는 master 병합용 release브랜치 PR 태그
다른 하나는 develop 병합용 relese 브랜치 PR 태그 입니다.
git action에서도 이 라벨 태그를 가져올 수 있다고 하니 이걸 기준으로 환경변수 설정을 한다면 어느 브랜치 컨벤션에서도 문제가 없을 것 같습니다!

2. lerna changed
패키지명 같은 경우는 lerna에서 변경을 감지할 수 있어서 (lerna changed)
꼭 브랜치명에 패키지명을 명시하지 않아도 알아서 변경이 있는 패키지를 빌드하게 할 수 있다고 합니다.

✅ 마무리하며

현재 모노레포 구조에서 CI/CD가 어떻게 구성되고 관리되는지를 조금이나마 이해할 수 있었습니다.
초기에는 어려웠지만 빌드, 배포, 캐시 무효화, slack 알림, 브랜치 정리까지의 과정을 온전히 이해할 수 있었고 아쉬운 점도 발견할 수 있었습니다. 아쉬운 점은 지금까지 유지되어온 컨벤션을 바꿀 필요가 없어 큰 문제없으나, 추후에 시간이 된다면 꼭 개선해보고 싶은 부분입니다 :D