TIL - 20260806

juni·2026년 8월 6일

목록 보기

424/468

0806 인프라/DevOps 운영 심화 (5/N): GitHub Actions CI/CD 기본

✅ 1. CI/CD란 무엇인가?

CI/CD는 코드 변경 후 검증, 빌드, 배포 과정을 자동화하는 개발 운영 방식입니다.
CI는 Continuous Integration, 즉 지속적 통합입니다.
CD는 Continuous Delivery 또는 Continuous Deployment, 즉 지속적 전달/배포입니다.
실무에서는 “코드를 push하면 자동으로 lint/test/build를 돌리고, 조건이 맞으면 배포까지 이어지는 흐름”으로 이해하면 됩니다.

코드 수정
  ↓
git push
  ↓
GitHub Actions 실행
  ↓
lint / test / build
  ↓
검증 성공
  ↓
배포 또는 배포 준비

➕ 1-1. CI와 CD 차이

구분	의미	예시
CI	코드가 깨지지 않았는지 자동 검증	lint, test, typecheck, build
CD	검증된 코드를 배포 가능 상태로 만듦	artifact 생성, staging 배포
자동 배포	검증 후 운영까지 자동 배포	main push → 운영 배포

➕ 1-2. 1인 개발자에게도 필요한 이유

로컬에서 검증 명령어를 깜빡하는 실수를 줄일 수 있습니다.
배포 전 최소 품질 기준을 자동으로 확인할 수 있습니다.
새 Mac이나 다른 환경에서도 동일한 검증을 재현할 수 있습니다.
AI IDE/Codex가 수정한 코드도 자동 검증할 수 있습니다.
작업 기록, 배포 이력, 실패 로그가 GitHub에 남습니다.

CI/CD 없이:
로컬에서 build 안 돌리고 배포
환경변수 누락을 늦게 발견
테스트 실패를 운영 배포 후 발견

CI/CD 사용:
push 시 자동 검증
실패 시 배포 중단
로그로 원인 추적 가능

✅ 2. GitHub Actions란 무엇인가?

GitHub Actions는 GitHub 저장소에서 특정 이벤트가 발생했을 때 자동으로 작업을 실행하는 도구입니다.
push, pull request, tag 생성, 수동 실행 같은 이벤트를 기준으로 workflow를 돌릴 수 있습니다.
프론트엔드, 백엔드, 테스트, 배포, 문서 생성, 릴리즈 노트 작성 등에 활용할 수 있습니다.

GitHub Repository
  ↓
