CICD Made Easier with Unity CLI

CI/CD 파이프라인은 자연스럽게 성장하는 경향이 있습니다. Unity 에디터 열고 빌드를 시작하는 스크립트로 시작하지만, 점차 더 많은 책임을 맡게 됩니다. 올바른 에디터 실행 파일을 찾고, 플랫폼 모듈을 설치하고, 라이선스를 관리하고, 테스트 결과를 수집하고, 서명 자격 증명을 처리하고, 작업이 완료되면 모든 것을 정리하는 등의 작업을 수행합니다.

그 결과는 효과적일 수 있지만, 이해하기 어렵고 재현하기는 더욱 어렵습니다. 파이프라인은 구성 파일의 코드뿐만 아니라 실행기에 설치 및 구성된 모든 것에 의존합니다.

새로운 Unity CLI는 Unity 에서 자동화 작업을 수행하는 더 간단한 방법을 제공합니다. 이를 통해 빌드 시스템은 에디터 설치, 테스트 실행, 빌드 생성 및 라이선스 관리를 위한 일관된 Unity 명령어를 사용할 수 있습니다. 이 소프트웨어는 비대화형 설치, 구조화된 출력, 명확한 종료 코드 등을 포함한 터미널 및 자동화 워크플로우를 위해 설계되었습니다. ( unity.com )

이는 CI 공급자 또는 프로젝트의 빌드 코드를 대체하는 것이 아닙니다. 대신, 두 장치를 연결하는 데 필요한 맞춤형 장비의 수를 줄여줍니다.

단순화: 파이프라인이 수행해야 할 작업을 표현하세요.

Unity CLI가 나오기 전에는 대부분의 CI 파이프라인에서 Unity 에디터 실행 파일을 직접 실행했습니다. 간소화된 테스트 명령은 다음과 같습니다.

UNITY_PATH="/opt/unity/editors/6000.2.10f1/Editor/Unity"

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -runTests \
  -testPlatform EditMode \
  -testResults ./results/editmode.xml \
  -logFile -

이 접근 방식 자체에 본질적으로 잘못된 점은 없습니다. 진정한 도전은 그 주변에서 일어나야 할 모든 일들에 있다.

파이프라인은 에디터가 어디에 설치되어 있는지 알아야 합니다. 요청된 버전이 있는지 확인하기 위해 다른 스크립트나 머신 이미지가 필요합니다. 실행 프로그램은 올바른 플랫폼 모듈, 라이선스 구성 및 환경 변수를 갖추고 있어야 합니다. Windows, macOS 및 Linux 실행기는 각각 약간씩 다른 경로와 설정 로직이 필요할 수 있습니다.

해당 명령은 테스트를 실행하지만, 그 주변의 파이프라인은 Unity 관련 구현 세부 사항을 많이 담당합니다.

Unity CLI를 사용하면 동일한 단계를 의도라는 관점에서 표현할 수 있습니다.

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

이는 파이프라인에게 프로젝트의 EditMode 테스트를 실행하고 결과를 NUnit XML 파일에 기록하도록 지시합니다. `--allow-install` 옵션을 사용하면 CLI가 프로젝트에 필요한 Unity 버전을 읽고 필요한 경우 설치할 수 있습니다. 어떤 에디터 버전을 사용할지 결정하는 기준은 빌드 머신이 아니라 프로젝트 자체가 됩니다.

빌드 과정은 동일한 패턴을 따릅니다. 이전에는 빌드 과정에서 에디터를 직접 호출하는 경우가 있었습니다.

"$UNITY_PATH" \
  -batchmode \
  -nographics \
  -quit \
  -projectPath "$PWD" \
  -buildTarget Android \
  -executeMethod Builder.PerformBuild \
  -logFile -

Unity CLI를 사용하면 빌드 내용을 더 쉽게 읽을 수 있습니다.

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab \
  --allow-install

기존 Builder.PerformBuild 메서드는 장면 선택, 빌드 설정 적용, 스크립팅 심볼 설정, 버전 정보 할당 또는 스튜디오별 유효성 검사 실행과 같이 프로젝트에 특정한 빌드 부분을 계속 담당할 수 있습니다.

