CICD Made Easier with Unity CLI

Los pipelines de CI/CD tienden a crecer orgánicamente. Lo que comienza como un script que abre el Editor de Unity y comienza una compilación gradualmente asume más responsabilidades: encontrar el ejecutable correcto del Editor, instalar módulos de plataforma, gestionar licencias, recopilar resultados de pruebas, manejar credenciales de firma y limpiar todo cuando finaliza el trabajo.

El resultado puede funcionar, pero puede ser difícil de entender e incluso más difícil de reproducir. La tubería depende no solo del código en su archivo de configuración, sino también de todo lo que esté instalado y configurado en el ejecutor.

La nueva CLI de Unity proporciona una forma más sencilla para que la automatización trabaje con Unity. Proporciona a los sistemas de compilación un comando unity consistente para instalar Editores, ejecutar pruebas, producir compilaciones y gestionar licencias. Está diseñado para flujos de trabajo de terminal y automatización, incluyendo instalación no interactiva, salida estructurada y códigos de salida claros. (unity.com)

Esto no reemplaza a su proveedor de CI ni al código de compilación de su proyecto. En cambio, reduce la maquinaria personalizada necesaria para conectar los dos.

Simplificar: expresar lo que la tubería necesita hacer

Antes de la CLI de Unity, la mayoría de los pipelines de CI lanzaban el ejecutable del Editor de Unity directamente. Un comando de prueba simplificado podría verse así:

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 -

No hay nada inherentemente malo en este enfoque. El desafío es todo lo que tiene que pasar a su alrededor.

La tubería tiene que saber dónde está instalado el Editor. Otro script o imagen de máquina debe asegurar que la versión solicitada esté presente. El corredor también debe tener los módulos de plataforma correctos, la configuración de licencia y las variables de entorno. Los ejecutores de Windows, macOS y Linux pueden necesitar rutas y lógica de configuración ligeramente diferentes.

El comando ejecuta las pruebas, pero la tubería a su alrededor posee muchos detalles de implementación específicos de Unity.

Con Unity CLI, el mismo paso se puede expresar en términos de su intención:

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

Esto le dice a la tubería que ejecute las pruebas de EditMode del proyecto y escriba los resultados en un archivo XML de NUnit. Con --allow-install, la CLI puede leer la versión de Unity requerida por el proyecto e instalarla si es necesario. El proyecto, en lugar de la máquina de compilación, se convierte en la fuente de verdad de qué versión del Editor usar.

Los edificios siguen el mismo patrón. Anteriormente, una compilación podría invocar el Editor directamente:

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

Con Unity CLI, la compilación es más fácil de leer:

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

Su método existente Builder.PerformBuild puede seguir siendo responsable de las partes de la compilación que son específicas de su proyecto: seleccionar escenas, aplicar configuraciones de compilación, establecer símbolos de scripting, asignar información de versión o ejecutar validaciones específicas del estudio.

La CLI simplifica la automatización en torno a ese método. La configuración de CI ya no necesita saber tanto sobre la localización y el lanzamiento del Editor.

Junto, un trabajo de CI puede ir de un ejecutor fresco a una compilación probada con una corta secuencia de comandos:

# 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

Alternativamente, los comandos de prueba y compilación pueden usar --allow-install, eliminando la necesidad de un paso de instalación de Editor separado cuando el proyecto debe determinar la versión.

El cambio importante no es simplemente que los comandos son más cortos. Es que comunican lo que el trabajo está tratando de lograr. Alguien que lea el pipeline puede ver dónde está instalado Unity, dónde se ejecutan las pruebas y dónde se produce la compilación sin tener que decodificar una colección de rutas del Editor y banderas de modo lote.

Todavía habrá otras partes en una tubería de producción. Tu proveedor de CI todavía extrae el repositorio, inyecta secretos, restaura cachés, publica informes de prueba y sube artefactos. La CLI de Unity da a esos sistemas una forma más simple y consistente de manejar los pasos específicos de Unity.

Mejorar: eliminar el riesgo de la tubería

