CICD Made Easier with Unity CLI

Os pipelines de CI/CD tendem a crescer organicamente. O que começa como um script que abre o Unity Editor e inicia uma compilação gradualmente assume mais responsabilidades: encontrar o executável correto do Editor, instalar módulos da plataforma, gerenciar licenças, coletar resultados de testes, lidar com credenciais de assinatura e limpar tudo quando o trabalho termina.

O resultado pode funcionar, mas pode ser difícil de entender e ainda mais difícil de reproduzir. O pipeline depende não apenas do código em seu arquivo de configuração, mas também de tudo o que estiver instalado e configurado no executor.

A nova CLI do Unity oferece uma maneira mais simples de automatizar o trabalho com o Unity. Isso proporciona aos sistemas de compilação um comando unitário consistente para instalar editores, executar testes, gerar builds e gerenciar licenças. Ele foi projetado para fluxos de trabalho de terminal e automação, incluindo instalação não interativa, saída estruturada e códigos de saída claros. ( unity.com )

Isso não substitui seu provedor de CI nem o código de compilação do seu projeto. Em vez disso, reduz a necessidade de maquinário personalizado para conectar os dois.

Simplifique: expresse o que o pipeline precisa fazer.

Antes do Unity CLI, a maioria dos pipelines de CI executava o arquivo executável do Unity Editor diretamente. Um comando de teste simplificado poderia ser assim:

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 -

Não há nada inerentemente errado com essa abordagem. O desafio reside em tudo o que precisa acontecer em torno disso.

O pipeline precisa saber onde o Editor está instalado. Outro script ou imagem de máquina precisa garantir que a versão solicitada esteja presente. O programa de execução também deve ter os módulos de plataforma, a configuração de licenciamento e as variáveis ​​de ambiente corretas. Os executores para Windows, macOS e Linux podem exigir caminhos e lógica de configuração ligeiramente diferentes.

O comando executa os testes, mas o pipeline em torno dele contém muitos detalhes de implementação específicos do Unity.

Com a Unity CLI, a mesma etapa pode ser expressa em termos de sua intenção:

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

Isso instrui o pipeline a executar os testes EditMode do projeto e gravar os resultados em um arquivo XML do NUnit. Com a opção --allow-install , a CLI pode ler a versão do Unity exigida pelo projeto e instalá-la, se necessário. O projeto, e não a máquina de compilação, torna-se a fonte de verdade para determinar qual versão do Editor deve ser usada.

As construções seguem o mesmo padrão. Anteriormente, uma compilação podia invocar o Editor diretamente:

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

Com o Unity CLI, a compilação fica mais fácil de ler:

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

Seu método Builder.PerformBuild existente pode continuar sendo responsável pelas partes da compilação que são específicas do seu projeto: selecionar cenas, aplicar configurações de compilação, definir símbolos de script, atribuir informações de versão ou executar validação específica do estúdio.

A interface de linha de comando (CLI) simplifica a automação relacionada a esse método. A configuração de CI não precisa mais saber tanto sobre como localizar e iniciar o Editor.

Em resumo, um trabalho de CI pode passar de uma execução limpa para uma versão testada com uma pequena sequência 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, os comandos de teste e compilação podem usar --allow-install , eliminando a necessidade de uma etapa de instalação separada do Editor quando o projeto deve determinar a versão.

A mudança importante não é simplesmente o fato de os comandos serem mais curtos. Trata-se de comunicar o que o trabalho pretende realizar. Quem lê o pipeline consegue ver onde o Unity está instalado, onde os testes são executados e onde a compilação é gerada, sem precisar decodificar uma coleção de caminhos do Editor e sinalizadores do modo em lote.

Ainda haverá outras etapas em um processo de produção. Seu provedor de CI ainda faz o checkout do repositório, injeta segredos, restaura caches, publica relatórios de teste e carrega artefatos. A CLI da Unity oferece a esses sistemas uma maneira mais simples e consistente de lidar com as etapas específicas da Unity.

Melhorar: eliminar os riscos do oleoduto

