CICD Made Easier with Unity CLI

Конвейеры CI/CD, как правило, развиваются органически. Начинающийся как скрипт, открывающий редактор Unity и запускающий сборку, постепенно берет на себя все больше обязанностей: поиск нужного исполняемого файла редактора, установка модулей платформы, управление лицензиями, сбор результатов тестирования, обработка учетных данных для подписи и очистка всего процесса после завершения работы.

Результат может сработать, но его будет трудно понять, а ещё сложнее воспроизвести. Конвейер обработки зависит не только от кода в своем конфигурационном файле, но и от всего, что установлено и настроено на исполнителе.

Новый интерфейс командной строки Unity предоставляет более простой способ автоматизации работы с 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) и записать результаты в XML-файл NUnit. С помощью параметра --allow-install интерфейс командной строки может определить версию 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 может по-прежнему отвечать за те части сборки, которые специфичны для вашего проекта: выбор сцен, применение параметров сборки, установка символов скриптов, назначение информации о версии или выполнение проверки, специфичной для студии.

Интерфейс командной строки упрощает автоматизацию этого метода. Теперь конфигурации 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 за единый интерфейс командной строки, команды также могут устранить несколько распространенных источников рисков в области CI/CD.

У бегуна установлена ​​неправильная версия редактора.

Конвейер обработки данных, зависящий от предварительно настроенного оборудования, также зависит от того, насколько правильно настроено это оборудование. Пользователь может обновить редактор, удалить модуль или изменить путь установки. Замененный вариант может выглядеть идентично на панели мониторинга CI, но при этом незначительно отличаться под поверхностью.

Эти различия бывает трудно заметить. Конфигурация конвейера не изменилась, и проект тоже не изменился, но сборка внезапно стала вести себя иначе, потому что изменилась машина.

Unity CLI позволяет заданию указать необходимый редактор и модули:

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

Или же в задании можно использовать параметр --allow-install и позволить файлу ProjectVersion.txt проекта определить необходимый редактор.

Это позволяет интегрировать среду сборки в конвейер, а не рассматривать её как недокументированное свойство исполнителя. Ветка, обновляющая Unity, может перенести это требование в CI, вместо того чтобы ждать, пока инженер сборки обновит каждый образ для запуска репозитория.

Это также делает эфемерные беговые дорожки более практичными. Новичку не обязательно начинать свою жизнь с тщательно подготовленной машины для сборки Unity . В рамках этой задачи можно установить интерфейс командной строки и настроить необходимую среду.

Система непрерывной интеграции (CI) ведет себя иначе, чем машины разработчиков.

Скрипты, специфичные для конкретного поставщика услуг, могут создавать разрыв между локальной разработкой и CI. При сбое задания разработчик может получить большую команду редактора, содержащую пути и параметры, которые имеют смысл только в среде выполнения сборки.

Для воспроизведения этой ошибки локально необходимо преобразовать скрипт CI в код, работающий на компьютере разработчика.

Интерфейс командной строки Unity сокращает этот разрыв, поскольку одну и ту же команду можно использовать в обоих местах:

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

В среде CI по-прежнему будут существовать различия — такие как секреты, лицензирование и публикация артефактов, — но точка входа в Unity останется прежней.

Это упрощает расследование неудачной попытки выполнения работы. Разработчик может скопировать команду тестирования или сборки, запустить ее из каталога проекта и начать воспроизводить проблему, не переустанавливая предварительно вызов редактора в процессе выполнения.

Пользовательские скрипты-обертки становятся собственной инфраструктурой.

Во многих студиях есть скрипты, которые находят установленные версии Unity , преобразуют цели сборки в аргументы редактора, передают логи, интерпретируют коды завершения и перемещают результаты тестирования в нужную директорию.

Эти сценарии обычно создаются по веским причинам. Однако со временем они превращаются в еще один уровень инфраструктуры, который необходимо тестировать и поддерживать. Они также могут дублироваться в разных проектах или переписываться для каждого поставщика CI.

Интерфейс командной строки Unity предоставляет единую точку входа для выполнения распространенных операций:

unity install
unity test
unity build

Это не означает, что каждый проект становится идентичным. Студии могут — и должны — оставлять логику, специфичную для каждого проекта, там, где ей и место. Метод сборки AC# может по-прежнему определять, как собирается игра, а интерфейс командной строки предоставляет стандартный способ его вызова для автоматизации.

Граница становится яснее: проект отвечает за сборку, а задача CI — за то, когда и где эта сборка будет выполняться.

Диагностировать неисправности сложно.

Неудачная попытка выполнения задания Unity может привести к генерации большого объема выходных данных. Если результаты тестирования существуют только в журнале редактора, разработчикам может потребоваться загрузить этот журнал и выполнить поиск в нем, чтобы найти фактическую причину ошибки. В случае с временным выполнением задания полезные диагностические файлы также могут исчезнуть сразу после завершения работы.

Unity Test может напрямую записывать XML-отчеты NUnit:

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 , паролям для подписи или файлам лицензий в автономном режиме. На машинах с длительным сроком службы эти файлы или изменения среды могут сохраняться между сборками, если конвейер не выполнит тщательную очистку.

Рабочий процесс, ориентированный на использование командной строки, идеально подходит для хранилищ секретных данных и временных исполнителей. Учетные данные могут быть внедрены в качестве переменных среды, использоваться заданием и удаляться при удалении исполнителя.

Подписание файлов может осуществляться по той же схеме. Например, хранилище ключей Android может храниться в виде секретного ключа CI, закодированного в base64, декодируемого только для сборки и удаляемого при завершении процесса:

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

Это не делает миграцию в систему непрерывной интеграции совершенно легкой, но уменьшает объем автоматизации, специфичной для Unity, которую необходимо переписывать. Провайдер выполняет команду; Unity CLI обрабатывает взаимодействие с Unity.

Такая согласованность полезна и в рамках разных проектов. Команды разработчиков могут выстраивать общие шаблоны конвейера сборки, не требуя от каждого проекта использования одной и той же внутренней реализации сборки.

В конечном счете, Unity CLI не меняет того, что должна делать хорошая система CI/CD. Конвейеру по-прежнему необходимо настраивать свою среду, запускать тесты, создавать сборки, защищать учетные данные, публиковать полезные выходные данные и очищать систему после завершения работы.

Меняется лишь объем специализированного оборудования, необходимого для обеспечения работы этих шагов с Unity.

Вместо того чтобы полагаться на жестко заданные пути к редактору, предварительно настроенные средства запуска и все более сложные скрипты-оболочки, команды могут описать свои намерения с помощью небольшого набора команд. В результате получается конвейер, который легче читается, легче воспроизводится и меньше зависит от состояния конкретной сборочной машины.

Используйте Unity CLI, чтобы упростить путь от чистого исполняемого файла до протестированной сборки и повысить надежность всего процесса.