Una tubería más simple es más fácil de leer y mantener, pero la simplificación es solo parte del beneficio. Al mover la configuración y ejecución de Unity detrás de una CLI consistente, los equipos también pueden abordar varias fuentes comunes de riesgo en CI/CD.

El corredor tiene la versión incorrecta del Editor

Un pipeline que depende de una máquina preconfigurada también depende de que esa máquina permanezca configurada correctamente. Alguien puede actualizar un Editor, eliminar un módulo o cambiar una ruta de instalación. Un corredor de reemplazo puede parecer idéntico en el panel de control de CI mientras es sutilmente diferente por dentro.

Esas diferencias pueden ser difíciles de detectar. La configuración del pipeline no ha cambiado y el proyecto no ha cambiado, pero la compilación se comporta de manera diferente de repente porque la máquina lo ha hecho.

Unity CLI permite que el trabajo declare el Editor y los módulos que necesita:

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

O el trabajo puede usar --allow-install y dejar que ProjectVersion.txt del proyecto determine el Editor requerido.

Esto convierte el entorno de compilación en parte de la canalización en lugar de una propiedad no documentada del ejecutor. Una rama que actualiza Unity puede traer ese requisito a CI con ella en lugar de esperar a que un ingeniero de compilación actualice cada imagen de ejecutor.

También hace que los ejecutores efímeros sean más prácticos. Un nuevo corredor no necesita comenzar la vida como una máquina de construcción de Unity cuidadosamente preparada. Puede instalar la CLI y aprovisionar el entorno requerido como parte del trabajo.

CI se comporta de manera diferente a las máquinas de desarrollo

Los scripts específicos del proveedor pueden crear una brecha entre el desarrollo local y CI. Cuando un trabajo falla, un desarrollador puede recibir un gran comando de Editor que contiene rutas y opciones que solo tienen sentido en el ejecutor de compilación.

Reproducir ese fallo localmente requiere traducir el script de CI a algo que funcione en la máquina del desarrollador.

Unity CLI reduce esa brecha porque el mismo comando se puede usar en ambos lugares:

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

El entorno de CI todavía tendrá diferencias, como secretos, licencias y publicación de artefactos, pero el punto de entrada orientado a Unity se mantiene igual.

Eso facilita investigar un trabajo fallido. Un desarrollador puede copiar el comando de prueba o de compilación, ejecutarlo desde el directorio del proyecto y comenzar a reproducir el problema sin reconstruir primero la invocación del Editor del ejecutor.

Los scripts envolventes personalizados se convierten en infraestructura propia

Muchos estudios tienen scripts que localizan instalaciones de Unity, traducen objetivos de compilación en argumentos del Editor, transmiten registros, interpretan códigos de salida y mueven los resultados de las pruebas al directorio correcto.

Estos scripts generalmente se crean por buenas razones. Con el tiempo, sin embargo, se convierten en otra capa de infraestructura que necesita ser probada y mantenida. También pueden estar duplicados entre proyectos o reescritos para cada proveedor de CI.

Unity CLI proporciona un punto de entrada para operaciones comunes:

unity install
unity test
unity build

Esto no significa que cada proyecto sea idéntico. Los estudios pueden y deben mantener la lógica específica del proyecto donde le corresponde. Un método de compilación en C# puede seguir definiendo cómo se construye un juego, mientras que la CLI proporciona una forma estándar para que la automatización lo invoque.

El límite se vuelve más claro: el proyecto es dueño de la compilación, mientras que el trabajo de CI es dueño de cuándo y dónde se ejecuta esa compilación.

Los fallos son difíciles de diagnosticar

Un trabajo fallido de Unity puede generar una gran cantidad de salida. Si los resultados de las pruebas existen solo en el registro del Editor, los desarrolladores pueden necesitar descargar y buscar ese registro para encontrar el fallo real. En un ejecutor efímero, los archivos de diagnóstico útiles también pueden desaparecer tan pronto como finaliza el trabajo.

unity test puede escribir informes XML de NUnit directamente:

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