.github/workflows/*.yml
  ↓
GitHub Actions Runner
  ↓
정해진 명령어 실행

➕ 2-1. 핵심 구성 요소

구성	의미
Workflow	자동화 작업 전체
Event	workflow 실행 조건
Job	실행 작업 단위
Step	job 안의 개별 단계
Action	재사용 가능한 명령 묶음
Runner	실제 명령어가 실행되는 환경
Secret	민감한 값 저장 공간

➕ 2-2. 파일 위치

.github/
  workflows/
    frontend-ci.yml
    backend-ci.yml
    frontend-deploy.yml
    backend-deploy.yml

workflow 파일은 .github/workflows 안에 둡니다.
YAML 문법을 사용합니다.

✅ 3. GitHub Actions 기본 구조

name: Frontend CI

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  verify:
    runs-on: ubuntu-latest

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

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 24

      - name: Install
        run: npm ci

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm run test:run

      - name: Build
        run: npm run build

➕ 3-1. `name`

name:
GitHub Actions 화면에 표시되는 workflow 이름

➕ 3-2. `on`

on:
workflow가 언제 실행될지 정하는 조건

예:
push
pull_request
workflow_dispatch

➕ 3-3. `jobs`

jobs:
실행할 작업 묶음

예:
verify
deploy
test
build

➕ 3-4. `steps`

steps:
job 안에서 순서대로 실행되는 개별 단계

처음에는 checkout → node setup → install → lint/test/build 흐름만 이해해도 충분합니다.

✅ 4. CI에서 가장 먼저 자동화할 것

처음부터 완벽한 CI/CD를 만들 필요는 없습니다.
가장 먼저 자동화해야 할 것은 배포 전 검증입니다.

➕ 4-1. 프론트엔드 CI

npm run lint
npm run test:run
npm run typecheck
npm run build

➕ 4-2. 백엔드 CI

npm run lint
npm run test
npm run test:e2e
npm run build
prisma generate

➕ 4-3. 공통 검증

의존성 설치 가능 여부
TypeScript 컴파일
환경변수 example 최신 여부
테스트 통과 여부
빌드 성공 여부

CI의 핵심은 “main branch에 깨진 코드가 들어가지 않게 하는 것”입니다.
1인 개발자라도 main은 최대한 안정적으로 유지해야 합니다.

✅ 5. package.json verify 스크립트

CI와 로컬에서 같은 명령어를 쓰면 관리가 편합니다.
verify 스크립트를 만들어두면 GitHub Actions에서도 그대로 실행할 수 있습니다.

{
  "scripts": {
    "lint": "eslint .",
    "test": "vitest",
    "test:run": "vitest run",
    "typecheck": "tsc --noEmit",
    "build": "vite build",
    "verify": "npm run lint && npm run test:run && npm run typecheck && npm run build"
  }
}

➕ 5-1. GitHub Actions에서 사용

- name: Verify
  run: npm run verify

➕ 5-2. 장점

로컬과 CI 검증 기준 통일
workflow 파일 단순화
배포 전 습관화 쉬움
AI에게 실행 기준 설명 쉬움

CI에만 있는 복잡한 검증보다, 로컬에서도 똑같이 돌릴 수 있는 검증이 좋습니다.

✅ 6. npm, pnpm, yarn 설치 차이

프로젝트에서 사용하는 패키지 매니저에 맞춰 CI 명령어를 정해야 합니다.
lock 파일과 설치 명령어가 맞지 않으면 CI에서 문제가 생길 수 있습니다.

패키지 매니저	lock 파일	설치 명령어
npm	`package-lock.json`	`npm ci`
pnpm	`pnpm-lock.yaml`	`pnpm install --frozen-lockfile`
yarn	`yarn.lock`	`yarn install --frozen-lockfile`

➕ 6-1. pnpm 예시

- name: Setup pnpm
  uses: pnpm/action-setup@v4
  with:
    version: 10

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: 24
    cache: 'pnpm'

- name: Install
  run: pnpm install --frozen-lockfile

- name: Verify
  run: pnpm verify

➕ 6-2. 주의할 점

lock 파일과 설치 명령어 맞추기
로컬과 CI Node 버전 맞추기
pnpm workspace면 workspace 기준으로 실행
package-lock과 pnpm-lock을 동시에 쓰지 않기

현재 프로젝트가 pnpm 기반이면 CI도 pnpm 기준으로 맞추는 것이 좋습니다.
lock 파일이 여러 개 있으면 의존성 설치가 꼬일 수 있습니다.

✅ 7. Node 버전 관리

로컬과 CI의 Node 버전이 다르면 빌드 결과가 달라질 수 있습니다.
.nvmrc나 package.json engines로 기준을 정해두면 좋습니다.

➕ 7-1. `.nvmrc`

➕ 7-2. package.json engines

{
  "engines": {
    "node": ">=24 <25",
    "pnpm": ">=10"
  }
}

➕ 7-3. GitHub Actions에서 사용

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version-file: '.nvmrc'
    cache: 'pnpm'

새 Mac 세팅, CI, 배포 서버의 Node 버전 기준은 맞추는 것이 좋습니다.
버전이 다르면 로컬에서는 되는데 CI에서 깨질 수 있습니다.

✅ 8. 환경변수와 GitHub Secrets

CI/CD에서는 API URL, AWS Bucket 이름, CloudFront Distribution ID 같은 값이 필요할 수 있습니다.
민감한 값은 GitHub Secrets에 저장합니다.

➕ 8-1. GitHub Secrets에 넣을 수 있는 값

AWS_ACCESS_KEY_ID
AWS_SECRET_ACCESS_KEY
S3_BUCKET_NAME
CLOUDFRONT_DISTRIBUTION_ID
VITE_API_BASE_URL
DATABASE_URL_FOR_TEST

➕ 8-2. workflow에서 사용

env:
  VITE_API_BASE_URL: ${{ secrets.VITE_API_BASE_URL }}

➕ 8-3. 주의

프론트 VITE_ 값은 빌드 후 브라우저에 노출됨
Secret 값 echo 출력 금지
운영/스테이징 Secret 분리
개인 AWS 키와 회사 배포 키 분리
최소 권한 IAM 사용

GitHub Secrets는 안전하게 보관되지만, 빌드 결과물에 포함되는 프론트 환경변수는 결국 사용자에게 노출됩니다.
Secret 저장소와 프론트 공개 환경변수를 혼동하면 안 됩니다.

✅ 9. GitHub Environments

GitHub Environments를 사용하면 staging, production 배포 환경을 구분할 수 있습니다.
운영 배포 전에 승인 단계를 둘 수도 있습니다.

Environments:
staging
production

➕ 9-1. 장점

환경별 Secret 분리
운영 배포 승인 설정 가능
배포 이력 관리
branch 보호와 연결 가능

➕ 9-2. 예시

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    steps:
      - name: Deploy
        run: echo "Deploy to production"

1인 개발자라도 production environment를 따로 두면 실수 방지에 도움이 됩니다.
운영 배포는 자동 실행보다 수동 승인 또는 수동 실행으로 시작하는 것이 더 안전합니다.

✅ 10. `workflow_dispatch` 수동 실행

운영 배포는 push만으로 자동 실행되게 하는 것보다 수동 실행으로 시작하는 것이 안전할 수 있습니다.
GitHub Actions의 workflow_dispatch를 사용하면 버튼으로 workflow를 실행할 수 있습니다.

name: Frontend Deploy

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Deploy environment'
        required: true
        default: 'staging'
        type: choice
        options:
          - staging
          - production

➕ 10-1. 장점

배포 시점을 직접 선택 가능
main push와 운영 배포 분리
운영 배포 실수 감소
배포 전 QA 후 실행 가능

➕ 10-2. 추천 운영 방식

push/PR:
CI만 실행

staging deploy:
수동 또는 develop branch

production deploy:
수동 실행 + environment 확인

처음 CI/CD를 도입할 때는 운영 자동 배포보다 수동 배포 자동화가 더 현실적입니다.
자동화는 하되, 마지막 승인권은 사람이 갖는 것이 안전합니다.

✅ 11. 프론트엔드 S3 + CloudFront 배포 workflow

0805에서 정리한 S3 + CloudFront 배포를 GitHub Actions로 자동화할 수 있습니다.

name: Frontend Deploy

on:
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production

    env:
      VITE_API_BASE_URL: ${{ secrets.VITE_API_BASE_URL }}

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

      - name: Setup pnpm
        uses: pnpm/action-setup@v4
        with:
          version: 10

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'pnpm'

      - name: Install
        run: pnpm install --frozen-lockfile

      - name: Verify
        run: pnpm verify

      - name: Check build output
        run: |
          grep -R "localhost" dist/ && exit 1 || true

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

      - name: Upload assets
        run: |
          aws s3 sync dist/assets/ s3://${{ secrets.S3_BUCKET_NAME }}/assets/ \
            --cache-control "public, max-age=31536000, immutable"

      - name: Upload index.html
        run: |
          aws s3 cp dist/index.html s3://${{ secrets.S3_BUCKET_NAME }}/index.html \
            --cache-control "no-cache, no-store, must-revalidate" \
            --content-type "text/html"

      - name: Upload rest
        run: |
          aws s3 sync dist/ s3://${{ secrets.S3_BUCKET_NAME }} \
            --exclude "index.html" \
            --exclude "assets/*"

      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id ${{ secrets.CLOUDFRONT_DISTRIBUTION_ID }} \
            --paths "/index.html" "/"

➕ 11-1. 주의

dist 생성 후 grep 실행 순서 확인
VITE_API_BASE_URL이 빌드 전에 주입되는지 확인
S3 bucket과 distribution ID가 production용인지 확인
assets 캐시와 index.html 캐시 구분
배포 후 Smoke Test는 별도 체크

이 workflow는 기본 예시입니다.
실제 프로젝트에서는 앱 경로, 패키지 매니저, monorepo 구조에 맞게 수정해야 합니다.

✅ 12. 백엔드 CI 기본

백엔드는 프론트보다 검증할 요소가 많습니다.
TypeScript 빌드, Prisma generate, unit test, e2e test, lint를 확인해야 합니다.

name: Backend CI

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  verify:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: together
          POSTGRES_PASSWORD: together_test_password
          POSTGRES_DB: together_test
        ports:
          - 5432:5432
        options: >-
          --health-cmd "pg_isready -U together -d together_test"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    env:
      DATABASE_URL: postgresql://together:together_test_password@localhost:5432/together_test?schema=public
      NODE_ENV: test

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

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'npm'

      - name: Install
        run: npm ci

      - name: Prisma Generate
        run: npx prisma generate

      - name: Migrate
        run: npx prisma migrate deploy

      - name: Lint
        run: npm run lint

      - name: Test
        run: npm run test

      - name: Build
        run: npm run build

➕ 12-1. 백엔드 CI에서 중요한 것

테스트용 DB 분리
운영 DATABASE_URL 사용 금지
Prisma generate 실행
migration 검증
환경변수 누락 확인

CI에서 운영 DB를 연결하면 절대 안 됩니다.
테스트용 PostgreSQL service를 띄우거나, 테스트 환경 DB를 따로 써야 합니다.

✅ 13. Prisma와 CI

Prisma 프로젝트에서는 CI에서 prisma generate와 migration 검증을 고려해야 합니다.
DB가 필요한 테스트가 있다면 GitHub Actions service container로 PostgreSQL을 띄울 수 있습니다.

➕ 13-1. Prisma 명령어

npx prisma generate
npx prisma migrate deploy
npm run test
npm run build

➕ 13-2. `migrate deploy`와 `migrate dev` 차이

명령어	용도
`migrate dev`	로컬 개발용, migration 생성/적용
`migrate deploy`	운영/CI용, 이미 생성된 migration 적용

➕ 13-3. CI 기준

CI:
migrate deploy 사용

로컬 개발:
migrate dev 사용

운영:
배포 과정에서 migrate deploy 사용

CI나 운영에서 migrate dev를 쓰는 것은 적절하지 않습니다.
운영 배포에서는 이미 커밋된 migration 파일만 적용해야 합니다.

✅ 14. 테스트용 서비스 컨테이너

GitHub Actions에서는 services를 사용해 PostgreSQL, Redis 같은 테스트용 컨테이너를 띄울 수 있습니다.

➕ 14-1. PostgreSQL service

services:
  postgres:
    image: postgres:16
    env:
      POSTGRES_USER: together
      POSTGRES_PASSWORD: together_test_password
      POSTGRES_DB: together_test
    ports:
      - 5432:5432
    options: >-
      --health-cmd "pg_isready -U together -d together_test"
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

➕ 14-2. Redis service

services:
  redis:
    image: redis:7
    ports:
      - 6379:6379
    options: >-
      --health-cmd "redis-cli ping"
      --health-interval 10s
      --health-timeout 5s
      --health-retries 5

➕ 14-3. 주의

서비스 컨테이너는 CI 테스트용
운영 DB/Redis와 무관
테스트 데이터는 매번 새로 생성
health check 없으면 테스트가 너무 빨리 시작될 수 있음

DB가 준비되기 전에 테스트가 실행되면 실패할 수 있습니다.
health check를 넣는 것이 좋습니다.

✅ 15. 백엔드 Docker Image 빌드

백엔드를 Docker로 배포할 계획이라면 CI에서 Docker image를 빌드할 수 있습니다.
처음에는 build 검증만 하고, 나중에 ECR push까지 확장하면 됩니다.

name: Backend Docker Build

on:
  push:
    branches:
      - main

jobs:
  docker-build:
    runs-on: ubuntu-latest

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

      - name: Docker build
        run: docker build -t togethermall-api:${{ github.sha }} .

➕ 15-1. ECR까지 확장

Docker build
  ↓
AWS ECR login
  ↓
docker tag
  ↓
docker push
  ↓
서버에서 pull 후 restart

➕ 15-2. 주의

Dockerfile에 Secret 넣지 않기
.env 파일 COPY 금지
이미지 태그에 github.sha 사용
latest만 의존하지 않기
빌드 캐시와 용량 관리

Docker image에 Secret이 들어가면 위험합니다.
운영 환경변수는 컨테이너 실행 시 주입해야 합니다.

✅ 16. 백엔드 배포 자동화 방식

백엔드 배포 자동화는 프론트 정적 배포보다 더 조심해야 합니다.
서버 프로세스 재시작, migration, 환경변수, 롤백을 모두 고려해야 합니다.

➕ 16-1. PM2 서버 배포 방식

GitHub Actions
  ↓
SSH 접속
  ↓
git pull 또는 artifact upload
  ↓
pnpm install
  ↓
prisma migrate deploy
  ↓
pnpm build
  ↓
pm2 restart
  ↓
health check

➕ 16-2. Docker 서버 배포 방식

GitHub Actions
  ↓
Docker image build
  ↓
ECR push
  ↓
서버 SSH
  ↓
docker compose pull
  ↓
docker compose up -d
  ↓
health check

➕ 16-3. 주의

migration 실패 시 배포 중단
health check 실패 시 롤백 기준 필요
운영 env 직접 출력 금지
서버 SSH key 관리 주의
배포 중 downtime 고려

백엔드 자동 배포는 반드시 staging에서 먼저 검증하는 것이 좋습니다.
처음에는 CI만 자동화하고, 배포는 수동 스크립트로 시작해도 충분합니다.

✅ 17. Monorepo에서 GitHub Actions

프론트, 어드민, 백엔드가 하나의 레포에 함께 있다면 monorepo 기준으로 workflow를 나눠야 합니다.
변경된 경로에 따라 필요한 workflow만 실행할 수 있습니다.

➕ 17-1. 예시 구조

apps/
  front/
  admin/
  back/
packages/
  ui/
  shared/

➕ 17-2. paths 조건

on:
  push:
    branches:
      - main
    paths:
      - 'apps/front/**'
      - 'packages/ui/**'
      - 'pnpm-lock.yaml'
      - '.github/workflows/front-ci.yml'

➕ 17-3. workspace 실행 예시

- name: Frontend Verify
  run: pnpm --filter front verify

- name: Admin Verify
  run: pnpm --filter admin verify

- name: Backend Verify
  run: pnpm --filter back verify

monorepo에서는 공통 패키지 변경이 여러 앱에 영향을 줄 수 있습니다.
packages/ui를 바꾸면 front/admin 모두 검증하는 것이 안전합니다.

✅ 18. 캐시로 CI 속도 개선

GitHub Actions는 매번 새 runner에서 실행됩니다.
의존성 설치 시간을 줄이려면 cache를 사용할 수 있습니다.

➕ 18-1. npm cache

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: 24
    cache: 'npm'

➕ 18-2. pnpm cache

- name: Setup Node
  uses: actions/setup-node@v4
  with:
    node-version: 24
    cache: 'pnpm'

➕ 18-3. 주의

캐시가 깨졌을 때 재실행 필요
lock 파일 기준으로 캐시 invalidation
너무 복잡한 캐시 설정은 유지보수 부담

처음에는 actions/setup-node의 기본 cache 옵션만 써도 충분합니다.
빌드 속도가 크게 문제될 때만 추가 최적화를 고민하면 됩니다.

✅ 19. Branch 전략과 CI

CI/CD는 branch 전략과 함께 설계해야 합니다.
개인 프로젝트라도 main branch 기준을 정하는 것이 좋습니다.

➕ 19-1. 단순 전략

main:
운영 배포 가능 상태

feature/*:
기능 작업

hotfix/*:
긴급 수정

➕ 19-2. workflow 기준

feature branch push:
CI 실행

pull request:
CI 실행 + 리뷰

main push:
CI 실행 + staging 또는 production deploy 후보

tag:
릴리즈 배포 후보

➕ 19-3. 1인 개발자 추천

혼자라도 main 직접 push 전:
npm run verify

중요 기능:
feature branch 사용

운영 배포:
main 기준 수동 deploy workflow 실행

main branch는 항상 배포 가능한 상태로 유지하는 것이 좋습니다.
무조건 복잡한 Git flow가 필요한 것은 아닙니다.

✅ 20. Pull Request 없이도 CI가 필요한가?

1인 개발자는 PR 없이 main에 바로 push할 때가 많습니다.
그래도 CI는 의미가 있습니다.

➕ 20-1. 이유

push 후 자동 검증
실패 로그 기록
배포 전 안정성 확인
AI 수정 코드 검증
새 환경에서 빌드되는지 확인

➕ 20-2. 추천 방식

작은 수정:
main push + CI 확인

큰 기능:
feature branch → PR 생성 → CI 확인 → merge

배포:
workflow_dispatch로 수동 배포

혼자라도 큰 변경은 PR을 만들면 diff 확인과 CI 결과 관리가 편합니다.
PR은 팀 협업 도구이기도 하지만, 혼자 쓰는 작업 검토 도구로도 좋습니다.

✅ 21. 실패한 GitHub Actions 읽는 법

CI가 실패하면 실패 로그를 보고 원인을 좁혀야 합니다.
대충 다시 실행만 반복하면 문제가 해결되지 않습니다.

➕ 21-1. 확인 순서

1. 어떤 job이 실패했는가?
2. 어떤 step에서 실패했는가?
3. exit code가 무엇인가?
4. 에러 메시지가 lint/test/build 중 어디에 속하는가?
5. 로컬에서도 재현되는가?
6. 환경변수 누락인가?
7. Node/pnpm 버전 차이인가?

➕ 21-2. 자주 나는 실패

lock 파일 불일치
Node 버전 차이
환경변수 누락
테스트가 시간/순서에 의존
DB service 준비 전 테스트 실행
TypeScript strict 에러
운영 Secret 미설정

➕ 21-3. 좋은 대응

실패 로그 복사
로컬에서 같은 명령어 실행
환경변수 차이 확인
수정 후 다시 push
실패 원인 작업 로그에 기록

CI 실패는 귀찮은 것이 아니라 운영 전에 문제를 잡아준 신호입니다.
실패 원인을 기록해두면 다음에 같은 실수를 줄일 수 있습니다.

✅ 22. CI/CD에서 절대 하면 안 되는 것

➕ 22-1. Secret 출력

- name: Debug Secret
  run: echo ${{ secrets.AWS_SECRET_ACCESS_KEY }}

이런 식으로 Secret을 출력하면 안 됩니다.

➕ 22-2. 운영 DB로 테스트

CI DATABASE_URL:
운영 RDS 주소

결과:
테스트가 운영 DB를 수정할 수 있음

➕ 22-3. 모든 AWS 권한 부여

GitHub Actions IAM:
AdministratorAccess

결과:
키 유출 시 전체 AWS 피해 가능

➕ 22-4. 무조건 운영 자동 배포

main push:
즉시 운영 배포

위험:
실수 push가 바로 장애로 이어질 수 있음

자동화는 강력할수록 방어장치가 필요합니다.
특히 운영 배포, DB migration, Secret, AWS 권한은 신중해야 합니다.

✅ 23. 배포 후 Health Check

배포 자동화에서는 배포 후 서비스가 살아 있는지 확인해야 합니다.
프론트는 운영 URL 접속, 백엔드는 health endpoint를 확인할 수 있습니다.

➕ 23-1. 백엔드 Health Check

curl -f https://api.example.com/health

-f 옵션은 HTTP 오류 상태면 실패 처리합니다.

➕ 23-2. workflow 예시

- name: Health Check
  run: |
    curl -f https://api.example.com/health

➕ 23-3. Health endpoint에 포함할 것

서버 프로세스 정상 여부
DB 연결 여부
Redis 연결 여부
필수 외부 서비스 상태
버전 정보

단순히 서버가 켜져 있는 것과 실제 서비스가 정상인 것은 다릅니다.
최소 DB 연결 정도는 확인할 수 있으면 좋습니다.

✅ 24. 알림 설정

CI/CD 실패를 바로 알 수 있어야 합니다.
GitHub 기본 알림 외에 Slack, Discord, 이메일, 카카오워크 등을 연결할 수 있습니다.

➕ 24-1. 알림이 필요한 상황

CI 실패
배포 실패
운영 배포 성공
Health check 실패
테스트 실패
보안 스캔 실패

➕ 24-2. 처음에는 단순하게

GitHub Actions 실패 알림 확인
이메일/GitHub notification 활성화
중요 workflow만 외부 알림 연결

처음부터 복잡한 알림 시스템은 필요 없습니다.
배포 실패와 운영 Health Check 실패만 잘 알아도 충분히 도움이 됩니다.

✅ 25. 1인 개발자 기준 도입 순서

➕ 25-1. 1단계: 로컬 verify 정리

package.json에 verify 추가
lint/test/typecheck/build 통합
로컬에서 배포 전 실행 습관화

➕ 25-2. 2단계: GitHub Actions CI

push/PR 시 verify 실행
Node/pnpm 버전 고정
캐시 설정
실패 로그 확인 습관

➕ 25-3. 3단계: 프론트 수동 배포 자동화

workflow_dispatch로 배포 실행
S3 업로드
CloudFront invalidation
운영 env 확인
배포 후 Smoke Test 수동 확인

➕ 25-4. 4단계: 백엔드 CI

PostgreSQL service container
Prisma generate/migrate deploy
unit/e2e test
build

➕ 25-5. 5단계: 백엔드 배포 자동화

staging 배포 자동화
health check
migration 자동화
rollback 기준
production은 수동 승인

지금 바로 모든 걸 자동화하려고 하지 않아도 됩니다.
먼저 CI로 깨진 코드 방지, 그다음 프론트 배포 자동화, 마지막에 백엔드 배포 자동화가 현실적입니다.

✅ 26. GitHub Actions 문서화

CI/CD는 문서화해야 나중에 다시 고치기 쉽습니다.
어떤 workflow가 언제 실행되고, 실패하면 무엇을 봐야 하는지 정리해야 합니다.

➕ 26-1. 문서에 넣을 것

workflow 파일 목록
실행 조건
필요한 Secrets
환경별 배포 방식
로컬에서 같은 검증 실행 방법
실패 시 확인 순서
배포 후 Smoke Test
롤백 기준

➕ 26-2. 예시

# GitHub Actions 운영 문서

## Workflows
- `frontend-ci.yml`: push/PR 시 프론트 검증
- `frontend-deploy.yml`: 수동 실행으로 프론트 운영 배포
- `backend-ci.yml`: push/PR 시 백엔드 검증

## Required Secrets
- `AWS_ACCESS_KEY_ID`
- `AWS_SECRET_ACCESS_KEY`
- `S3_BUCKET_NAME`
- `CLOUDFRONT_DISTRIBUTION_ID`
- `VITE_API_BASE_URL`

## Local Verify
```bash
pnpm verify

Deploy

main branch 최신 확인
운영 QA 확인
GitHub Actions에서 Frontend Deploy 수동 실행
배포 완료 후 Smoke Test 수행

Failure Check

실패 job/step 확인
로그 확인
로컬에서 같은 명령 실행
환경변수/Secret 누락 확인


*   문서가 있으면 CI/CD가 “한 번 만든 설정”이 아니라 운영 가능한 체계가 됩니다.
*   AI에게 workflow 수정을 맡길 때도 기준 자료로 활용할 수 있습니다.

---

### ✅ 27. AI에게 GitHub Actions 문제를 물어볼 때 좋은 질문법

*   GitHub Actions 문제는 workflow 파일, 실패 step, 로그, 패키지 매니저, Node 버전이 있어야 정확히 분석할 수 있습니다.

#### ➕ 27-1. 좋은 질문 예시

```txt id="ai-github-actions-question"
GitHub Actions에서 React + Vite + pnpm 프로젝트 CI가 실패하고 있어.

상황:
1. Node 버전은 로컬에서 24 사용
2. pnpm 버전은 10 사용
3. lock 파일은 pnpm-lock.yaml
4. workflow는 아래와 같음
5. 실패한 step은 Install 또는 Build임
6. 에러 로그는 아래와 같음
7. 로컬에서는 pnpm verify가 성공함

요청:
- 가장 가능성 높은 원인
- workflow 수정안
- Node/pnpm/cache 설정 확인
- 환경변수 누락 가능성
- lock 파일 문제 확인
- 재발 방지 체크리스트
를 순서대로 정리해줘.

➕ 27-2. AI 답변 검증 기준

패키지 매니저와 lock 파일을 맞추는가?
로컬 Node 버전과 CI Node 버전을 비교하는가?
실패한 job/step 기준으로 원인을 좁히는가?
Secret을 로그에 출력하라고 하지 않는가?
운영 DB를 테스트에 쓰라고 하지 않는가?
main push 즉시 운영 자동 배포를 무조건 권하지 않는가?
staging/production 환경 분리를 제안하는가?
수정된 workflow YAML을 실제로 실행 가능한 형태로 제안하는가?

📌 요약

CI/CD는 코드 변경 후 lint, test, typecheck, build, 배포까지 이어지는 검증과 운영 흐름을 자동화하는 방식입니다.
GitHub Actions는 GitHub 저장소의 push, pull request, 수동 실행 같은 이벤트를 기준으로 workflow를 실행할 수 있는 자동화 도구입니다.
처음에는 운영 자동 배포보다 lint + test + typecheck + build를 자동으로 돌리는 CI부터 도입하는 것이 안전합니다.
로컬과 CI의 검증 기준을 맞추기 위해 npm run verify 또는 pnpm verify 같은 통합 검증 스크립트를 만들어두는 것이 좋습니다.
프로젝트가 pnpm 기반이면 GitHub Actions도 pnpm install --frozen-lockfile과 pnpm-lock.yaml 기준으로 맞춰야 합니다.
Node 버전은 .nvmrc나 package.json engines로 고정하고, CI에서도 같은 버전을 사용해야 로컬과 CI 차이를 줄일 수 있습니다.
프론트 S3 + CloudFront 배포는 workflow_dispatch 수동 실행으로 시작하면 안전하며, 운영 배포 전 사람이 QA하고 마지막 버튼만 자동화하는 구조가 현실적입니다.
백엔드 CI에서는 운영 DB를 절대 사용하면 안 되며, GitHub Actions service container로 PostgreSQL/Redis를 띄워 테스트하는 방식이 안전합니다.
Prisma 프로젝트에서는 CI/운영에서 migrate dev가 아니라 migrate deploy를 사용해야 합니다.
CI/CD 자동화에서 가장 위험한 것은 Secret 출력, 운영 DB 테스트, 과도한 AWS 권한, 무검토 운영 자동 배포입니다.
1인 개발자 기준으로는 로컬 verify → GitHub Actions CI → 프론트 수동 배포 자동화 → 백엔드 CI → 백엔드 staging 배포 자동화 → production 수동 승인 순서가 가장 현실적입니다.

juni

이전 포스트

TIL - 20260805

다음 포스트

TIL - 20260806

TIL

0806 인프라/DevOps 운영 심화 (5/N): GitHub Actions CI/CD 기본

✅ 1. CI/CD란 무엇인가?

➕ 1-1. CI와 CD 차이

➕ 1-2. 1인 개발자에게도 필요한 이유

✅ 2. GitHub Actions란 무엇인가?

➕ 2-1. 핵심 구성 요소

➕ 2-2. 파일 위치

✅ 3. GitHub Actions 기본 구조

➕ 3-1. name

➕ 3-2. on

➕ 3-3. jobs

➕ 3-4. steps

✅ 4. CI에서 가장 먼저 자동화할 것

➕ 4-1. 프론트엔드 CI

➕ 4-2. 백엔드 CI

➕ 4-3. 공통 검증

✅ 5. package.json verify 스크립트

➕ 5-1. GitHub Actions에서 사용

➕ 5-2. 장점

✅ 6. npm, pnpm, yarn 설치 차이

➕ 6-1. pnpm 예시

➕ 6-2. 주의할 점

✅ 7. Node 버전 관리

➕ 7-1. .nvmrc

➕ 7-2. package.json engines

➕ 7-3. GitHub Actions에서 사용

✅ 8. 환경변수와 GitHub Secrets

➕ 8-1. GitHub Secrets에 넣을 수 있는 값

➕ 8-2. workflow에서 사용

➕ 8-3. 주의

✅ 9. GitHub Environments

➕ 9-1. 장점

➕ 9-2. 예시

✅ 10. workflow_dispatch 수동 실행

➕ 10-1. 장점

➕ 10-2. 추천 운영 방식

✅ 11. 프론트엔드 S3 + CloudFront 배포 workflow

➕ 11-1. 주의

✅ 12. 백엔드 CI 기본

➕ 12-1. 백엔드 CI에서 중요한 것

✅ 13. Prisma와 CI

➕ 13-1. Prisma 명령어

➕ 13-2. migrate deploy와 migrate dev 차이

➕ 13-3. CI 기준

✅ 14. 테스트용 서비스 컨테이너

➕ 14-1. PostgreSQL service

➕ 14-2. Redis service

➕ 14-3. 주의

✅ 15. 백엔드 Docker Image 빌드

➕ 15-1. ECR까지 확장

➕ 15-2. 주의

✅ 16. 백엔드 배포 자동화 방식

➕ 16-1. PM2 서버 배포 방식

➕ 16-2. Docker 서버 배포 방식

➕ 16-3. 주의

✅ 17. Monorepo에서 GitHub Actions

➕ 17-1. 예시 구조

➕ 17-2. paths 조건

➕ 17-3. workspace 실행 예시

✅ 18. 캐시로 CI 속도 개선

➕ 18-1. npm cache

➕ 18-2. pnpm cache

➕ 18-3. 주의

✅ 19. Branch 전략과 CI

➕ 19-1. 단순 전략

➕ 19-2. workflow 기준

➕ 19-3. 1인 개발자 추천

✅ 20. Pull Request 없이도 CI가 필요한가?

➕ 20-1. 이유

➕ 20-2. 추천 방식

✅ 21. 실패한 GitHub Actions 읽는 법

➕ 21-1. 확인 순서

➕ 21-2. 자주 나는 실패

➕ 21-3. 좋은 대응

✅ 22. CI/CD에서 절대 하면 안 되는 것

➕ 22-1. Secret 출력

➕ 22-2. 운영 DB로 테스트

➕ 22-3. 모든 AWS 권한 부여

➕ 3-1. `name`

➕ 3-2. `on`

➕ 3-3. `jobs`

➕ 3-4. `steps`

➕ 7-1. `.nvmrc`

✅ 10. `workflow_dispatch` 수동 실행

➕ 13-2. `migrate deploy`와 `migrate dev` 차이