CICD Made Easier with Unity CLI

Les pipelines CI/CD ont tendance à croître de manière organique. Ce qui commence comme un script qui ouvre l'éditeur Unity et lance une construction prend progressivement plus de responsabilités : trouver l'exécutable éditeur correct, installer les modules de plateforme, gérer les licences, collecter les résultats des tests, gérer les informations d'identification de signature et tout nettoyer lorsque le travail est terminé.

Le résultat peut fonctionner, mais il peut être difficile à comprendre et encore plus difficile à reproduire. Le pipeline dépend non seulement du code de son fichier de configuration, mais aussi de tout ce qui est installé et configuré sur le runner.

Le nouveau CLI Unity fournit une manière plus simple pour l'automatisation de travailler avec Unity. Il donne aux systèmes de construction une commande unity cohérente pour installer les éditeurs, exécuter des tests, produire des builds et gérer les licences. Il est conçu pour les flux de travail en terminal et d'automatisation, y compris l'installation non interactive, la sortie structurée et des codes de sortie clairs. (unity.com)

Ceci ne remplace pas votre fournisseur de CI ni le code de construction de votre projet. Au lieu de cela, cela réduit la machinerie personnalisée nécessaire pour connecter les deux.

Simplifier : exprimer ce que le pipeline doit faire

Avant le CLI Unity, la plupart des pipelines CI lançaient directement l'exécutable de l'éditeur Unity. Une commande de test simplifiée pourrait ressembler à ceci :

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 -

Il n'y a rien d'intrinsèquement mauvais dans cette approche. Le défi est tout ce qui doit se passer autour.

Le pipeline doit savoir où l'Éditeur est installé. Un autre script ou une autre image machine doit s'assurer que la version demandée est présente. Le coureur doit également disposer des bons modules de plateforme, de la configuration de licence et des variables d'environnement. Les exécuteurs Windows, macOS et Linux peuvent avoir besoin de chemins et de logiques de configuration légèrement différents.

La commande exécute les tests, mais le pipeline qui l'entoure possède beaucoup de détails d'implémentation spécifiques à Unity.

Avec Unity CLI, la même étape peut être exprimée en termes de son intention :

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

Ceci indique au pipeline d'exécuter les tests EditMode du projet et d'écrire les résultats dans un fichier XML NUnit. Avec --allow-install, l'interface en ligne de commande peut lire la version de Unity requise par le projet et l'installer si nécessaire. Le projet, plutôt que la machine de construction, devient la source de vérité pour la version d'éditeur à utiliser.

Les constructions suivent le même modèle. Auparavant, une construction pouvait invoquer l'Éditeur directement :

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

Avec l'Unity CLI, la construction est plus facile à lire :

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

Votre méthode existante Builder.PerformBuild peut rester responsable des parties de la construction qui sont spécifiques à votre projet : sélection des scènes, application des paramètres de construction, définition des symboles de script, attribution des informations de version ou exécution de validations spécifiques au studio.

L'interface en ligne de commande simplifie l'automatisation autour de cette méthode. La configuration CI n'a plus besoin de savoir autant sur la localisation et le lancement de l'Éditeur.

Ensemble, un job CI peut passer d'un runner vierge à une build testée avec une courte séquence de commandes :

# 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

Alternativement, les commandes de test et de construction peuvent utiliser --allow-install, éliminant le besoin d'une étape d'installation séparée de l'Éditeur lorsque le projet doit déterminer la version.

Le changement important n'est pas simplement que les commandes sont plus courtes. C'est qu'ils communiquent ce que le travail essaie d'accomplir. Quelqu'un lisant le pipeline peut voir où Unity est installé, où les tests s'exécutent et où la construction est produite sans avoir à décoder une collection de chemins d'éditeur et de drapeaux en mode lot.

Il y aura encore d'autres parties dans un pipeline de production. Votre fournisseur CI télécharge toujours le dépôt, injecte des secrets, restaure les caches, publie les rapports de test et télécharge les artefacts. L'interface en ligne de commande Unity donne à ces systèmes une manière plus simple et plus cohérente de gérer les étapes spécifiques à Unity.

Améliorer : supprimer le risque du pipeline