Um pipeline mais simples é mais fácil de ler e manter, mas a simplificação é apenas parte do benefício. Ao mover a configuração e a execução do Unity para trás de uma CLI consistente, as equipes também podem lidar com diversas fontes comuns de risco em CI/CD.

O corredor tem a versão errada do Editor.

Um pipeline que depende de uma máquina pré-configurada também depende de que essa máquina permaneça configurada corretamente. Alguém pode atualizar um editor, remover um módulo ou alterar o caminho de instalação. Um executor substituto pode parecer idêntico no painel de controle de integração contínua, embora apresente diferenças sutis em sua estrutura interna.

Essas diferenças podem ser difíceis de detectar. A configuração do pipeline não mudou, e o projeto também não, mas a compilação de repente passou a se comportar de forma diferente porque a máquina mudou.

A CLI do Unity permite que a tarefa declare o Editor e os módulos de que precisa:

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

Ou então, a tarefa pode usar a opção --allow-install e deixar que o arquivo ProjectVersion.txt do projeto determine o editor necessário.

Isso faz com que o ambiente de compilação faça parte do pipeline, em vez de ser uma propriedade não documentada do executor. Uma branch que atualiza o Unity pode incorporar esse requisito na CI, em vez de esperar que um engenheiro de compilação atualize cada imagem do runner.

Isso também torna os corredores efêmeros mais práticos. Um novo jogo de corrida não precisa começar sua vida como uma máquina de compilação Unity meticulosamente preparada. Ele pode instalar a CLI e provisionar o ambiente necessário como parte da tarefa.

A integração contínua (CI) se comporta de maneira diferente das máquinas de desenvolvimento.

Scripts específicos do provedor podem criar uma lacuna entre o desenvolvimento local e a integração contínua (CI). Quando uma tarefa falha, o desenvolvedor pode receber um comando extenso do Editor contendo caminhos e opções que só fazem sentido no ambiente de execução da compilação.

Reproduzir essa falha localmente exige traduzir o script de CI para algo que funcione na máquina do desenvolvedor.

A CLI do Unity reduz essa diferença porque o mesmo comando pode ser usado em ambos os lugares:

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

O ambiente de CI ainda terá diferenças — como segredos, licenciamento e publicação de artefatos — mas o ponto de entrada voltado para o Unity permanece o mesmo.

Isso facilita a investigação de um trabalho malsucedido. Um desenvolvedor pode copiar o comando de teste ou de compilação, executá-lo a partir do diretório do projeto e começar a reproduzir o problema sem primeiro reconstruir a invocação do Editor do executor.

Scripts de encapsulamento personalizados tornam-se infraestrutura por si só.

Muitos estúdios possuem scripts que localizam instalações do Unity , traduzem os alvos de compilação em argumentos do Editor, transmitem logs, interpretam códigos de saída e movem os resultados dos testes para o diretório correto.

Esses scripts geralmente são criados por bons motivos. Com o tempo, porém, elas se tornam mais uma camada de infraestrutura que precisa ser testada e mantida. Eles também podem ser duplicados em diferentes projetos ou reescritos para cada provedor de CI.

A CLI do Unity fornece um ponto de entrada único para operações comuns:

unity install
unity test
unity build

Isso não significa que todos os projetos se tornem idênticos. Os estúdios podem — e devem — manter a lógica específica de cada projeto onde ela pertence. O método de compilação do AC# pode continuar definindo como um jogo é construído, enquanto a CLI fornece uma maneira padrão para a automação invocá-lo.

A delimitação fica mais clara: o projeto é responsável pela compilação, enquanto a tarefa de CI é responsável por quando e onde essa compilação será executada.

As falhas são difíceis de diagnosticar.

Uma tarefa do Unity que falha pode gerar uma grande quantidade de resultados. Se os resultados dos testes existirem apenas no registro do Editor, os desenvolvedores podem precisar baixar e pesquisar esse registro para encontrar a falha real. Em um sistema de execução efêmero, arquivos de diagnóstico úteis também podem desaparecer assim que a tarefa for concluída.

O Unity Test pode escrever relatórios XML do NUnit diretamente:

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

