Run custom scripts during the build process

Follow this workflow to run custom scripts before and after the build process.

Read time 5 minutes

Last updated 4 months ago

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.

Note

Set the line endings for your shell scripts to Unix, especially when you execute line commands with URLs.

Prerequisites

The following reference pages give more context to this workflow:

A list of installed software.
A list of available environment variables.
An overview of the advanced build settings, including script hooks and when Unity Build Automation runs them.

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. You can set pre-export and post-export methods in the build target’s Advanced settings in the Cloud dashboard.

Important

The

UnityEngine.CloudBuild.BuildManifestObject

class is only available when running in Build automation, not locally. To compile your code locally, wrap your pre-export and post-export methods in an #if UNITY_CLOUD_BUILD block.

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. UBA calls the pre-export method in the Unity Editor context before exporting the Unity player.

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.

UBA calls the post-export method in the Unity Editor context, after UBA exports the Unity player, AssetBundles, and Addressables.

Custom scripting

#define

directives

Using Build Automation, you can create custom scripting #define directives. On the Unity 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, refer to Conditional Compilation.

Pre-build and post-build scripts

You need to reference your pre-build and post-build bash scripts in the build targets Advanced settings. You can use these scripts for custom pre and post processing:

UBA calls pre-build bash scripts after cloning the code in the build machine, and after restoring cache operations, but before UBA starts up Unity to run the build process.
UBA calls post-build bash scripts after the Unity Editor process completes, but before UBA uploads the generated artifacts.

Change node versions

NVM is installed on the build machines to let you change 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 versionnvm install 16.13.0nvm use 16.13.0## Output Node version usednode -vexit 0

Use 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 profilervm install ruby-3.3.0rvm ruby-3.3.0 do gem install fastlanervm ruby-3.3.0 do fastlane --helpexit 0

Note

It isn't recommended to change the Ruby system Ruby version with

rvm use NEW_RUBY_VERSION

and do it at your own risk.

Set 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

Note

UBA calls post-build bash scripts after UBA clones the code in the build machine and after restoring cache operations, but before you start the Unity Editor to run the build process.

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.

Note

If you pass a path that uses environment variables during a post-build script to a Windows executable, then you need to use the cygwin path.

Sample script to get the path to the player


#!/bin/bash#This is a sample that simply outputs the path to the build artifact.echo "START"PLAYER_PATH=$UNITY_PLAYER_PATH#If you use a Windows Builder and use the path to pass it to a native Windows application, you need to properly convert the cygwin player path to Windows format.if [[ "$BUILDER_OS" == "WINDOWS" ]]; thenPLAYER_PATH=$(cygpath -wa "$UNITY_PLAYER_PATH")fiecho "$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 of 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

"*****"

Warning

You must register the value with 'mask-value' before outputting it in the logs.

Example of 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 of 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

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Build Automation

DevOps

Build Automation REST API

Build Automation Editor Package

Build Automation

Run custom scripts during the build process

Prerequisites

Pre-export and post-export methods

Pre-export method name

Post-export method name

Custom scripting
`#define`
directives

Pre-build and post-build scripts

Change node versions

Use other Ruby versions

Set environment variables

Example of writing an environment variable to
`DEVOPS_ENV`

Access build artifacts in a post-build script

Sample script to get the path to the player

Mask values in logs

Example of masking a value

Example of masking a variable

Example of masking an environment variable