CLI는 해당 메서드와 관련된 자동화를 간소화합니다. CI 구성은 더 이상 에디터를 찾고 실행하는 방법에 대해 자세히 알 필요가 없습니다.

요약하자면, CI 작업은 간단한 명령어 시퀀스만으로 새로운 실행기에서 테스트를 거친 빌드까지 완료할 수 있습니다.

# Install Unity CLI on macOS and Linux
brew install --cask unity-cli

# Install Unity CLI on Windows
winget install Unity.CLI

# Install a specific Editor and its Android module
unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

# Run EditMode tests
unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

# Build an Android App Bundle
unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

또는 테스트 및 빌드 명령에 --allow-install 옵션을 사용하면 프로젝트에서 버전을 결정해야 하는 경우 별도의 에디터 설치 단계가 필요하지 않습니다.

중요한 변화는 단순히 명령어가 더 짧아졌다는 것만이 아닙니다. 그들이 전달하는 메시지는 그 업무가 달성하고자 하는 목표를 명확히 보여준다는 것입니다. 파이프라인을 읽는 사람은 에디터 경로와 배치 모드 플래그 모음을 해독할 필요 없이 Unity 가 설치된 위치, 테스트가 실행되는 위치, 빌드가 생성되는 위치를 확인할 수 있습니다.

생산 파이프라인에는 여전히 다른 부분들이 남아 있을 것입니다. CI 제공업체는 여전히 저장소를 체크아웃하고, 비밀 키를 주입하고, 캐시를 복원하고, 테스트 보고서를 게시하고, 아티팩트를 업로드합니다. Unity CLI는 이러한 시스템에 Unity 관련 단계를 처리하는 더 간단하고 일관된 방법을 제공합니다.

개선점: 파이프라인에서 위험 요소를 제거하세요.

파이프라인이 단순할수록 읽고 유지 관리하기 쉽지만, 단순함은 이점의 일부일 뿐입니다. Unity 설정 및 실행을 일관된 CLI 환경으로 옮김으로써 팀은 CI/CD 위험의 여러 일반적인 원인을 해결할 수 있습니다.

실행자가 잘못된 에디터 버전을 사용하고 있습니다.

사전 구성된 머신에 의존하는 파이프라인은 해당 머신이 올바르게 구성된 상태로 유지되어야 한다는 점에도 의존합니다. 누군가 에디터를 업데이트하거나, 모듈을 제거하거나, 설치 경로를 변경할 수 있습니다. 교체된 실행기는 CI 대시보드에서는 동일하게 보일 수 있지만 내부적으로는 미묘하게 다를 수 있습니다.

그러한 차이점을 알아차리기는 어려울 수 있습니다. 파이프라인 구성도, 프로젝트도 변경되지 않았는데, 머신이 바뀌면서 빌드 동작이 갑자기 달라졌습니다.

Unity CLI를 사용하면 작업에 필요한 에디터와 모듈을 선언할 수 있습니다.

unity install 6000.2.10f1 \
  -m android \
  --accept-eula \
  --yes

또는 작업에서 --allow-install 옵션을 사용하고 프로젝트의 ProjectVersion.txt 파일에서 필요한 편집기를 결정하도록 할 수 있습니다.

이렇게 하면 빌드 환경이 실행기의 문서화되지 않은 속성이 아니라 파이프라인의 일부가 됩니다. Unity 업그레이드하는 브랜치는 빌드 엔지니어가 모든 러너 이미지를 업데이트할 때까지 기다릴 필요 없이 해당 요구 사항을 CI에 바로 반영할 수 있습니다.

또한, 이는 일시적인 달리기 선수들을 더욱 실용적으로 만들어줍니다. 새로운 러너는 처음부터 세심하게 준비된 Unity 빌드 머신으로 시작할 필요가 없습니다. 이 작업은 CLI를 설치하고 필요한 환경을 구축하는 과정을 포함합니다.

CI 환경은 개발자 환경과 다르게 동작합니다.

공급자별 스크립트는 로컬 개발과 CI(지속적 통합) 간에 격차를 초래할 수 있습니다. 작업이 실패하면 개발자는 빌드 실행기에서만 유효한 경로와 옵션이 포함된 긴 편집기 명령을 받을 수 있습니다.