Os provedores de CI podem ingerir esse relatório e exibi-lo. Ele também usa códigos de saída definidos e mantém logs específicos da CLI, ajudando a automação a distinguir falhas de teste de outros problemas. ( docs.unity.com )

O resultado não é simplesmente mais registro de dados. É uma saída mais útil nos locais onde os desenvolvedores já procuram: o registro de tarefas, o relatório de testes e os artefatos de compilação.

Um pipeline pode preservar os principais resultados de cada execução:

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

Isso facilita a operação do oleoduto em grande escala. Os desenvolvedores podem investigar falhas de testes de rotina por conta própria, enquanto os engenheiros de compilação mantêm os registros detalhados necessários para diagnosticar problemas de infraestrutura.

As credenciais e licenças permanecem válidas mesmo após o término do emprego.

Os programas de compilação geralmente precisam acessar material sensível: credenciais de contas de serviço, keystores do Android , senhas de assinatura ou arquivos de licença offline. Máquinas de longa duração podem reter esses arquivos ou alterações de ambiente entre compilações, a menos que o pipeline execute uma limpeza cuidadosa.

Um fluxo de trabalho com foco na linha de comando (CLI) se encaixa naturalmente com armazenamentos secretos e executores efêmeros. As credenciais podem ser injetadas como variáveis ​​de ambiente, usadas pela tarefa e descartadas quando o executor é removido.

A assinatura de arquivos pode seguir o mesmo padrão. Por exemplo, um keystore do Android pode ser armazenado como um segredo CI codificado em base64, decodificado apenas durante a compilação e excluído durante a desmontagem:

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

O licenciamento também pode se tornar uma parte explícita do ciclo de vida do trabalho. O executor ativa uma licença antes de realizar o trabalho no Unity e a devolve quando o trabalho termina:

unity license activate --floating

# Run tests and produce builds

unity license return

A CLI do Unity oferece suporte a fluxos de trabalho de ativação e devolução, incluindo opções de licenciamento flutuante e offline. ( docs.unity.com )

Para executores efêmeros, o comando de retorno deve ser colocado em uma etapa de desmontagem incondicional para que seja executado mesmo quando um teste ou compilação falhar. Isso impede que trabalhos com falha deixem as vagas reservadas e afetem builds posteriores.

O pipeline está vinculado a um provedor de CI.

Cada plataforma de CI possui sua própria linguagem de configuração, mas o trabalho do Unity dentro da tarefa não deve precisar ser alterado quando o provedor for alterado.

Um pipeline pode usar GitHub Actions, GitLab CI, Jenkins, Buildkite, TeamCity ou um sistema de orquestração interno. Esses sistemas continuarão a gerenciar agendamentos, segredos, caches e artefatos. Os comandos que testam e compilam o projeto Unity podem permanecer consistentes:

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

Isso não torna a migração para CI fácil, mas reduz a quantidade de automação específica do Unity que precisa ser reescrita. O provedor executa o comando; a CLI da Unity lida com a interação com a Unity.

Essa consistência também é útil em diferentes projetos. As equipes de desenvolvimento podem estabelecer padrões de pipeline comuns sem exigir que todos os projetos compartilhem a mesma implementação de compilação interna.

Em última análise, a CLI da Unity não altera o que um bom pipeline de CI/CD precisa realizar. O pipeline ainda precisa provisionar seu ambiente, executar testes, gerar builds, proteger credenciais, publicar resultados úteis e realizar a limpeza necessária.

O que muda é a quantidade de ferramentas personalizadas necessárias para que essas etapas funcionem com o Unity.

Em vez de depender de caminhos de editor predefinidos, executores pré-configurados e scripts de encapsulamento cada vez mais complexos, as equipes podem descrever sua intenção usando um pequeno conjunto de comandos. O resultado é um pipeline mais fácil de ler, mais fácil de reproduzir e menos dependente do estado de uma máquina de compilação específica.

Use a CLI do Unity para simplificar o caminho de uma execução limpa a uma versão testada — e melhorar a confiabilidade de tudo ao longo do processo.