TeamCity Unity plugin

[

The plugin supports building Unity projects on TeamCity.

Features

• Unity versions detection on build agents
• Unity build runner with smart completions
• Automatic discovery of Unity build steps
• Structured build log with problems highlighting
• Unity Editor tests reporting
• Unity build settings feature
• Unity as Agent tool
• Running Unity build step inside a container

Unity build settings feature

This TeamCity build feature allows to automatically activate and return Unity Editor license before build start and after build completion.

Also it allows to configure Unity cache server address in one place to use this setting within Unity build steps.

Download

You can download the plugin and install it as an additional TeamCity plugin.

Note: After installation, you need to restart TeamCity server by going to Administration => Diagnostics => Restart Server

Compatibility

The plugin is compatible with TeamCity 2018.1+ and was verified to work with Unity 2017+.

Configuration

The plugin automatically detects Editors installed via Unity Hub. Also it searches Editors in the PATH environment variable and in the following well-known directories:

• macOS: /Applications/Unity* and /Applications/Unity/Hub/Editor/*
• Linux: /opt/Unity*/~/Unity* and /opt/Unity/Hub/Editor/*/~/Unity/Hub/Editor/*
• Windows: %Program Files%/Unity* and %Program Files%/Unity/Hub/Editor/*

Note: you need to start TeamCity build agent under the same user account which is used for Unity Hub installation.

To add Unity installation located in custom path you could use UNITY_HOME environment variable, e.g. UNITY_HOME=C:\Tools\Unity_2018.1\. Multiple paths could be specified by using default path delimiter.

To search Unity installation directories in custom path matching Unity* pattern you could use UNITY_HINT_PATH environment variable, e.g. UNITY_HINT_PATH=C:\Tools. Multiple paths could be specified by using default path delimiter.

You may also install Unity as a TeamCity agent tool. See TeamCity Agent Tool Configuration for more information.

Agent configuration parameters

All detected Unity versions will be reported as build agent configuration parameters with the unity.path.%unityVersion% prefix. They could be found on the Agents -> "%agentName%" -> Agent Parameters -> Configuration Parameters page in TeamCity server UI.

Custom error logging settings

The runner allows overriding default error logging settings by using "Line statuses file" parameter where you could specify the path to configuration file. Example file contents:

<?xml version="1.0" encoding="UTF-8"?>
<lines>
  <line level="warning" message="warning CS\d+" />
  <line level="error" message="error CS\d+" />
</lines>

TeamCity Agent Tool Configuration

This plugin supports optionally installing Unity as a TeamCity agent tool.

Creating Tool Zip Archive

To create a tool zip file for Unity, do the following:

1. Locally install (or extract) the desired version of Unity along with any/all desired Target Support (Android, iOS, Xbox, etc.)
2. Zip the Editor folder + plugin descriptor into an archive named Unity-<version>.zip such as Unity-2018.4.9f1.zip It should look like this (for Windows):

   📁 Unity-2018.4.9f1.zip
   |- 📄 teamcity-plugin.xml
   |- 📂 Editor
   │  |- 📂 BugReporter
   │  |- 📂 Data
   │  |- 📂 locales
   │  |- 📄 Unity.exe
   │  |- ...
   

   Note that the archive structure may vary depending on the distributed binaries. For example, when packing for MacOS, the top-level folder inside the archive should be Unity.app.
3. Upload as a Unity Tool on the Administration > Tools page on TeamCity

NB!

• Due to the current limitation of TeamCity tool distribution, preserving file permissions for Unix-like platforms is only possible with additional configuration. Namely, a plugin descriptor should list all files in the archive which are needed to be executable after unpacking on an agent.

  An example of this list for MacOS tool descriptor might be:

  <executable-files>
     <include name='Unity.app/Contents/MacOS/Unity'/>
     <include name='Unity.app/Contents/Resources/PackageManager/Server/UnityPackageManager'/>
     ...
  </executable-files>

  Feel free to upvote TW-21673 issue to make it work out of the box.

• Agent environment must contain all the required global dependencies to make Unity work on a given OS.

Running Unity build step inside a container

This plugin is integrated with Container Wrapper extension. The integration works only with 2023.09 and above versions of TeamCity.

Common problems

Unmet requirements: Exists=>unity.path.xxx

This problem indicates that the Unity Editor installation was not found on any of build agent machines. Check that you have installed Editor on your build agents and machines were properly configured.

Build

This project uses Gradle as the build system. You can easily open it in IntelliJ IDEA or Eclipse.

Contributing

We appreciate all kinds of feedback, so please feel free to send a PR or submit an issue. For issues please consider opening related ticket in our YouTrack.

Documentation

• Changelog
• Maintainership