해당 오류를 로컬 환경에서 재현하려면 CI 스크립트를 개발자 컴퓨터에서 작동하는 스크립트로 변환해야 합니다.

Unity CLI는 동일한 명령어를 양쪽에서 사용할 수 있도록 함으로써 이러한 격차를 줄여줍니다.

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml \
  --allow-install

CI 환경은 비밀 키, 라이선스, 아티팩트 게시 등과 같은 부분에서 여전히 차이가 있겠지만, Unity에서 접근하는 방식은 동일하게 유지됩니다.

그렇게 하면 실패한 작업에 대한 조사가 더 쉬워집니다. 개발자는 테스트 또는 빌드 명령을 복사하여 프로젝트 디렉터리에서 실행한 다음, 실행기의 에디터 호출을 먼저 재구성하지 않고도 문제를 재현할 수 있습니다.

사용자 정의 래퍼 스크립트는 그 자체로 하나의 인프라가 됩니다.

많은 스튜디오에서는 Unity 설치 위치를 찾고, 빌드 대상을 에디터 인수로 변환하고, 로그를 스트리밍하고, 종료 코드를 해석하고, 테스트 결과를 올바른 디렉터리로 이동하는 스크립트를 사용합니다.

이러한 스크립트는 대개 타당한 이유로 만들어집니다. 하지만 시간이 지남에 따라 이러한 것들은 테스트와 유지 관리가 필요한 또 다른 인프라 계층이 됩니다. 이러한 코드는 프로젝트 간에 중복되거나 각 CI 제공업체에 맞게 다시 작성될 수도 있습니다.

Unity CLI는 일반적인 작업을 위한 단일 진입점을 제공합니다.

unity install
unity test
unity build

그렇다고 모든 프로젝트가 똑같아진다는 의미는 아닙니다. 스튜디오는 프로젝트별 논리를 적절한 위치에 유지해야 하며, 또 그렇게 할 수 있습니다. AC# 빌드 메서드는 게임 빌드 방식을 계속해서 정의할 수 있으며, CLI는 자동화 도구가 이를 호출하는 표준 방식을 제공합니다.

경계가 더욱 명확해집니다. 프로젝트는 빌드를 소유하고, CI 작업은 해당 빌드가 언제 어디서 실행되는지를 소유합니다.

고장의 원인을 진단하기는 어렵습니다.

Unity 작업이 실패하면 많은 양의 출력 파일이 생성될 수 있습니다. 테스트 결과가 에디터 로그에만 있는 경우, 개발자는 실제 오류 원인을 찾기 위해 해당 로그를 다운로드하고 검색해야 할 수 있습니다. 임시 실행 파일에서는 유용한 진단 파일도 작업이 완료되는 즉시 사라질 수 있습니다.

Unity 테스트는 NUnit XML 보고서를 직접 작성할 수 있습니다.

unity test . \
  --mode EditMode \
  --output ./results/editmode.xml

CI 공급자는 해당 보고서를 수집하여 표시할 수 있으며, 정의된 종료 코드를 사용하고 CLI별 로그를 유지 관리하여 자동화가 테스트 실패와 다른 문제를 구분할 수 있도록 지원합니다. ( docs.unity.com )

그 결과는 단순히 벌목량 증가에만 그치지 않습니다. 이는 개발자들이 이미 확인하고 있는 작업 로그, 테스트 보고서 및 빌드 결과물과 같은 곳에서 더 유용한 출력 결과를 제공합니다.

파이프라인은 각 실행의 주요 출력값을 보존할 수 있습니다.

results/editmode.xml
results/playmode.xml
out/app.aab
Editor.log
cli-log.json

이를 통해 파이프라인을 대규모로 운영하는 것이 더 쉬워집니다. 개발자는 일상적인 테스트 실패를 직접 조사할 수 있으며, 빌드 엔지니어는 인프라 문제를 진단하는 데 필요한 자세한 로그를 유지할 수 있습니다.

자격증과 면허는 직업보다 오래 지속됩니다.

빌드 실행자는 서비스 계정 자격 증명, Android 키 저장소, 서명 암호 또는 오프라인 라이선스 파일과 같은 민감한 자료에 액세스해야 하는 경우가 많습니다. 수명이 긴 시스템은 파이프라인에서 신중한 정리 작업을 수행하지 않는 한 빌드 간에 해당 파일이나 환경 변경 사항을 유지할 수 있습니다.