Un pipeline plus simple est plus facile à lire et à maintenir, mais la simplification n'est qu'une partie du bénéfice. En déplaçant la configuration et l'exécution de Unity derrière une CLI cohérente, les équipes peuvent également résoudre plusieurs sources courantes de risque en CI/CD.

Le coureur a la mauvaise version d'Éditeur

Un pipeline qui dépend d'une machine préconfigurée dépend également du fait que cette machine reste correctement configurée. Quelqu'un peut mettre à jour un Éditeur, supprimer un module ou changer un chemin d'installation. Un coureur de remplacement peut paraître identique dans le tableau de bord CI tout en étant subtilement différent en dessous.

Ces différences peuvent être difficiles à repérer. La configuration du pipeline n'a pas changé, et le projet n'a pas changé, mais la construction se comporte soudainement différemment parce que la machine l'a fait.

L'interface en ligne de commande de Unity permet au job de déclarer l'Éditeur et les modules dont il a besoin :

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

Ou le job peut utiliser --allow-install et laisser le ProjectVersion.txt du projet déterminer l'Éditeur requis.

Ceci fait de l'environnement de construction une partie du pipeline plutôt qu'une propriété non documentée du lanceur. Une branche qui met à jour Unity peut apporter cette exigence dans CI avec elle au lieu d'attendre qu'un ingénieur de construction mette à jour chaque image de runner.

Cela rend également les exécuteurs éphémères plus pratiques. Un nouveau coureur n'a pas besoin de commencer sa vie comme une machine de construction Unity soigneusement préparée. Il peut installer l'interface en ligne de commande et provisionner l'environnement requis dans le cadre de la tâche.

CI se comporte différemment des machines de développement

Les scripts spécifiques au fournisseur peuvent créer un fossé entre le développement local et l'intégration continue. Lorsqu'un job échoue, un développeur peut recevoir une grande commande Éditeur contenant des chemins et des options qui n'ont de sens que sur le lanceur de construction.

Reproduire cette défaillance localement nécessite de traduire le script CI en quelque chose qui fonctionne sur la machine du développeur.

Unity CLI réduit cet écart car la même commande peut être utilisée dans les deux endroits :

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

L'environnement CI aura toujours des différences — telles que les secrets, les licences et la publication d'artefacts — mais le point d'entrée côté Unity reste le même.

Cela facilite l'investigation d'un travail raté. Un développeur peut copier la commande de test ou de construction, l'exécuter depuis le répertoire du projet et commencer à reproduire le problème sans reconstruire d'abord l'invocation de l'Éditeur du lanceur.

Les scripts enveloppants personnalisés deviennent une infrastructure en soi

De nombreux studios ont des scripts qui localisent les installations Unity, traduisent les cibles de construction en arguments d'éditeur, diffusent les journaux, interprètent les codes de sortie et déplacent les résultats des tests dans le bon répertoire.

Ces scripts sont généralement créés pour de bonnes raisons. Avec le temps, cependant, ils deviennent une autre couche d'infrastructure qui doit être testée et maintenue. Ils peuvent également être dupliqués entre projets ou réécrits pour chaque fournisseur CI.

L'interface en ligne de commande de Unity fournit un point d'entrée unique pour les opérations courantes :

unity install
unity test
unity build

Cela ne signifie pas que chaque projet devient identique. Les studios peuvent — et doivent — conserver la logique spécifique au projet là où elle doit se trouver. Une méthode de construction C# peut continuer à définir comment un jeu est construit, tandis que l'interface de ligne de commande fournit une manière standard pour l'automatisation de l'invoquer.

La frontière devient plus claire : le projet possède la construction, tandis que le job CI possède quand et où cette construction s'exécute.

Les pannes sont difficiles à diagnostiquer

Un travail Unity échoué peut générer une grande quantité de sortie. Si les résultats des tests n'existent que dans le journal de l'Éditeur, les développeurs pourraient avoir besoin de télécharger et de rechercher ce journal pour trouver la défaillance réelle. Sur un exécuteur éphémère, les fichiers de diagnostic utiles peuvent également disparaître dès que le travail est terminé.

unity test peut écrire des rapports XML NUnit directement :

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

