SteamPipe와 GitHub Actions로 게임 빌드 자동 배포 파이프라인 구축하기

핵심 요약

SteamPipe 자동 배포 파이프라인은 GitHub Actions에서 빌드 아티팩트를 Steamworks에 업로드하고, 선택한 베타 브랜치에 설정하는 작업을 자동화합니다. 전용 빌드 계정의 최소 권한, 자격 증명 보호, App/Depot 설정, 워크플로 제한을 함께 설계해야 합니다. 자동화는 수동 실수를 줄이는 데 도움을 줄 수 있지만 완전히 제거하지는 않으며, default 브랜치 배포는 별도의 승인 절차로 다루어야 합니다.

SteamPipe 빌드 배포 자동화는 왜 필요한가?

빌드를 수동으로 업로드하면 계정 정보 관리와 대상 브랜치 선택을 사람이 매번 수행해야 합니다. 자동화는 이 과정을 줄일 수 있지만, 잘못된 대상 브랜치를 설정하면 잘못된 빌드가 배포될 수 있으므로 승인과 브랜치 보호 정책도 함께 마련해야 합니다.

QA와 플레이테스트에서 빌드가 자주 생성되는 프로젝트라면 수동 업로드가 병목이 될 수 있습니다. 이때 검토할 위험은 다음과 같습니다.

인적 오류(Human Error): 릴리즈 브랜치, 내부 테스트 브랜치(Internal Beta), 퍼블릭 플레이테스트 브랜치의 Depot 매핑 혼동
시간 낭비: 빌드 완료 시점마다 담당자가 대기하다가 수동 스크립트를 실행해야 하는 컨텍스트 스위칭 비용
보안 취약점: 로컬 작업자 PC마다 Steamworks 마스터 권한 또는 배포 권한이 있는 계정 정보가 분산 저장되는 문제

GitHub Actions 끝에 SteamPipe 업로드 단계를 연결하면 ‘커밋 또는 태그 → 빌드 및 패키징 → 테스트 브랜치 업로드’ 흐름을 자동화할 수 있습니다. 이는 배포 절차의 자동화이지, 서비스 가용성을 보장하는 무중단 배포 기능은 아닙니다.

SteamPipe 자동화 파이프라인 아키텍처 개요

SteamPipe의 핵심 아키텍처와 구성 요소

SteamPipe는 업로드된 빌드를 관리하고 플레이어 업데이트를 전달하는 Steamworks의 콘텐츠 배포 시스템입니다. 변경 파일과 업데이트 방식은 콘텐츠 및 클라이언트 상태에 따라 달라질 수 있으므로, 아래 구성과 캐시 동작을 고정된 전송량 보장으로 해석해서는 안 됩니다. Valve SteamPipe 문서

구성 요소	역할 및 기능	주요 파일/식별자
SteamCMD	스팀 서버와 통신하며 빌드 업로드 및 라이선스 검증을 수행하는 CLI 툴	`steamcmd.exe` / `steamcmd.sh`
App ID	스팀웍스에 등록된 게임 고유 식별 번호	예: `480` (SpaceWar)
Depot ID	플랫폼(Windows, macOS, Linux)이나 언어별 실제 콘텐츠 데이터 묶음 식별자	예: `481`, `482`
App VDF	빌드 설명, 타깃 브랜치, 포함될 Depot 목록을 정의하는 최상위 설정 파일	`app_build_[AppID].vdf`
Depot VDF	실제 빌드 결과물 폴더(ContentRoot)와 파일 필터링 규칙을 정의하는 파일	`depot_build_[DepotID].vdf`

배포 파이프라인의 전체 데이터 흐름은 다음과 같습니다.

flowchart LR
    subgraph GitHub_Actions [GitHub Actions Runner]
        A[Git Push / Tag] --> B[Game Engine Build]
        B --> C[Artifacts Packaging]
        C --> D[Generate VDF Scripts]
        D --> E[SteamCMD CLI Run]
    end

    subgraph Steam_Network [Steamworks Infrastructure]
        E -->|Encrypted Upload| F[Steam Content Server]
        F --> G[Build Manifest Created]
        G --> H{Target Branch Set}
        H -->|Live Release| I[Default Branch]
        H -->|QA Validation| J[Internal Test Branch]
        H -->|Playtest| K[Public Beta Branch]
    end

GitHub Actions에서 SteamPipe 배포 파이프라인을 어떻게 구현할까?

GitHub Actions에서 SteamPipe 배포를 안정적으로 구축하기 위한 4단계 절차를 설명합니다.

Step 1: Steamworks 전용 빌드 계정 생성 및 권한 설정

CI에는 전용 빌드 계정을 사용하고 필요한 게임과 작업에 최소 권한만 부여합니다. Steamworks 권한 이름과 필요 범위는 계정 구성에 따라 확인해야 합니다.

