GitHub Actions 고급 패턴: Reusable Workflows·Composite Actions·모노레포 CI/CD 최적화 전략

org-platform/
  .github/
    workflows/
      build-node.yml        # Node.js 빌드 파이프라인
      build-python.yml      # Python 빌드 파이프라인
      deploy-k8s.yml        # Kubernetes 배포 파이프라인
      security-scan.yml     # 보안 스캔 공통 파이프라인

# org-platform/.github/workflows/build-node.yml
name: Reusable Node.js Build

on:
  workflow_call:
    inputs:
      node-version:
        description: 'Node.js 버전'
        required: false
        type: string
        default: '20'
      working-directory:
        description: '작업 디렉토리'
        required: false
        type: string
        default: '.'
      run-e2e:
        description: 'E2E 테스트 실행 여부'
        required: false
        type: boolean
        default: false
      artifact-name:
        description: '빌드 아티팩트 이름'
        required: false
        type: string
        default: 'build-output'
    secrets:
      NPM_TOKEN:
        description: 'npm 레지스트리 토큰'
        required: false
      SONAR_TOKEN:
        description: 'SonarQube 분석 토큰'
        required: false
    outputs:
      build-version:
        description: '빌드된 버전'
        value: ${{ jobs.build.outputs.version }}
      test-coverage:
        description: '테스트 커버리지'
        value: ${{ jobs.test.outputs.coverage }}

jobs:
  build:
    runs-on: ubuntu-latest
    outputs:
      version: ${{ steps.version.outputs.version }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'
          cache-dependency-path: ${{ inputs.working-directory }}/package-lock.json

      - name: Install dependencies
        working-directory: ${{ inputs.working-directory }}
        run: npm ci

      - name: Build
        working-directory: ${{ inputs.working-directory }}
        run: npm run build

      - name: Extract version
        id: version
        working-directory: ${{ inputs.working-directory }}
        run: echo "version=$(node -p 'require(\"./package.json\").version')" >> "$GITHUB_OUTPUT"

      - name: Upload build artifact
        uses: actions/upload-artifact@v4
        with:
          name: ${{ inputs.artifact-name }}
          path: ${{ inputs.working-directory }}/dist/
          retention-days: 7

  test:
    runs-on: ubuntu-latest
    needs: build
    outputs:
      coverage: ${{ steps.coverage.outputs.percentage }}
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ inputs.node-version }}
          cache: 'npm'

      - name: Install dependencies
        working-directory: ${{ inputs.working-directory }}
        run: npm ci

      - name: Run unit tests
        working-directory: ${{ inputs.working-directory }}
        run: npm run test -- --coverage

      - name: Extract coverage
        id: coverage
        working-directory: ${{ inputs.working-directory }}
        run: |
          COVERAGE=$(cat coverage/coverage-summary.json | jq '.total.lines.pct')
          echo "percentage=$COVERAGE" >> "$GITHUB_OUTPUT"

      - name: SonarQube analysis
        if: secrets.SONAR_TOKEN != ''
        uses: SonarSource/sonarqube-scan-action@v3
        env:
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

  e2e:
    if: inputs.run-e2e
    runs-on: ubuntu-latest
    needs: build
    steps:
      - uses: actions/checkout@v4

      - name: Download build artifact
        uses: actions/download-artifact@v4
        with:
          name: ${{ inputs.artifact-name }}
          path: ${{ inputs.working-directory }}/dist/

      - name: Run E2E tests
        working-directory: ${{ inputs.working-directory }}
        run: npm run test:e2e

# my-service/.github/workflows/ci.yml
name: CI Pipeline

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

jobs:
  build-and-test:
    uses: org-platform/.github/workflows/build-node.yml@v2.3.0
    with:
      node-version: '20'
      working-directory: '.'
      run-e2e: ${{ github.ref == 'refs/heads/main' }}
      artifact-name: 'my-service-build'
    secrets:
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
      SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

  deploy-staging:
    needs: build-and-test
    if: github.ref == 'refs/heads/develop'
    uses: org-platform/.github/workflows/deploy-k8s.yml@v2.3.0
    with:
      environment: staging
      image-tag: ${{ needs.build-and-test.outputs.build-version }}
    secrets: inherit

  deploy-production:
    needs: build-and-test
    if: github.ref == 'refs/heads/main'
    uses: org-platform/.github/workflows/deploy-k8s.yml@v2.3.0
    with:
      environment: production
      image-tag: ${{ needs.build-and-test.outputs.build-version }}
    secrets: inherit