Les fournisseurs CI peuvent ingérer ce rapport et l'afficher. Il utilise également des codes de sortie définis et maintient des journaux spécifiques à l'interface de ligne de commande, aidant l'automatisation à distinguer les échecs de test des autres problèmes. (docs.unity.com)

Le résultat n'est pas simplement plus de journalisation. C'est un résultat plus utile dans les endroits où les développeurs regardent déjà : le journal de travail, le rapport de test et les artefacts de construction.

Un pipeline peut conserver les sorties clés de chaque exécution :

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

Cela facilite l'exploitation du pipeline à grande échelle. Les développeurs peuvent eux-mêmes enquêter sur les échecs de tests de routine, tandis que les ingénieurs de construction conservent les journaux détaillés nécessaires pour diagnostiquer les problèmes d'infrastructure.

Les informations d'identification et les licences survivent au poste

Les exécuteurs de construction ont souvent besoin d'accéder à des informations sensibles : identifiants de compte de service, keystores Android, mots de passe de signature ou fichiers de licence hors ligne. Les machines de longue durée peuvent conserver ces fichiers ou changements d'environnement entre les constructions, à moins que le pipeline n'effectue un nettoyage minutieux.

Un flux de travail axé sur la ligne de commande s'intègre naturellement avec les magasins de secrets et les exécuteurs éphémères. Les informations d'identification peuvent être injectées en tant que variables d'environnement, utilisées par le job et supprimées lorsque le runner est supprimé.

La signature des fichiers peut suivre le même modèle. Par exemple, un keystore Android peut être stocké comme un secret CI encodé en base64, décodé uniquement pour la construction et supprimé pendant le nettoyage :

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 licence peut également devenir une partie explicite du cycle de vie du poste. Le coureur active une licence avant d'effectuer un travail Unity et la retourne lorsque le travail est terminé :

unity license activate --floating

# Run tests and produce builds

unity license return

L'interface de ligne de commande Unity prend en charge les flux de travail d'activation et de retour, y compris les options de licence flottante et hors ligne. (docs.unity.com)

Pour les exécuteurs éphémères, la commande de retour doit être placée dans une étape de nettoyage inconditionnelle afin qu'elle s'exécute même en cas d'échec d'un test ou d'une construction. Cela empêche les travaux échoués de laisser des sièges réservés et d'affecter les constructions ultérieures.

Le pipeline est lié à un fournisseur CI

Chaque plateforme CI a son propre langage de configuration, mais le travail Unity à l'intérieur du job ne devrait pas avoir à changer lorsque le fournisseur le fait.

Un pipeline peut utiliser GitHub Actions, GitLab CI, Jenkins, Buildkite, TeamCity ou un système d'orchestration interne. Ces systèmes continueront à gérer la planification, les secrets, les caches et les artefacts. Les commandes qui testent et construisent le projet Unity peuvent rester cohérentes :

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

Cela ne rend pas la migration CI aisée, mais cela réduit la quantité d'automatisation spécifique à Unity qui doit être réécrite. Le fournisseur exécute la commande ; l'interface de ligne de commande Unity gère l'interaction avec Unity.

Cette cohérence est également utile entre les projets. Les équipes peuvent établir des modèles de pipeline communs sans exiger que chaque projet partage la même implémentation de construction interne.

En fin de compte, Unity CLI ne change pas ce qu'un bon pipeline CI/CD doit accomplir. Le pipeline doit toujours provisionner son environnement, exécuter des tests, produire des builds, protéger les identifiants, publier des résultats utiles et faire le ménage après lui-même.

Quels changements sont nécessaires pour savoir combien de machinerie personnalisée est nécessaire pour faire fonctionner ces étapes avec Unity.

Au lieu de dépendre de chemins d'éditeur codés en dur, de lanceurs préconfigurés et de scripts enveloppants de plus en plus complexes, les équipes peuvent décrire leur intention à l'aide d'un petit ensemble de commandes. Le résultat est un pipeline plus facile à lire, plus facile à reproduire et moins dépendant de l'état d'une machine de construction particulière.

Utilisez l'interface de ligne de commande Unity pour simplifier le chemin d'un exécuteur propre à une version testée et améliorer la fiabilité de tout le processus.