CLI 우선 워크플로는 시크릿 저장소 및 임시 실행기와 자연스럽게 어울립니다. 자격 증명은 환경 변수로 주입되어 작업에서 사용되고, 실행기가 제거될 때 폐기될 수 있습니다.

파일 서명도 같은 패턴을 따를 수 있습니다. 예를 들어, Android 키스토어는 base64로 인코딩된 CI 비밀 키로 저장하고, 빌드 시에만 디코딩한 다음, 빌드 완료 시 삭제하는 방식입니다.

echo "$ANDROID_KEYSTORE_BASE64" \
  | base64 --decode > ./android.keystore

unity build . \
  --target Android \
  --execute-method Builder.PerformBuild \
  --output-path ./out/app.aab

rm -f ./android.keystore

라이선스 취득은 업무 과정의 명시적인 부분이 될 수도 있습니다. 실행기는 Unity 작업을 수행하기 전에 라이선스 활성화하고 작업이 완료되면 라이선스를 반환합니다.

unity license activate --floating

# Run tests and produce builds

unity license return

Unity CLI는 플로팅 및 오프라인 라이선스 옵션을 포함한 활성화 및 반환 워크플로를 지원합니다. ( docs.unity.com )

임시 실행기의 경우, 반환 명령은 테스트 또는 빌드가 실패하더라도 실행되도록 무조건적인 종료 단계에 배치해야 합니다. 이렇게 하면 실패한 작업으로 인해 시트가 체크 해제된 상태로 남아 이후 빌드에 영향을 미치는 것을 방지할 수 있습니다.

해당 파이프라인은 하나의 CI 제공업체에 연결되어 있습니다.

모든 CI 플랫폼은 고유한 구성 언어를 가지고 있지만, 플랫폼 제공자가 변경되더라도 작업 내의 Unity 작업은 변경될 필요가 없습니다.

파이프라인은 GitHub Actions, GitLab CI, Jenkins, Buildkite, TeamCity 또는 내부 오케스트레이션 시스템을 사용할 수 있습니다. 해당 시스템들은 앞으로도 스케줄링, 비밀 정보, 캐시 및 아티팩트 관리를 계속해서 담당할 것입니다. Unity 프로젝트를 테스트하고 빌드하는 명령어는 일관성을 유지할 수 있습니다.

unity test . --mode EditMode --output ./results/editmode.xml
unity build . --target Android --output-path ./out/app.aab

이것이 CI 마이그레이션을 간편하게 만들어주는 것은 아니지만, Unity 관련 자동화 코드를 다시 작성해야 하는 양을 줄여줍니다. 공급자가 명령을 실행하고, Unity CLI는 Unity 와의 상호 작용을 처리합니다.

그러한 일관성은 프로젝트 전반에 걸쳐 유용합니다. 빌드 팀은 모든 프로젝트가 동일한 내부 빌드 구현을 공유할 필요 없이 공통 파이프라인 패턴을 수립할 수 있습니다.

결론적으로 Unity CLI는 훌륭한 CI/CD 파이프라인이 달성해야 할 목표를 바꾸지는 않습니다. 파이프라인은 여전히 ​​환경을 프로비저닝하고, 테스트를 실행하고, 빌드를 생성하고, 자격 증명을 보호하고, 유용한 출력을 게시하고, 자체적으로 정리 작업을 수행해야 합니다.

달라지는 점은 Unity 에서 이러한 단계를 작동시키기 위해 필요한 맞춤형 장비의 양입니다.

팀은 하드 코딩된 에디터 경로, 사전 구성된 실행기, 그리고 점점 더 복잡해지는 래퍼 스크립트에 의존하는 대신, 몇 가지 명령어를 사용하여 의도를 설명할 수 있습니다. 그 결과, 파이프라인은 읽기 쉽고, 재현하기 쉬우며, 특정 빌드 머신의 상태에 덜 의존하게 됩니다.

Unity CLI를 사용하면 깔끔한 실행 파일에서 테스트를 거친 빌드에 이르는 과정을 간소화하고 그 과정 전반의 안정성을 향상시킬 수 있습니다.