Steamworks 전용 계정 생성: 배포 작업만 전담할 별도의 스팀 계정(예: bot_studio_builder)을 생성합니다.
Steamworks 권한 부여: 계정 권한은 필요한 업로드·브랜치 작업에 한정하고 현재 Steamworks 권한 화면에서 이름과 범위를 확인합니다.
인증 정보 준비: 현재 game-ci/steam-deploy는 TOTP 또는 사전 인증된 config.vdf를 입력으로 받습니다. 선택한 방법과 액션 버전에 맞춰 공식 액션 안내를 따르고 세션 파일을 민감 정보로 취급합니다. 액션 인증 안내

Step 2: VDF 빌드 스크립트 작성

빌드 설정 파일인 App VDF와 Depot VDF를 저장소의 .steam/ 디렉터리에 준비합니다. 환경에 따라 브랜치나 빌드 설명(Build Description)을 동적으로 치환할 수 있도록 구성합니다.

아래 App ID와 Depot ID는 예시일 뿐이며 실제 프로젝트의 Steamworks 식별자로 바꾸어야 합니다. VDF 예시는 SteamCMD 직접 설정을 이해하기 위한 별도 경로이고, 아래 GitHub Action 예시가 이 파일을 실행하지는 않습니다. 중괄호 대신 명시한 placeholder 문자열도 업로드 전에 실제 값으로 바꾸어야 합니다.

1) App VDF (scripts/app_build_[AppID].vdf)

"AppBuild"
{
	"appid" "480"
	"desc" "Automated CI Build - BUILD_DESC_PLACEHOLDER"
	"buildoutput" "../output/"
	"contentroot" "../build/"
	"setlive" "EXISTING_BETA_BRANCH_PLACEHOLDER"
	"preview" "0"
	"local" ""
	"depots"
	{
		"481" "depot_build_481.vdf"
	}
}

2) Depot VDF (scripts/depot_build_481.vdf)

"DepotBuildConfig"
{
	"DepotID" "481"
	"ContentRoot" "../build/Windows/"
	"FileMapping"
	{
		"LocalPath" "*"
		"DepotPath" "."
		"recursive" "1"
	}
	"FileExclusion" "*.pdb"
	"FileExclusion" "*_BackUpThisFolder_ButDontShipIt*"
}

[!TIP]
예시는 디버그 심볼(*.pdb)과 크래시 백업 폴더를 제외합니다. 프로젝트의 디버깅·지원 정책에 필요한 파일까지 제외하지 않도록 매핑 결과를 미리 검토하세요.

Step 3: GitHub Secrets 환경 변수 등록

저장소의 Settings > Secrets and variables > Actions에 다음 민감 정보를 등록합니다.

STEAM_USERNAME: 빌드 전용 봇 계정 ID
STEAM_PASSWORD: 빌드 전용 봇 계정 비밀번호
STEAM_CONFIG_VDF: (필요 시) Base64로 인코딩된 Steam Guard 세션 파일 내용

GitHub Actions Secrets 설정 화면

Step 4: GitHub Actions 배포 잡 작성

아래는 같은 워크플로의 build 잡이 windows-game-build 아티팩트를 만들었다고 가정한 배포 잡 예시입니다. 실제 저장소에 해당 빌드 잡과 artifact 업로드 단계가 있어야 합니다. 테스트용 베타 브랜치 internal-qa, staging-candidate, 태그 배포용 release-staging은 Steamworks에 미리 만들어야 합니다. default 브랜치는 VDF나 액션에서 자동 지정할 수 없습니다. 예시는 Major 버전 태그(@v3)를 사용하므로, 운영 환경에서는 검토된 액션 버전 또는 커밋 SHA를 고정하고 변경 이력을 확인하세요. 액션 입력 참조

name: Deploy Game Build to Steam

on:
  workflow_dispatch:
    inputs:
      branch:
        type: choice
        description: 'Existing Steam beta branch to deploy to'
        required: true
        default: 'internal-qa'
        options:
          - internal-qa
          - staging-candidate
  push:
    tags:
      - 'v*.*.*'

jobs:
  deploy-to-steam:
    name: Upload & Set Live on SteamPipe
    runs-on: ubuntu-latest
    needs: build

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

      - name: Download Build Artifacts
        # 실제 환경에서는 이전 빌드 Job의 artifact를 내려받거나 S3 등에서 다운로드
        uses: actions/download-artifact@v4
        with:
          name: windows-game-build
          path: build/Windows

      - name: Determine Target Branch and Description
        id: vars
        env:
          PUSH_TAG: ${{ github.event_name == 'push' }}
          INPUT_BRANCH: ${{ inputs.branch }}
        run: |
          if [ "$PUSH_TAG" = "true" ]; then
            target_branch="release-staging"
          else
            target_branch="$INPUT_BRANCH"
          fi
          printf 'branch=%s\n' "$target_branch" >> "$GITHUB_OUTPUT"
          printf 'desc=[CI] run %s, commit %.12s\n' "$GITHUB_RUN_NUMBER" "$GITHUB_SHA" >> "$GITHUB_OUTPUT"

      - name: Execute SteamPipe Deploy
        uses: game-ci/steam-deploy@v3
        with:
          username: ${{ secrets.STEAM_USERNAME }}
          password: ${{ secrets.STEAM_PASSWORD }}
          appId: '480'
          buildDescription: ${{ steps.vars.outputs.desc }}
          rootPath: '.'
          depot1Path: 'build/Windows'
          releaseBranch: ${{ steps.vars.outputs.branch }}

      - name: Report deployment result in log
        if: success()
        run: |
          echo "Successfully deployed build to Steam branch: ${{ steps.vars.outputs.branch }}"