# .github/actions/docker-build-push/action.yml
name: 'Docker Build and Push'
description: 'Docker 이미지를 빌드하고 레지스트리에 푸시합니다'

inputs:
  registry:
    description: '컨테이너 레지스트리 URL'
    required: true
  image-name:
    description: '이미지 이름'
    required: true
  dockerfile:
    description: 'Dockerfile 경로'
    required: false
    default: './Dockerfile'
  context:
    description: '빌드 컨텍스트 경로'
    required: false
    default: '.'
  build-args:
    description: '빌드 인자 (줄바꿈 구분)'
    required: false
    default: ''
  push:
    description: '이미지 푸시 여부'
    required: false
    default: 'true'

outputs:
  image-digest:
    description: '빌드된 이미지 다이제스트'
    value: ${{ steps.build.outputs.digest }}
  image-tag:
    description: '이미지 태그'
    value: ${{ steps.meta.outputs.tags }}

runs:
  using: 'composite'
  steps:
    - name: Set up Docker Buildx
      uses: docker/setup-buildx-action@v3

    - name: Extract metadata
      id: meta
      uses: docker/metadata-action@v5
      with:
        images: ${{ inputs.registry }}/${{ inputs.image-name }}
        tags: |
          type=sha,prefix=
          type=ref,event=branch
          type=ref,event=tag
          type=semver,pattern=v{{version}}
          type=raw,value=latest,enable={{is_default_branch}}

    - name: Build and push
      id: build
      uses: docker/build-push-action@v6
      with:
        context: ${{ inputs.context }}
        file: ${{ inputs.dockerfile }}
        push: ${{ inputs.push }}
        tags: ${{ steps.meta.outputs.tags }}
        labels: ${{ steps.meta.outputs.labels }}
        build-args: ${{ inputs.build-args }}
        cache-from: type=gha
        cache-to: type=gha,mode=max
        provenance: true
        sbom: true

    - name: Print image info
      shell: bash
      run: |
        echo "Image digest: ${{ steps.build.outputs.digest }}"
        echo "Image tags: ${{ steps.meta.outputs.tags }}"

# my-service/.github/workflows/build-image.yml
name: Build Docker Image

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'Dockerfile'

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write
    steps:
      - uses: actions/checkout@v4

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Build and Push
        id: docker
        uses: ./.github/actions/docker-build-push
        with:
          registry: ghcr.io
          image-name: ${{ github.repository }}
          build-args: |
            APP_VERSION=${{ github.sha }}
            BUILD_DATE=${{ github.event.head_commit.timestamp }}

      - name: Deploy notification
        run: |
          echo "Deployed image with digest: ${{ steps.docker.outputs.image-digest }}"

# .github/workflows/monorepo-ci.yml
name: Monorepo CI

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

jobs:
  detect-changes:
    runs-on: ubuntu-latest
    outputs:
      packages: ${{ steps.filter.outputs.changes }}
      api-changed: ${{ steps.filter.outputs.api }}
      web-changed: ${{ steps.filter.outputs.web }}
      shared-changed: ${{ steps.filter.outputs.shared }}
    steps:
      - uses: actions/checkout@v4

      - name: Detect changed packages
        uses: dorny/paths-filter@v3
        id: filter
        with:
          filters: |
            api:
              - 'packages/api/**'
              - 'packages/shared/**'
            web:
              - 'packages/web/**'
              - 'packages/shared/**'
            shared:
              - 'packages/shared/**'
            docs:
              - 'packages/docs/**'

  build-matrix:
    needs: detect-changes
    if: needs.detect-changes.outputs.packages != '[]'
    runs-on: ubuntu-latest
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
      - name: Build dynamic matrix
        id: set-matrix
        run: |
          CHANGES='${{ needs.detect-changes.outputs.packages }}'
          MATRIX=$(echo "$CHANGES" | jq -c '{package: .}')
          echo "matrix=$MATRIX" >> "$GITHUB_OUTPUT"

  build:
    needs: build-matrix
    if: needs.build-matrix.outputs.matrix != ''
    runs-on: ubuntu-latest
    strategy:
      matrix: ${{ fromJSON(needs.build-matrix.outputs.matrix) }}
      fail-fast: false
    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Build package
        run: npm run build --workspace=packages/${{ matrix.package }}

      - name: Test package
        run: npm run test --workspace=packages/${{ matrix.package }}

  integration-test:
    needs: [detect-changes, build]
    if: >-
      needs.detect-changes.outputs.api-changed == 'true' ||
      needs.detect-changes.outputs.web-changed == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Install all dependencies
        run: npm ci

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

  deploy:
    needs: [detect-changes, build, integration-test]
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    strategy:
      matrix:
        include:
          - package: api
            changed: ${{ needs.detect-changes.outputs.api-changed }}
          - package: web
            changed: ${{ needs.detect-changes.outputs.web-changed }}
      fail-fast: false
    steps:
      - name: Skip if not changed
        if: matrix.changed != 'true'
        run: echo "Skipping deploy for ${{ matrix.package }} (no changes)"

      - uses: actions/checkout@v4
        if: matrix.changed == 'true'

      - name: Deploy
        if: matrix.changed == 'true'
        run: |
          echo "Deploying ${{ matrix.package }}..."
          # 실제 배포 로직

