4-5. CI/CD 파이프라인 통합 | World Partition Deep Dive

01

Jenkins Pipeline

Jenkins를 이용한 HLOD 빌드 자동화

                    Groovy - Jenkinsfile
pipeline {
    agent {
        label 'unreal-build-agent'
    }

    environment {
        UE_ROOT = 'C:\\Program Files\\Epic Games\\UE_5.5'
        PROJECT_PATH = "${WORKSPACE}\\MyProject\\MyProject.uproject"
        MAP_PATH = '/Game/Maps/MainWorld'
    }

    stages {
        stage('Checkout') {
            steps {
                checkout scm
            }
        }

        stage('Build HLODs') {
            steps {
                script {
                    bat """
                        "${UE_ROOT}\\Engine\\Binaries\\Win64\\UnrealEditor-Cmd.exe" ^
                            "${PROJECT_PATH}" ^
                            "${MAP_PATH}" ^
                            -run=WorldPartitionBuilderCommandlet ^
                            -AllowCommandletRendering ^
                            -Builder=WorldPartitionHLODsBuilder ^
                            -SCCProvider=None
                    """
                }
            }
        }

        stage('Build Navigation') {
            steps {
                script {
                    bat """
                        "${UE_ROOT}\\Engine\\Binaries\\Win64\\UnrealEditor-Cmd.exe" ^
                            "${PROJECT_PATH}" ^
                            "${MAP_PATH}" ^
                            -run=WorldPartitionBuilderCommandlet ^
                            -AllowCommandletRendering ^
                            -Builder=WorldPartitionNavigationDataBuilder ^
                            -SCCProvider=None
                    """
                }
            }
        }

        stage('Cook Content') {
            steps {
                script {
                    bat """
                        "${UE_ROOT}\\Engine\\Build\\BatchFiles\\RunUAT.bat" ^
                            BuildCookRun ^
                            -project="${PROJECT_PATH}" ^
                            -platform=Win64 ^
                            -cook ^
                            -pak ^
                            -stage
                    """
                }
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'MyProject/Saved/Logs/**/*.log'
        }
        failure {
            emailext (
                subject: "Build Failed: ${env.JOB_NAME}",
                body: "Check console output at ${env.BUILD_URL}",
                to: 'team@example.com'
            )
        }
    }
}
                

02

GitHub Actions

GitHub 기반 CI/CD 파이프라인

                    YAML - .github/workflows/build-world-partition.yml
name: Build World Partition Assets

on:
  push:
    branches: [ main ]
    paths:
      - 'Content/Maps/**'
      - 'Content/__ExternalActors__/**'
  workflow_dispatch:

jobs:
  build-hlods:
    runs-on: [self-hosted, unreal]

    env:
      UE_ROOT: C:\Program Files\Epic Games\UE_5.5

    steps:
      - uses: actions/checkout@v3
        with:
          lfs: true

      - name: Build HLODs
        run: |
          & "$env:UE_ROOT\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
            "${{ github.workspace }}\MyProject\MyProject.uproject" `
            "/Game/Maps/MainWorld" `
            -run=WorldPartitionBuilderCommandlet `
            -AllowCommandletRendering `
            -Builder=WorldPartitionHLODsBuilder `
            -SCCProvider=None `
            -Verbose

      - name: Build Navigation
        run: |
          & "$env:UE_ROOT\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" `
            "${{ github.workspace }}\MyProject\MyProject.uproject" `
            "/Game/Maps/MainWorld" `
            -run=WorldPartitionBuilderCommandlet `
            -AllowCommandletRendering `
            -Builder=WorldPartitionNavigationDataBuilder `
            -SCCProvider=None

      - name: Commit Generated Assets
        run: |
          git config user.name "CI Bot"
          git config user.email "ci@example.com"
          git add Content/__ExternalActors__/**/HLOD*
          git add Content/__ExternalActors__/**/NavMesh*
          git commit -m "Auto-generated: HLOD and NavMesh [skip ci]" || true
          git push
                

Self-Hosted Runner

Unreal Engine 빌드는 GPU가 필요할 수 있으므로 Self-Hosted Runner를 사용해야 합니다. 클라우드 러너는 일반적으로 GPU를 제공하지 않습니다.

03

분산 빌드

대규모 월드의 병렬 빌드

대규모 월드에서는 영역별로 분할하여 병렬 빌드하면 시간을 크게 단축할 수 있습니다.

                    분산 빌드 개념
# 영역별 병렬 빌드 (Simplygon Grid 또는 커스텀 스크립트)

# 머신 1: 영역 A (북서쪽)
UnrealEditor-Cmd.exe "MyProject.uproject" "/Game/Maps/MainWorld" ^
    -run=WorldPartitionBuilderCommandlet ^
    -Builder=WorldPartitionHLODsBuilder ^
    -AllowCommandletRendering ^
    -Region=RegionA

# 머신 2: 영역 B (북동쪽)
UnrealEditor-Cmd.exe "MyProject.uproject" "/Game/Maps/MainWorld" ^
    -run=WorldPartitionBuilderCommandlet ^
    -Builder=WorldPartitionHLODsBuilder ^
    -AllowCommandletRendering ^
    -Region=RegionB

# 머신 3: 영역 C (남서쪽)
...

# 최종 병합 단계에서 결과물 통합
                

분산 빌드 아키텍처:

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   머신 1    │    │   머신 2    │    │   머신 3    │
│  Region A   │    │  Region B   │    │  Region C   │
└──────┬──────┘    └──────┬──────┘    └──────┬──────┘
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                          ▼
                  ┌───────────────┐
                  │  결과물 병합  │
                  │ (Git Merge)   │
                  └───────────────┘

04

빌드 트리거 전략

언제 HLOD를 리빌드할 것인가

콘텐츠 변경 시

Content/Maps/** 또는 __ExternalActors__/** 경로 변경 시 자동 트리거.

정기 빌드

야간 또는 주간 단위로 전체 HLOD 리빌드 수행.

수동 트리거

릴리즈 전 또는 마일스톤 빌드 시 명시적으로 실행.

PR 검증

PR에서 월드 변경 감지 시 HLOD 빌드 테스트.

                    YAML - 조건부 트리거
on:
  push:
    branches: [ main ]
    paths:
      - 'Content/Maps/**'
      - 'Content/__ExternalActors__/**'
      - 'Content/HLOD/**'

  schedule:
    # 매일 새벽 3시 (야간 빌드)
    - cron: '0 3 * * *'

  workflow_dispatch:
    inputs:
      rebuild_all:
        description: 'Rebuild all HLODs'
        required: false
        default: 'false'
                

05

빌드 아티팩트 관리

생성된 에셋의 버전 관리

                    Git LFS 설정
# .gitattributes

# HLOD 생성 에셋
Content/__ExternalActors__/**/HLOD*.uasset filter=lfs diff=lfs merge=lfs -text
Content/HLOD/**/*.uasset filter=lfs diff=lfs merge=lfs -text

# NavMesh 데이터
Content/__ExternalActors__/**/NavMesh*.uasset filter=lfs diff=lfs merge=lfs -text

# 텍스처 (HLOD 머티리얼 베이킹)
Content/HLOD/**/*.ubulk filter=lfs diff=lfs merge=lfs -text
                

빌드 아티팩트 전략

HLOD 에셋을 Git에 커밋할지, 빌드 서버에서만 생성할지 결정해야 합니다. 팀 규모와 빌드 시간에 따라 적절한 전략을 선택하세요.

SUMMARY

핵심 요약

Jenkins: 전통적인 CI 도구, 커스터마이징 용이
GitHub Actions: Self-Hosted Runner로 UE 빌드
분산 빌드: 영역별 병렬 처리로 시간 단축
트리거 전략: 콘텐츠 변경, 정기, 수동 조합
Git LFS: HLOD 에셋 버전 관리

PRACTICE

도전 과제

배운 내용을 직접 실습해보세요

실습 1: Jenkins HLOD 빌드 파이프라인

Jenkins에서 HLOD 빌드를 자동화하는 파이프라인 스크립트를 작성하세요. 맵 변경 감지 -> HLOD 빌드 -> 결과 검증 -> 아티팩트 저장 단계를 구성하고, 빌드 실패 시 알림을 설정합니다.

실습 2: GitHub Actions HLOD 워크플로우

GitHub Actions에서 PR 생성 시 변경된 맵에 대해 HLOD 빌드를 실행하고, 빌드 결과(성공/실패, HLOD 통계)를 PR 코멘트로 보고하는 워크플로우를 작성하세요.

심화 과제

맵 변경 -> HLOD 빌드 -> 미니맵 생성 -> 네비메시 빌드 -> 쿠킹 -> 패키징까지 전체 맵 빌드 프로세스를 자동화하는 종합 CI/CD 파이프라인을 구축하세요. 단계별 캐싱과 병렬 처리를 최적화합니다.