Los proveedores de CI pueden ingerir ese informe y mostrarlo. También utiliza códigos de salida definidos y mantiene registros específicos de la CLI, ayudando a la automatización a distinguir los fallos de las pruebas de otros problemas. (docs.unity.com)

El resultado no es meramente más registro. Es más útil el resultado en los lugares donde los desarrolladores ya miran: el registro de trabajo, el informe de prueba y los artefactos de compilación.

Una tubería puede preservar las salidas clave de cada ejecución:

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

Esto facilita la operación del pipeline a escala. Los desarrolladores pueden investigar por sí mismos los fallos de pruebas rutinarias, mientras que los ingenieros de compilación conservan los registros detallados necesarios para diagnosticar problemas de infraestructura.

Las credenciales y licencias sobreviven al trabajo

Los ejecutores de compilación a menudo necesitan acceso a material sensible: credenciales de cuenta de servicio, almacenes de claves de Android, contraseñas de firma o archivos de licencia sin conexión. Las máquinas de larga duración pueden retener esos archivos o cambios de entorno entre compilaciones a menos que la tubería realice una limpieza cuidadosa.

Un flujo de trabajo centrado en la CLI encaja naturalmente con los almacenes de secretos y los ejecutores efímeros. Las credenciales pueden inyectarse como variables de entorno, ser utilizadas por el trabajo y descartarse cuando se elimina el ejecutor.

Firmar archivos puede seguir el mismo patrón. Por ejemplo, un almacén de claves de Android se puede almacenar como un secreto de CI codificado en base64, decodificado solo para la compilación y eliminado durante la limpieza:

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

La concesión de licencias también puede convertirse en una parte explícita del ciclo de vida del trabajo. El corredor activa una licencia antes de realizar trabajo de Unity y la devuelve cuando finaliza el trabajo:

unity license activate --floating

# Run tests and produce builds

unity license return

Unity CLI soporta flujos de trabajo de activación y retorno, incluidas opciones de licencia flotante y sin conexión. (docs.unity.com)

Para los *runners* efímeros, el comando de retorno debe colocarse en un paso de limpieza incondicional para que se ejecute incluso si una prueba o compilación falla. Eso evita que los trabajos fallidos dejen asientos reservados y afecten las compilaciones posteriores.

La tubería está vinculada a un proveedor de CI

Cada plataforma de CI tiene su propio lenguaje de configuración, pero el trabajo de Unity dentro del trabajo no debería tener que cambiar cuando el proveedor lo haga.

Un pipeline puede usar GitHub Actions, GitLab CI, Jenkins, Buildkite, TeamCity o un sistema de orquestación interno. Esos sistemas seguirán gestionando la programación, secretos, cachés y artefactos. Los comandos que prueban y construyen el proyecto de Unity pueden permanecer consistentes:

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

Esto no hace que la migración a CI sea sencilla, pero reduce la cantidad de automatización específica de Unity que debe reescribirse. El proveedor ejecuta el comando; la CLI de Unity maneja la interacción con Unity.

Esa consistencia también es útil en varios proyectos. Los equipos pueden establecer patrones de canalización comunes sin requerir que cada proyecto comparta la misma implementación de compilación interna.

En última instancia, Unity CLI no cambia lo que un buen pipeline de CI/CD necesita lograr. La tubería todavía tiene que aprovisionar su entorno, ejecutar pruebas, producir compilaciones, proteger credenciales, publicar resultados útiles y limpiar después de sí misma.

Qué cambios se necesitan en cuanto a cuánta maquinaria personalizada se necesita para que esos pasos funcionen con Unity.

En lugar de depender de rutas de Editor codificadas, ejecutores preconfigurados y scripts envolventes cada vez más complejos, los equipos pueden describir su intención utilizando un pequeño conjunto de comandos. El resultado es un *pipeline* que es más fácil de leer, más fácil de reproducir y menos dependiente del estado de una máquina de compilación en particular.

Utilice Unity CLI para simplificar la ruta desde un ejecutor limpio hasta una compilación probada y mejorar la fiabilidad de todo el proceso.