Steam 빌드 패치와 Hotfix 릴리즈 자동화 파이프라인 구축 가이드
SteamPipe와 SteamCMD를 CI/CD에 연결해 게임 빌드 검증, 베타 브랜치 배포, 승인 게이트, 롤백까지 자동화하는 실전 패치·Hotfix 릴리즈 파이프라인을 정리합니다.
핵심 요약
Steam 패치 자동화의 핵심은 재현 가능한 빌드 산출물을 만들고 SteamPipe로 비공개 브랜치에 먼저 업로드한 뒤 검증이 끝난 빌드만 공개 브랜치로 승격하는 것이다. Hotfix는 일반 패치와 같은 배포 경로를 쓰되 코드 변경 범위, 테스트 게이트, 승인 시간을 줄이고 즉시 롤백 가능한 이전 빌드를 보존해야 한다.
이 글에서는 Unity·Unreal Engine 등 특정 엔진과 무관하게 적용할 수 있는 SteamCMD 기반 파이프라인을 설명한다.
Steam 빌드 패치 자동화는 왜 필요한가?
수동 릴리즈는 빌드 폴더를 잘못 선택하거나 이전 실행 파일을 다시 업로드하거나 검증되지 않은 콘텐츠를 기본 브랜치에 공개하는 실수로 이어지기 쉽다. 특히 크래시를 긴급 수정하는 Hotfix는 속도가 중요하지만 속도를 위해 검증과 롤백 절차까지 생략하면 더 큰 장애를 만들 수 있다.
자동화 파이프라인은 다음 네 가지를 보장해야 한다.
| 목표 | 구현 방법 | 확인 기준 |
|---|---|---|
| 재현성 | CI에서 고정된 엔진·SDK·의존성 버전으로 빌드 | 동일 커밋에서 동일한 파일 목록 생성 |
| 추적성 | Git SHA, 빌드 번호, Steam build ID 기록 | 배포된 파일의 소스를 역추적 가능 |
| 안전한 공개 | 비공개 QA 브랜치 → 공개 브랜치 승격 | 공개 전 테스트·승인 게이트 통과 |
| 복구성 | 이전 Steam build ID와 배포 이력 보존 | 문제 발생 시 빠르게 이전 빌드로 전환 |
SteamPipe와 SteamCMD는 각각 무엇을 담당하는가?
Steam의 콘텐츠 배포는 SteamPipe가 담당한다. CI 환경에서는 보통 SteamCMD를 실행해 SteamPipe 빌드 스크립트를 전달한다.
| 구성 요소 | 역할 | 파이프라인에서의 위치 |
|---|---|---|
| Steamworks App ID | 게임 애플리케이션 식별자 | 앱 빌드 설정의 기준 |
| Depot | 플랫폼 또는 언어별 콘텐츠 묶음 | Windows, macOS, DLC 등 분리 배포 |
| SteamPipe | 콘텐츠 청크 업로드 및 배포 처리 | 파일 변경분 전송 |
| SteamCMD | SteamPipe 자동 실행 도구 | CI의 업로드 단계 |
| Branch | 기본·베타·QA·Hotfix 배포 채널 | 검증과 점진 공개 |
SteamPipe는 파일 전체를 매번 단순 복사하는 방식이 아니라 콘텐츠를 청크 단위로 처리한다. 그래도 패치 용량은 파일 구조에 크게 영향을 받는다. 대형 아카이브 파일 하나에 작은 변경이 섞이면 사용자가 다시 내려받아야 할 데이터가 커질 수 있으므로 자주 바뀌는 데이터와 거의 변경되지 않는 데이터를 가능한 한 분리하는 편이 좋다.
Steam 빌드 패치 파이프라인을 어떻게 구현할까?
1. 빌드 입력을 고정한다
빌드 시작 시점에 다음 값을 생성하고 아티팩트 메타데이터로 남긴다.
- Git commit SHA
- CI 실행 번호
- 대상 플랫폼과 빌드 구성(Release, Shipping 등)
- 게임 버전 문자열
- 콘텐츠 해시 또는 파일 목록 해시
예를 들어 버전은 1.4.2+ci.381처럼 사용자에게 보이는 버전과 CI 식별자를 함께 기록할 수 있다. Steam에 업로드할 폴더에는 디버그 심볼, 원본 에셋, 테스트 전용 설정 파일이 섞이지 않도록 별도 스테이징 단계를 둔다.
2. SteamPipe VDF를 저장소에서 관리한다
SteamPipe 스크립트는 보통 VDF(KeyValues) 형식이다. 앱 빌드 스크립트와 디포 빌드 스크립트를 코드와 함께 버전 관리하면 어떤 경로를 어떤 디포에 올렸는지 리뷰할 수 있다.
app_build_123456.vdf 예시는 다음과 같다.
"appbuild"
{
"appid" "123456"
"desc" "1.4.2 ci-381 8f31c2a"
"buildoutput" "../steam-output"
"contentroot" "../staging/windows"
"setlive" "qa"
"depots"
{
"123457" "depot_build_123457.vdf"
}
}depot_build_123457.vdf에서는 실제 업로드 대상과 제외 규칙을 명시한다.
"DepotBuildConfig"
{
"DepotID" "123457"
"ContentRoot" "../staging/windows"
"FileMapping"
{
"LocalPath" "*"
"DepotPath" "."
"recursive" "1"
}
"FileExclusion" "*.pdb"
"FileExclusion" "Logs/*"
"FileExclusion" "CrashDumps/*"
}setlive는 업로드 직후 연결할 브랜치다. 운영 기본 브랜치를 가리키게 두면 CI 설정 실수 하나로 미검증 빌드를 공개할 수 있으므로 자동 업로드 대상은 qa 또는 비공개 베타 브랜치로 제한하는 것이 안전하다.
3. CI에서 SteamCMD 업로드를 실행한다
Steam Guard를 포함한 계정 보안 정보와 Steamworks 배포 권한은 CI 비밀 저장소에 보관한다. 비밀값을 로그에 출력하지 않고 일반 플레이 계정 대신 배포 권한만 가진 전용 Steamworks 계정을 사용한다.
steamcmd +login "$STEAM_USER" "$STEAM_PASSWORD" \
+run_app_build "scripts/steam/app_build_123456.vdf" \
+quitCI는 SteamCMD 종료 코드만 확인해서는 부족하다. 업로드 로그에서 생성된 Steam build ID를 추출해 릴리즈 메타데이터에 저장하고 업로드된 디포와 대상 브랜치가 의도한 값인지 확인해야 한다.
flowchart LR
A[Git 태그 또는 Hotfix 커밋] --> B[엔진 빌드]
B --> C[스테이징 및 파일 검사]
C --> D[자동 테스트]
D --> E[SteamCMD: QA 브랜치 업로드]
E --> F[QA 스모크 테스트]
F --> G{승인 완료?}
G -- 예 --> H[공개 브랜치 승격]
G -- 아니오 --> I[차단 또는 이전 빌드 복구]패치 전 검증 게이트에는 무엇을 넣어야 하는가?
검증은 시간이 오래 걸리는 테스트와 릴리즈를 막는 최소 테스트로 나눠야 한다. 모든 테스트를 Hotfix마다 처음부터 끝까지 실행하면 긴급 수정의 가치가 줄어들고 반대로 테스트를 모두 끄면 수정 내용과 관계없는 회귀를 놓치게 된다.
필수 게이트
- 빌드 성공과 파일 검사: 실행 파일, 필수 DLL·패키지,
steam_appid.txt처리 정책, 설정 파일이 스테이징 경로에 올바르게 있는지 검사한다. - 자동 테스트: 단위 테스트, 저장 데이터 호환성 검사, 핵심 씬 또는 맵 로딩 테스트, 헤드리스 실행 가능 여부를 확인한다.
- 스모크 테스트: Steam QA 브랜치에서 설치, 실행, 로그인·초기화, 저장·불러오기, 종료를 실제 클라이언트 기준으로 확인한다.
- 배포 비교: 이전 빌드와 현재 빌드의 파일 목록 및 용량 차이를 확인한다. 의도하지 않은 대용량 에셋 교체는 이 단계에서 발견할 수 있다.
다음은 배포 전 확인용 체크리스트의 예다.
| 항목 | 일반 패치 | Hotfix |
|---|---|---|
| 전체 회귀 테스트 | 권장 | 변경 범위에 따라 생략 가능 |
| 크래시 재현 시나리오 | 해당 시 필수 | 필수 |
| 첫 실행 스모크 테스트 | 필수 | 필수 |
| 기존 세이브 로드 | 변경 시 필수 | 필수 |
| QA 브랜치 설치 검증 | 필수 | 필수 |
| 담당자 승인 | 필수 | 온콜 또는 릴리즈 담당자 필수 |
Hotfix 릴리즈는 일반 패치와 무엇이 다른가?
Hotfix는 파이프라인을 우회하는 절차가 아니라 더 짧은 경로를 명시적으로 정의한 릴리즈 유형이어야 한다. 일반 패치와 다른 점은 테스트를 무조건 줄이는 것이 아니라 변경 범위를 작게 유지하고 장애 증상과 수정 검증을 강하게 연결하는 데 있다.
Hotfix 운영 규칙
- 수정 커밋은 장애 원인과 직접 관련된 최소 범위로 제한한다.
- 기능 추가, 대규모 리팩터링, 에셋 재압축은 Hotfix 브랜치에 넣지 않는다.
- 크래시라면 크래시 리포트의 스택 트레이스, 발생 버전, 재현 조건을 릴리즈 티켓에 기록한다.
- QA 브랜치에서 수정 전후의 재현 결과를 남긴다.
- 공개 직후 관찰할 지표와 롤백 기준을 배포 전에 정한다.
예를 들어 시작 시 크래시를 고쳤다면 최소한 다음 조건을 만족해야 한다.
- 문제가 발생한 이전 빌드에서 크래시 재현 또는 크래시 리포트 증거를 확보한다.
- Hotfix 빌드에서 같은 입력·세이브·플랫폼 조건으로 시작 과정을 반복한다.
- Steam QA 브랜치 설치 후 첫 실행과 기존 세이브 로드를 확인한다.
- 공개 후 크래시 리포트, 시작 실패율, 부정 리뷰를 정해 둔 시간 동안 관찰한다.
Steam 패치 롤백은 어떻게 준비해야 하는가?
롤백의 목표는 코드를 되돌리는 것이 아니라 사용자에게 정상으로 확인된 콘텐츠 빌드를 최대한 빨리 다시 제공하는 것이다. 따라서 배포가 끝난 뒤에도 다음 데이터를 삭제하지 않아야 한다.
- Steam build ID와 배포 시각
- 연결된 브랜치와 디포 ID
- Git commit SHA 및 CI 아티팩트 URL
- 변경 목록과 승인자
- 알려진 문제 및 롤백 판단 근거
가장 안전한 운영 방식은 공개 직전의 정상 build ID를 릴리즈 메모에 고정해 두는 것이다. Steamworks 관리 화면에서 브랜치의 라이브 빌드를 이전 build ID로 전환하는 절차는 사전에 권한 있는 담당자가 한 번 리허설해 두는 편이 좋다. 롤백 후에는 원인 분석을 위해 장애 빌드를 즉시 삭제하지 말고 접근을 제한한 상태로 보존한다.
자주 묻는 질문 (FAQ)
SteamCMD 비밀번호를 CI 환경 변수에 넣어도 될까?
평문 환경 변수나 저장소 파일에 직접 넣으면 안 된다. CI의 암호화된 Secret 기능을 사용하고 배포 권한을 최소화한 전용 Steamworks 계정을 분리해야 한다.
QA 브랜치와 기본 브랜치를 같은 빌드로 자동 전환해도 될까?
검증 완료 신호 없이 자동 전환하면 QA 단계가 의미 없어지므로 권장하지 않는다. QA 브랜치 업로드는 자동화하고 기본 브랜치 승격은 테스트 결과와 승인 조건을 통과한 뒤 실행하는 구조가 안전하다.
Hotfix에서 전체 회귀 테스트를 생략해도 될까?
가능하지만 조건이 있다. 수정 범위가 작고 영향 영역을 명확히 알 수 있어야 하며 최소 스모크 테스트와 장애 재현 시나리오 검증은 반드시 통과해야 한다.
정리
Steam 빌드 자동화는 SteamCMD 명령 하나를 CI에 추가하는 작업으로 끝나지 않는다. 빌드 입력 고정, SteamPipe 스크립트의 코드 관리, QA 브랜치 검증, 공개 승인, build ID 기록, 롤백 리허설을 하나의 운영 절차로 묶어야 안정적인 패치와 Hotfix 릴리즈가 가능하다.
처음에는 Windows 단일 디포와 qa 브랜치만 대상으로 시작해도 충분하다. 이후 플랫폼별 디포, 자동 스모크 테스트, 크래시 모니터링 알림을 단계적으로 추가하면 릴리즈 속도와 안정성을 함께 높일 수 있다.
