Configure a build

A build configuration defines the settings and requirements for creating a specific build of your project. A build configuration is a structured setup that determines how your project is compiled, packaged, and prepared for deployment across different platforms. Once a build configuration is created, you can run multiple build attempts against it. All the settings specified in the configuration, such as the platform, Unity version, and credentials automatically apply to every build attempt to ensure consistency and reproducibility across all builds.

To set up a build configuration:

  1. Sign in to the Unity Cloud Dashboard.
  2. Select DevOps > Build automation > Configurations.

Prerequisites

Before you set up your first build configuration, ensure your project’s source control settings are configured. This step is required for your first configuration.

Select Get started to configure your source control.

Build Target Configuration - Configure Source Control

Choose a build configuration flow

You have two options to set up a new build configuration: quick target setup and target setup.

Quick target setup

If you select Quick target setup, the dashboard displays the basic configurations required to configure a build target for each platform. If you don’t want to configure advanced settings for your build target, select Quick target setup.

Build Target Configuration - Quick target setup

Target setup

When you select Target setup, you first set up the basic settings required for launching your build target. Then, you can either save your configuration or move to the advanced settings.

Build Target Configuration - Advanced settings

Basic Info

The Basic Info section includes fields to define core settings for your build:

SettingDescription
Target nameSet a unique name for the build target configuration.
BranchChoose the branch that Build Automation will pull from.
Project subfolder path (optional)Specify the folder that contains the Assets and ProjectSettings if they’re not in the repository’s root.
Unity versionSelect the Unity version you use. The Unity version controls the availability of several advanced settings such as builder operating system and version, and headless mode.
Auto detect Unity versionEnable for Unity Build Automation to detect the Unity version from ProjectSettings/ProjectVersion.txt in your project. Ensure to include this file in your source control.
Builder Operating System and VersionSelect the OS and version for your build machine. This is influenced by your platform. Refer to the Supported platforms on each builder OS for more information.
Xcode version (for macOS builders only)Select Default to use the default Xcode version for the selected OS. This option appears when you select a macOS builder operating system. Refer to the Available Xcode versions guide for supported versions.
Unity Editor architecture (for macOS builders only)Specify the Unity Editor architecture for builds that run on a silicon-based operating system.
Android SDK version (for Android builds only)Set the Android SDK version to build the Unity project with. Refer to the Android SDK to Unity versions compatibility guide for more information.

Build Target Configuration - Basic Info

Builder Configuration

Select the machine specifications for your build. The appropriate settings depend on your project’s complexity and platform requirements. For more details about builder configurations refer to Choose a machine specification.

Credentials

The Credentials section allows you to provide the credentials Build Automation uses to sign your build to ensure the security and integrity of your build artifacts. Provide the required credentials, such as keystores for Android or signing certificates for macOS.

Scheduling

The Scheduling section enables you to automate build triggers and set recurring build schedules.

SettingDescription
Auto-buildAutomatically start builds when changes are detected in the repository.
Auto-cancelAutomatically cancel pending builds if a new build triggers.
Build scheduleConfigure a repeating build schedule with options such as interval, date, and time.

For more details, refer to Run builds automatically.

Android configurations

Additional build settings are available when you select Android as the target platform.

In the Basic Info section of the target configuration, the first setting is the Android SDK version. Use this setting to select the preferred Android SDK version, which depends on the selected Unity version. For more information, refer to the Android SDK to Unity versions compatibility guide.

The remaining Android specific settings are in Advanced Settings under Platform specific settings (Android).

SettingDescription
Build app bundles (.aab) instead of an APKAn Android App Bundle is an upload format that includes all your app's compiled code and resources, but defers APK generation and signing to Google Play. You must also use the Gradle build system. Refer to Android App Bundles documentation for more information.
Build asset packsBuild asset packs are only available when you build app bundles. If you enable this option, then Unity Build Automation uses Google Play's build method from the Google Play Unity Plugin to build an App Bundle with Asset Packs. You need to install the plugin in your project. You must also programmatically configure Asset Packs in a Pre-Build script and call AssetPackConfigSerializer.SaveConfig method. For more information, refer to Android Play Asset Delivery documentation.
Make split binary application buildsThis setting sets the PlayerSettings.Android.useAPKExpansionFiles flag. Refer to Android Support for APK expansion files (OBB) documentation for more information. If you enable the Build Asset Packs option, Unity Build Automation ignores this option.

Build Target Configuration - Android Settings

Universal Windows Platform configurations

Additional build settings are available when the selected target platform is Universal Windows Platform (UWP). These settings allow for fine-grained control over how you build the UWP application and how you configure target devices.

For comprehensive information about UWP settings, refer to the UWP Build Settings documentation.

The Basic Info section of the target configuration includes the following UWP-specific options:

SettingDescription
Visual Studio versionDefines the version of Visual Studio that used to build the UWP application. If you use Unity 2022.2 or earlier, the latest Visual Studio version is automatically selected regardless of this setting.
Windows SDK versionSets the Windows SDK version that the application targets when you build with Visual Studio. This depends on the selected Visual Studio version.
Build typeDetermines the type of UWP build output generated by Unity. The available options are: Executable Only, D3D, or XAML. These options determine whether the output is a standalone executable or uses specific presentation frameworks.
Build configurationSpecifies the optimization level of the Visual Studio project output. The options include: Debug, Release (default), and Master. These settings impact the profiling and performance of the final output.
Target device familyDefines the UWP device families the application supports. By default, this option is set to Universal and targets all supported devices. You can also select specific families, such as Desktop, Xbox, HoloLens, or IoT. Refer to WSATargetFamily documentation for more information.

Build Target Configuration - UWP Basic Settings

The Advanced Settings of the target configuration include additional UWP-specific options:

SettingDescription
Application CapabilitiesSpecifies the capabilities for the system resources and features that your app expects to use. Refer to the capabilities properties documentation for more details.
Executable-only CPU architectureOnly available when you set the build type to Executable Only. Determines the CPU architecture that the output executable will support. If you don't provide a value, it defaults to x64.
Targeted CPU platformOnly available when you set the build type to D3D or XAML. Sets the AppxBundlePlatforms property, which specifies the targeted CPU architecture for the output. If you don't provide a value, it defaults to x64.

Build Target Configuration - UWP Advanced Settings