Run custom scripts during the build process#

Build Automation supports both pre build and post build custom scripts created by users. To use custom scripts, check these scripts into the source repository, and configure the relative path to the scripts from the root of the repository in the Advanced Settings of a build.

Pre-export and post-export methods#

Use the pre-export and post-export methods to trigger actions before and after your Unity project is built in the cloud. These methods must exist in classes in the Assets/Editor folder. If the Editor folder doesn’t exist in your directory, you can create one.

Pre-export method name#

To use a pre-export method, create a public static method in your Unity Project that contains the code you want to execute before the Unity Editor exports your project and after the Unity Editor script compilation phase.

public static void PreExport()

You can enable Build Automation to pass the build manifest of the current build to the pre-export method by specifying a BuildManifestObject object as a parameter in the method signature. You can then make changes to the Project or Player settings before you export the Project.

public static void PreExport(UnityEngine.CloudBuild.BuildManifestObject manifest)

When Unity Build Automation calls the method, it passes a BuildManifestObject object as an optional parameter with BuildManifestObject as the build manifest of the current build.

Post-export method name#

To use the post-export method, create a public static method in your Unity Project that contains the code you want executed after the Unity Editor exports your Project.

public static void PostExport(string exportPath)

When Unity Build Automation calls the method, it passes a string:

• For non-iOS build targets, the string contains the path to the exported Project.
• For iOS Projects, the string contains the path to the exported Xcode project. You can use the path to locate the exported Xcode Project to perform additional preprocessing before Xcode is called to complete the build process.

  Note: If you tag any methods in your code with the Unity PostProcessBuildAttribute, those methods are executed before any methods configured as post-export methods in Unity Build Automation.

Custom scripting #define directives#

Using Build Automation, you can create custom scripting #define directives. On the Unity Cloud Dashboard, go to the build target’s Advanced settings.

In the Scripting Define Symbols field, you can add your own custom scripting #define directives to the built-in selection available. For each build target, enter the names of the symbols you want to define. You can then use these symbols as the conditions in #if directives, just like the built-in symbols. For more information, see Conditional Compilation.

Change node versions#

NVM is installed on the build machines to let you switch to a different node version during the build process. The following sample script installs and switches to Node 16.13.0:

#!/usr/bin/env bash

## Source profile
. ~/.profile

## Install NVM modules and set version
nvm install 16.13.0
nvm use 16.13.0

## Output Node version used
node -v

exit 0

Using other Ruby versions#

RVM and gem are installed on the build machines to let you use different Ruby versions during the build process. The following sample script installs Ruby 3.3.0 and executes commands using DO so that it doesn't impact the system Ruby installation that's used by UBA tools.

#!/usr/bin/env bash

## Source profile
rvm install ruby-3.3.0
rvm ruby-3.3.0 do gem install fastlane
rvm ruby-3.3.0 do fastlane --help

exit 0

rvm install ruby-3.3.0 --with-openssl-dir=$(brew --prefix openssl@1.1)

Setting environment variables#

echo "{environment_variable_name}={value}" >> "$DEVOPS_ENV"

To make an environment variable available to the Unity build and your post-build scripts, define or update the environment variable and write this value to the DEVOPS_ENV environment file. The script that creates or updates the environment variable doesn't have access to the new value, but all subsequent processes will have access. The environment variable name is stored as the uppercase version of the name given (testenv becomes TESTENV). Only single line environment variables are supported.

Example of writing an environment variable to DEVOPS_ENV#

In the pre-build script set the environment variable.

echo "TEST_ENV=Sample environment variable" >> $DEVOPS_ENV

Then in the post-build script echo the environment variable.

echo $TEST_ENV

Access build artifacts in a post-build script#

You can access build artifacts for automatic upload to a storefront or to automate some part of the build process using a post-build script. If passing a path using environment variables during a post-build script to a Windows executable, then the cygwin path must be used.

Sample script to get the path to the player#

#!/bin/bash

#This is a sample that will simply output the path to the build artifact

echo "START"

PLAYER_PATH=$UNITY_PLAYER_PATH

#If we are using a Windows Builder and using the path to pass it to a native Windows application, we need to properly convert the cygwin player path to windows format

if [[ "$BUILDER_OS" == "WINDOWS" ]]; then
PLAYER_PATH=$(cygpath -wa "$UNITY_PLAYER_PATH")
fi

echo "$PLAYER_PATH"

Mask values in logs#

Masking a value prevents a string or variable from being printed in the log. Each masked value is replaced with *****, regardless of the value contents. You can pass an environment variable or raw value into the mask command.

To mask a string or environment variable, use the ::mask-value:: command.

echo "::mask-value::{value}"

Example: Masking a value#

To mask the value "SuperS3cretPassword!", set the ::mask-value:: command for the value:

echo "::mask-value::SuperS3cretPassword!"

When this is printed in the log, the output will be displayed as "*****".

Example: Masking a variable#

To mask the variable DB_PASSWORD or variable value "SuperS3cretPassword!", set the ::mask-value:: command for the variable:

DB_PASSWORD=SuperS3cretPassword!
echo "::mask-value::$DB_PASSWORD"

When either of these are printed to the log, the output will be displayed as "*****".

Example: Masking an environment variable#

Environment variables set with $DEVOPS_ENV can be masked. Set the value of the enviornment variable, mask it, and then output the value to the $DEVOPS_ENV file for use in other scripts.

DB_PASSWORD=SuperS3cretPassword!
echo "::mask-value::$DB_PASSWORD"
echo "DB_PASSWORD=$DB_PASSWORD" >> $DEVOPS_ENV