---

name: ci-pipeline-setup description: Set up CI/CD pipelines with GitHub Actions. Use when creating new projects, adding automation, or when manual verification becomes bottleneck. Covers lint, test, build, deploy automation. allowed-tools: Read, Glob, Grep, Edit, Write, Bash license: MIT metadata: author: antigravity-team version: "1.0"

CI Pipeline Setup

GitHub Actions를 이용한 CI/CD 파이프라인 설정 스킬입니다.

Core Principle

"verification-before-completion을 로컬에서만 하지 말고, 원격 저장소에서 자동으로 강제한다." "머지 전에 CI가 통과해야 한다 = 시스템으로 강제"

필수 파이프라인 단계

단계	목적	실패 시
Lint	코드 스타일 일관성	PR 머지 차단
Type Check	타입 안전성 검증	PR 머지 차단
Test	기능 정확성 검증	PR 머지 차단
Build	빌드 가능 여부 확인	PR 머지 차단
Security	취약점 스캔	PR 머지 차단

기본 CI 워크플로우

.github/workflows/ci.yml

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

# 동시 실행 제어 (같은 PR에 새 커밋 시 이전 실행 취소)
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  # ================================
  # 1. 코드 품질 검사
  # ================================
  lint:
    name: Lint & Format
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run ESLint
        run: npm run lint

      - name: Check formatting
        run: npm run format:check

  # ================================
  # 2. 타입 검사
  # ================================
  typecheck:
    name: Type Check
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run TypeScript
        run: npm run typecheck

  # ================================
  # 3. 테스트
  # ================================
  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test -- --coverage

      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: false

  # ================================
  # 4. 빌드
  # ================================
  build:
    name: Build
    runs-on: ubuntu-latest
    needs: [lint, typecheck, test]
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: build
          path: .next/
          retention-days: 7

  # ================================
  # 5. 보안 스캔
  # ================================
  security:
    name: Security Audit
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run npm audit
        run: npm audit --audit-level=high

package.json 스크립트

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint . --ext .ts,.tsx",
    "lint:fix": "eslint . --ext .ts,.tsx --fix",
    "format": "prettier --write .",
    "format:check": "prettier --check .",
    "typecheck": "tsc --noEmit",
    "test": "vitest",
    "test:ci": "vitest --run --coverage"
  }
}

Branch Protection Rules

GitHub 설정 방법

Settings → Branches → Add rule

Branch name pattern: main

✅ Require a pull request before merging
  ✅ Require approvals (최소 1명)
  ✅ Dismiss stale pull request approvals when new commits are pushed

✅ Require status checks to pass before merging
  ✅ Require branches to be up to date before merging
  Status checks:
    - lint
    - typecheck
    - test
    - build
    - security

✅ Require conversation resolution before merging
✅ Do not allow bypassing the above settings

branch-protection.yml (자동 설정용)

# .github/branch-protection.yml
branches:
  - name: main
    protection:
      required_pull_request_reviews:
        required_approving_review_count: 1
        dismiss_stale_reviews: true
      required_status_checks:
        strict: true
        contexts:
          - lint
          - typecheck
          - test
          - build
          - security
      enforce_admins: true
      restrictions: null

고급 패턴

Matrix 빌드 (다중 환경)

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test

캐시 최적화

- name: Cache node_modules
  uses: actions/cache@v4
  with:
    path: node_modules
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
    restore-keys: |
      ${{ runner.os }}-node-

PR 라벨 자동화

# .github/workflows/labeler.yml
name: Labeler

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/labeler@v5
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}

의존성 자동 업데이트 (Dependabot)

# .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    open-pull-requests-limit: 10
    labels:
      - "dependencies"
    groups:
      dev-dependencies:
        patterns:
          - "@types/*"
          - "eslint*"
          - "prettier*"

배포 파이프라인 (CD)

Vercel 자동 배포

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    needs: [lint, typecheck, test, build]
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          vercel-args: '--prod'

Preview 배포 (PR별)

# PR에서 자동으로 Preview URL 생성
on:
  pull_request:

jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
          vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
          # --prod 없음 = Preview 배포

Workflow 파일 구조

.github/
├── workflows/
│   ├── ci.yml           # 메인 CI (lint, test, build)
│   ├── deploy.yml       # 프로덕션 배포
│   ├── preview.yml      # PR Preview 배포
│   └── labeler.yml      # 라벨 자동화
├── dependabot.yml       # 의존성 업데이트
├── CODEOWNERS           # 코드 소유자
└── PULL_REQUEST_TEMPLATE.md

Checklist

새 프로젝트

• .github/workflows/ci.yml 생성
• package.json 스크립트 정의 (lint, typecheck, test, build)
• Branch Protection Rules 설정
• Dependabot 설정
• CODEOWNERS 파일 생성

CI 품질

• 모든 PR에서 CI 필수 통과
• 캐시 최적화로 빌드 시간 단축
• 병렬 실행으로 효율성 증가
• 실패 시 명확한 에러 메시지

보안

• Secrets는 GitHub Secrets에만 저장
• npm audit 자동 실행
• 의존성 자동 업데이트 활성화

References

• GitHub Actions Documentation
• Branch Protection Rules
• Dependabot