안정적인 라이브 운영을 위한 QA-Ops 실전 팁

1. 단계별 브랜치 프로모션(Branch Promotion) 전략

GitHub Actions에서 무조건 default(실제 라이브) 브랜치로 바로 배포하는 것은 위험합니다. 단계별 검증 파이프라인을 두어야 합니다.

internal-qa (비공개): 매일 밤 또는 PR 머지 시 자동 배포. QA 팀이 1차 회귀 테스트(Regression Test) 수행
staging-candidate (비밀번호 보호): 마일스톤 완료 빌드. 배포 전 최종 밸런스 및 인프라 연동 확인
default (퍼블릭 라이브): SteamPipe 업로드로 자동 지정하지 않는다. 테스트 브랜치에서 검증한 뒤 Steamworks에서 승인·승격한다. Valve는 default branch를 빌드 스크립트에서 자동 설정할 수 없다고 안내한다. Valve SteamPipe 문서

2. 빌드 설명(Build Description)에 Git Metadata 삽입

스팀웍스 웹 대시보드 빌드 내역(Steamworks > Builds)에서 어떤 커밋이 반영되었는지 한눈에 파악할 수 있도록 desc 파라미터에 Git Commit SHA와 PR 번호를 동적으로 삽입하세요.

BUILD_DESC="[CI] Commit: $(git rev-parse --short HEAD) | Branch: ${GITHUB_REF_NAME}"

3. SteamPipe 빌드 캐시 유지

SteamPipe 빌드 도구는 빌드 출력 디렉터리와 캐시를 사용할 수 있습니다. 지속형 러너에서 캐시를 유지하면 재사용할 데이터가 있는지 프로젝트별로 시험할 수 있지만, 임시 GitHub-hosted 러너의 캐시 복원 비용까지 고려해야 하며 특정 업로드 시간 단축을 보장하지 않습니다.

자주 묻는 질문 (FAQ)

Q1. CI 서버에서 Steam Guard(2FA) 이메일/모바일 인증 코드를 요구하며 로그인이 실패합니다.

CI에서는 사람의 입력을 전제로 한 인증 흐름을 그대로 실행하기 어렵습니다. game-ci/steam-deploy가 지원하는 TOTP 또는 사전 인증된 configVdf 중 하나를 구성하고, 계정과 세션 정보를 GitHub Secrets에 안전하게 보관합니다. 액션 동작과 Steam Guard 정책은 현재 공식 안내에서 다시 확인하세요. 액션 인증 안내

Q2. 수십 GB 이상의 대용량 게임 빌드 업로드 시 러너 디스크 용량 부족이나 타임아웃이 발생합니다.

빌드 산출물과 캐시가 사용 가능한 디스크 공간을 넘는 경우 다음 방법을 검토합니다. 사용 가능한 공간은 러너 이미지와 작업 구성에 따라 달라지므로 작업 시작 시 실제 여유 공간을 확인하세요. GitHub-hosted runner image 정보

Self-Hosted Runner 도입: 스튜디오 내부의 고성능 빌드 머신이나 AWS EC2/GCP 인스턴스를 GitHub Self-Hosted Runner로 등록하여 디스크 용량과 네트워크 대역폭 제한을 해소합니다.
디스크 정리 스크립트 실행: 빌드에 필요하지 않은 도구와 임시 파일을 제거하되, 러너 작업에 필요한 도구를 삭제하지 않도록 실행 전후 디스크 공간과 빌드를 확인합니다.

Q3. 비밀번호로 잠겨 있는 스팀 비공개 베타 브랜치에도 자동 배포가 가능한가요?

Steamworks에서 베타 브랜치를 만들고 비밀번호를 설정할 수 있습니다. 빌드 업로드와 브랜치에 설정하는 작업은 별개입니다. 업로드 후 Steamworks에서 빌드를 해당 브랜치에 설정하고, 브랜치 비밀번호는 빌드 스크립트나 로그에 넣지 말고 Steamworks에서 별도로 관리하세요. Valve 베타 브랜치 문서

마무리

SteamPipe와 GitHub Actions를 결합하면 빌드 전달 지연과 배포 과정의 실수를 줄일 수 있습니다. 이 글의 VDF 템플릿과 워크플로를 프로젝트의 브랜치 전략에 맞춰 적용하면 일관된 게임 라이브 운영(QA-Ops) 절차를 마련할 수 있습니다.