com.utilities.buildpipeline

A Build Pipeline utility package for the Unity Game Engine.

Installing

Requires Unity 2019.4 LTS or higher.

CI tests the current Unity streams on pull requests, and a monthly run covers the older lines.

The recommended installation method is though the unity package manager and OpenUPM.

Via Unity Package Manager and OpenUPM

Terminal

openupm add com.utilities.buildpipeline

Manual

• Open your Unity project settings
• Add the OpenUPM package registry:
  • Name: OpenUPM
  • URL: https://package.openupm.com
  • Scope(s):
    • com.utilities

• Open the Unity Package Manager window
• Change the Registry from Unity to My Registries
• Add the Utilities.BuildPipeline package

Via Unity Package Manager and Git url

• Open your Unity Package Manager
• Add package from git url: https://github.com/RageAgainstThePixel/com.utilities.buildpipeline.git#upm

Documentation

Example Usage

Create Github Action Workflow

Create a new workflow file in your Unity project repository at .github/workflows/build.yml with the following content:

name: unity-build

on:
  push:
    branches: ['main']
  pull_request:
    branches: ['*']
  workflow_dispatch: # Allows you to run this workflow manually from the Actions tab
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      # max-parallel: 2 # Use this if you're activating pro license with matrix
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        unity-versions: [2019.x, 2020.x, 2021.x, 2022.x, 6000.x]
        include: # for each os specify the build targets
          - os: ubuntu-latest
            build-target: StandaloneLinux64
          - os: windows-latest
            build-target: StandaloneWindows64
          - os: macos-latest
            build-target: StandaloneOSX

    steps:
      - uses: actions/checkout@v7

        # Installs the Unity Editor based on your project version text file
      - uses: RageAgainstThePixel/unity-setup@v3
        id: unity-setup # used to get project path output in later steps
        with:
          unity-version: ${{ matrix.unity-versions }}
          build-targets: ${{ matrix.build-target }}
          version-file: path/to/your/ProjectSettings/ProjectVersion.txt # optional, this step will attempt to auto detect if not provided

        # Activates the installation with the provided credentials
      - uses: RageAgainstThePixel/activate-unity-license@v3
        with:
          license: 'Personal' # Choose license type to use [ Personal, Professional ]
          username: ${{ secrets.UNITY_USERNAME }}
          password: ${{ secrets.UNITY_PASSWORD }}
          # serial: ${{ secrets.UNITY_SERIAL }} # Required for pro activations

      - uses: RageAgainstThePixel/unity-action@v4
        name: ${{ matrix.build-target }}-Validate
        with:
          log-name: ${{ matrix.build-target }}-Validate
          build-target: ${{ matrix.build-target }}
          project-path: ${{ steps.unity-setup.outputs.unity-project-path }}
          args: -quit -nographics -batchmode -executeMethod Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject -importTMProEssentialsAsset

      - uses: RageAgainstThePixel/unity-action@v4
        name: ${{ matrix.build-target }}-Build
        with:
          log-name: ${{ matrix.build-target }}-Build
          build-target: ${{ matrix.build-target }}
          project-path: ${{ steps.unity-setup.outputs.unity-project-path }}
          args: -quit -nographics -batchmode -executeMethod Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild ${{ matrix.build-args }}

Note

Embedded CI Logging in GitHub Actions and Azure DevOps can be disabled by adding the DISABLE_EMBEDDED_BUILD_PIPELINE_PLUGIN_LOGGING environment variable to the build step with a value of true or 1.

Executable Methods

These methods can be executed using the -executeMethod command line argument to validate, sync, and build the Unity project.

Method	Description
Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject	Validates the Unity Project assets by forcing a symbolic link sync and creates solution files.
Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.SyncSolution	Force Unity to update CSProj files and generates solution.
Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild	Start a build using command line arguments.

"/path/to/Unity.exe" -projectPath "/path/to/unity/project" -quit -batchmode -executeMethod Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild

Project Validation Command Line Arguments

Note

No longer required in Unity 6+

Argument	Description
-importTMProEssentialsAsset	Imports the TMPro Essential assets if they are not already in the project.

"/path/to/Unity.exe" -projectPath "/path/to/unity/project" -quit -batchmode -executeMethod Utilities.Editor.BuildPipeline.UnityPlayerBuildTools.ValidateProject -importTMProEssentialsAsset

Additional Custom Command Line Arguments

In addition to any already defined Unity Editor command line arguments, this plugin offers some additional options:

Argument	Description
-ignoreCompilerErrors	Disables logging.
-autoIncrement	Enables auto incrementing.
-versionName	Sets the version of the application. Value must be string.
-buildNumber	Sets the version build number of the application. (For Android, this must be an integer.)
-bundleIdentifier	Sets the bundle identifier of the application.
-productName	Sets the product name of the application and uses it for generated build artifact names when provided (including directory export/split modes).
-sceneList	Sets the scenes of the application, list as CSV.
-sceneListFile	Sets the scenes of the application from a file containing a CSV list.
-buildOutputDirectory	Sets the output directory for the build.
-acceptExternalModificationsToPlayer	Sets the build options to accept external modifications to the player.
-development	Sets the build options to build a development build of the player.
-patch	Sets the build options to build a patch of the player for platforms that support it.
-colorSpace	Sets the color space of the application, if the provided color space string is a valid ColorSpace enum value.
-compressionMethod	Set the build compression. Can be: LZ4, LZ4HC
-buildConfiguration	Sets the build configuration of the application. Can be: debug, master, or release.
-export	Creates a native code project for the target platform.
-symlinkSources	Enables the use of symbolic links for the sources.
-disableDebugging	⚠️ deprecated. Use allowDebugging. Disables the ability to attach remote debuggers to the player.
-allowDebugging	Enables or disables the ability to attache a remote debugger to the player. Can be: true or false.
-dotnetApiCompatibilityLevel	Sets the dotnet api compatibility level of the player. Can be: NET_2_0, NET_2_0_Subset, NET_4_6, NET_Unity_4_8, NET_Web, NET_Micro, NET_Standard, or NET_Standard_2_0.
-scriptingBackend	Sets the scripting framework of the player. Can be: Mono2x, IL2CPP, or WinRTDotNET.
-autoConnectProfiler	Start the player with a connection to the profiler.
-buildWithDeepProfilingSupport	Enables deep profiling support in the player.
-il2cppCompilerConfiguration	C++ compiler configuration used when compiling IL2CPP. Can be: Debug, Release, or Master
-il2cppCodeGeneration	Control code generation for IL2CPP. Can be: OptimizeSpeed or OptimizeSize
-buildProfileName	Sets the build profile by name.
-buildProfilePath	Sets the build profile by path.
-buildProfileGuid	Sets the build profile by asset guid.

Platform specific Command Line Arguments

Android Command Line Arguments

Argument	Description
-apkBundle	Builds an .apk (The default setting)
-appBundle	Builds an .aab for Google Play Store.
-splitBinaryPerCpuArch	Builds an APK per CPU architecture.
-splitApplicationBinary	If -appBundle is not passed, then Unity builds Android expansion files (OBB) for the APK, otherwise it will create asset packs for Play Asset Delivery.
-keystorePath	Path to the keystore.
-keystorePass	Sets the keystore password.
-keyaliasName	Name of the key to use when signing.
-keyaliasPass	Sets the key alias password.
-symbols	Sets the symbol creation mode. Can be: public, debugging, or disabled.
-versionCode	Sets the version code of the application. Must be an integer. Deprecated, use buildNumber instead
-minifyRelease	Enables minification of the release build.
-minifyDebug	Enables minification of the debug build.

Apple Device Command Line Args

Works for any Apple Platform Target: MacOS, iOS, tvOS, and visionOS.

Argument	Description
-appleTeamId	The team id used for signing.
-enableAppleAutomaticSigning	Enables automatic signing.
-disableAppleAutomaticSigning	Disables automatic signing.
-appleProvisioningProfileId	Sets the provisioning profile UUID.
-appleProvisioningProfileType	Sets the provisioning profile type. Can be Automatic, Development, or Distribution.
-appleSdkVersion	Sets the apple sdk version. Can be Device or Simulator.

MacOS Command Line Arguments

Argument	Description
-arch	Sets the build architecture. Can be: x64, arm64, or x64arm64.

Windows Universal Platform Command Line Arguments

Argument	Description
-arch	Sets the build architecture. Can be: x64, x86, ARM, or ARM64.
-wsaUWPBuildType	Sets the output build type when building to Universal Windows Platform. Can be: XAML, D3D, or ExecutableOnly.
-wsaSetDeviceFamily	Sets the device family. Can be: Desktop, Mobile, Xbox, Holographic, Team, IOT, or IoTHeadless.
-wsaUWPSDK	Sets the UWP SDK Version to build for.
-wsaMinUWPSDK	Sets the min UWP SDK to build for.
-wsaCertificate	Sets the signing certificate. Must pass the path and password together. -wsaCertificate "path/to/cert.pfx" myP@55w0rd