# .github/workflows/cache-optimized.yml
name: Cache Optimized Build

on:
  push:
    branches: [main]
  pull_request:

env:
  TURBO_CACHE_DIR: .turbo

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      # 1단계: npm 의존성 캐시 (package-lock.json 기반)
      - name: Setup Node.js with dependency cache
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      # 2단계: Turborepo 원격 캐시 대신 로컬 캐시 사용
      - name: Cache Turborepo
        uses: actions/cache@v4
        with:
          path: .turbo
          key: turbo-${{ runner.os }}-${{ github.sha }}
          restore-keys: |
            turbo-${{ runner.os }}-

      # 3단계: Next.js 빌드 캐시 (pages별 증분 빌드)
      - name: Cache Next.js build
        uses: actions/cache@v4
        with:
          path: packages/web/.next/cache
          key: nextjs-${{ runner.os }}-${{ hashFiles('packages/web/**/*.ts', 'packages/web/**/*.tsx') }}
          restore-keys: |
            nextjs-${{ runner.os }}-

      # 4단계: ESLint 캐시
      - name: Cache ESLint
        uses: actions/cache@v4
        with:
          path: .eslintcache
          key: eslint-${{ runner.os }}-${{ hashFiles('.eslintrc*') }}-${{ github.sha }}
          restore-keys: |
            eslint-${{ runner.os }}-${{ hashFiles('.eslintrc*') }}-
            eslint-${{ runner.os }}-

      # 5단계: Jest 캐시
      - name: Cache Jest
        uses: actions/cache@v4
        with:
          path: /tmp/jest_rs
          key: jest-${{ runner.os }}-${{ hashFiles('**/jest.config.*') }}
          restore-keys: |
            jest-${{ runner.os }}-

      - name: Install dependencies
        run: npm ci

      - name: Build with Turborepo
        run: npx turbo run build --cache-dir=.turbo

      - name: Test with Turborepo
        run: npx turbo run test --cache-dir=.turbo

      - name: Lint with cache
        run: npx turbo run lint --cache-dir=.turbo

# OIDC를 사용한 AWS 배포 예시
jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/github-actions-deploy
          aws-region: ap-northeast-2
          role-session-name: github-actions-${{ github.run_id }}

      - name: Deploy to ECS
        run: |
          aws ecs update-service \
            --cluster production \
            --service my-api \
            --force-new-deployment

# 시크릿 전달 검증을 포함한 caller 워크플로우
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Validate required secrets
        run: |
          MISSING=""
          if [ -z "$AWS_ROLE" ]; then MISSING="$MISSING AWS_ROLE_ARN"; fi
          if [ -z "$NPM_TK" ]; then MISSING="$MISSING NPM_TOKEN"; fi
          if [ -n "$MISSING" ]; then
            echo "::error::Missing required secrets:$MISSING"
            exit 1
          fi
        env:
          AWS_ROLE: ${{ secrets.AWS_ROLE_ARN }}
          NPM_TK: ${{ secrets.NPM_TOKEN }}

  deploy:
    needs: validate
    uses: org-platform/.github/workflows/deploy-k8s.yml@v2.3.0
    secrets:
      AWS_ROLE_ARN: ${{ secrets.AWS_ROLE_ARN }}
      NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: false

- uses: actions/checkout@v4
  with:
    sparse-checkout: |
      packages/api
      packages/shared
      package.json
      package-lock.json
    sparse-checkout-cone-mode: false