unity-build.yml

name: unity-build
on:
  workflow_call:
    inputs:
      matrix:
        required: true
        type: string
      utp-test-profile:
        required: false
        type: string
        default: normal
    secrets:
      UNITY_USERNAME:
        required: true
      UNITY_PASSWORD:
        required: true
jobs:
  build:
    name: ${{ matrix.name }}
    runs-on: ${{ matrix.os }}
    strategy:
      matrix: ${{ fromJSON(inputs.matrix) }}
      fail-fast: false
    permissions:
      contents: read
      checks: write # to publish unit test results via checks github api
    defaults:
      run:
        shell: bash
    env:
      UNITY_PROJECT_PATH: '' # Create Unity Project step will set this if needed
      UNITY_CLI_WORKFLOW_SUMMARY: 'true' # opt-in: append rich markdown to GITHUB_STEP_SUMMARY from unity-cli log parsing
    steps:
      - name: Free Disk Space
        if: ${{ matrix.os == 'ubuntu-latest' && (matrix.unity-version != '2018' && matrix.unity-version != '2017.4.40f1') }}
        uses: endersonmenezes/free-disk-space@7901478139cff6e9d44df5972fd8ab8fcade4db1 # v3.2.2
        with:
          remove_android: true
          remove_dotnet: false
          remove_tool_cache: false
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: 24.x
      - name: Setup unity-cli
        run: |
          npm ci
          npm run build
          npm run link
          unity-cli --version
      - name: Setup Unity
        timeout-minutes: 30
        run: |
          if [ "${{ matrix.os }}" = "windows-11-arm" ]; then
            unity-cli hub-install
          else
            unity-cli hub-install --hub-version 3.12.0
            unity-cli hub-install --auto-update
          fi
          unity-cli hub-version
          unity-cli upm-install --json
          UPM_VER=$(unity-cli upm-version | tr -d '\n\r')
          echo "UPM CLI version: ${UPM_VER}"
          if ! [[ "${UPM_VER}" =~ ^v[0-9] ]]; then
            echo "::error::upm-version expected a v-prefixed release (e.g. v9.0.0); got: ${UPM_VER}"
            exit 1
          fi
          if [ "${{ matrix.unity-version }}" != "none" ]; then
            unity-cli setup-unity --unity-version "${{ matrix.unity-version }}" --build-targets "${{ matrix.build-target }}" --json
          fi
      - name: Verify UNITY_HUB_PATH and UNITY_EDITOR_PATH variables
        run: |
          echo "UNITY_HUB_PATH: ${UNITY_HUB_PATH}"
          echo "UNITY_EDITOR_PATH: ${UNITY_EDITOR_PATH}"
          echo "UNITY_PROJECT_PATH: ${UNITY_PROJECT_PATH}" # Expected to be empty at this point

          if [ -z "${UNITY_HUB_PATH}" ]; then
            echo "::error::UNITY_HUB_PATH is not set"
            exit 1
          fi

          if [ "${{ matrix.unity-version }}" != "none" ] && [ -z "${UNITY_EDITOR_PATH}" ]; then
            echo "::error::UNITY_EDITOR_PATH is not set"
            exit 1
          fi
      - name: Activate License
        if: ${{ matrix.unity-version != 'none' }}
        run: |
          unity-cli license-context
          unity-cli activate-license --license personal --email "${{ secrets.UNITY_USERNAME }}" --password "${{ secrets.UNITY_PASSWORD }}"
      - name: Create Unity Project
        if: ${{ matrix.unity-version != 'none' }}
        run: |
          unity-cli list-project-templates --unity-editor "${UNITY_EDITOR_PATH}" --json
          create_rc=1
          for attempt in 1 2 3; do
            echo "Create Unity Project attempt ${attempt}/3"
            if unity-cli create-project --name "Unity Project" --unity-editor "${UNITY_EDITOR_PATH}" --json; then
              create_rc=0
              break
            fi
            if [ "$attempt" -lt 3 ]; then
              echo "::warning::create-project failed on attempt ${attempt}; retrying after short backoff"
              sleep 10
            fi
          done
          if [ "$create_rc" -ne 0 ]; then
            echo "::error::Failed to create Unity project after 3 attempts"
            exit 1
          fi
      - name: Verify UNITY_PROJECT_PATH variable
        if: ${{ matrix.unity-version != 'none' }}
        id: verify-project-path
        run: |
          if [ -z "${UNITY_PROJECT_PATH}" ]; then
            echo "::error::UNITY_PROJECT_PATH is not set"
            exit 1
          fi
          # check if the project can be built. Only Unity 2019.4+ and newer majors support the build pipeline package
          version="${{ matrix.unity-version }}"
          # extract major and minor (minor may be empty if version is just '2019' etc.)
          major=$(echo "$version" | cut -d'.' -f1)
          minor=$(echo "$version" | cut -d'.' -f2)
          if [ -z "$minor" ]; then
            minor=0
          fi
          # numeric comparison: enable build for major >= 2019
          if [ "$major" -ge 2019 ]; then
            echo "Proceeding with build for Unity version $version"
            echo "RUN_BUILD=true" >> $GITHUB_OUTPUT
          else
            echo "Skipping build: Unity version $version does not support the build pipeline package (requires 2019.4+)"
          fi
      - name: Update Android Target Sdk Version
        if: ${{ matrix.build-target == 'Android' && matrix.unity-version != 'none' }}
        run: |
          # update AndroidTargetSdkVersion to 32 in ProjectSettings/ProjectSettings.asset
          sed -i 's/AndroidTargetSdkVersion: [0-9]*/AndroidTargetSdkVersion: 32/' "${UNITY_PROJECT_PATH}/ProjectSettings/ProjectSettings.asset"
          # ensure android dependencies are installed before UTP/build batches
          unity-cli setup-unity -p "${UNITY_PROJECT_PATH}" -m android
      - name: Compute safe artifact name
        id: artifact-name
        env:
          MATRIX_NAME: ${{ matrix.name }}
        run: |
          set -euo pipefail
          unity_version="${{ matrix.unity-version }}"
          unity_version="${unity_version//'*'/x}"
          bt="${{ matrix.build-target }}"
          bt="${bt:-none}"
          # Per-job slug so parallel matrix rows never collide (name encodes the job-builder row).
          base="${{ matrix.os }}-${unity_version}-${bt}"
          ba="${{ matrix.build-args }}"
          if [ -n "${ba}" ]; then
            if command -v sha256sum >/dev/null 2>&1; then
              bah=$(printf '%s' "$ba" | sha256sum | awk '{print $1}' | cut -c1-12)
            else
              bah=$(printf '%s' "$ba" | shasum -a 256 2>/dev/null | awk '{print $1}' | cut -c1-12)
            fi
            base="${base}-ba${bah}"
          fi
          mname="${MATRIX_NAME:-}"
          if [ -n "$mname" ]; then
            slug=$(printf '%s' "$mname" | sed 's/[^a-zA-Z0-9._-]/_/g' | cut -c1-100)
            base="${slug}__${base}"
          fi
          echo "name=${base}-utp-batch-logs" >> $GITHUB_OUTPUT
        shell: bash
      - name: Run Unity UTP test batches
        if: ${{ steps.verify-project-path.outputs.RUN_BUILD == 'true' }}
        uses: ./.github/actions/run-unity-test-batch
        with:
          unity-project-path: ${{ env.UNITY_PROJECT_PATH }}
          build-target: ${{ matrix.build-target }}
          build-args: ${{ matrix.build-args }}
          test-profile: ${{ inputs.utp-test-profile }}
          artifact-name: ${{ steps.artifact-name.outputs.name }}
      - name: Verify UTP JSON keys
        if: ${{ steps.verify-project-path.outputs.RUN_BUILD == 'true' }}
        run: node .github/scripts/scan-utp-artifacts.cjs "${GITHUB_WORKSPACE}/utp-artifacts"
      - name: Guardrail hidden UTP failures
        if: ${{ steps.verify-project-path.outputs.RUN_BUILD == 'true' }}
        run: |
          set -euo pipefail
          # Keep this alternation in sync with hard failures from .github/actions/scripts/run-utp-tests.sh
          failure_markers='One or more tests did not meet expectations|was expected to succeed but failed|produced UTP errors but was expected to succeed'
          log_dir="${UNITY_PROJECT_PATH}/Builds/Logs"
          artifacts_dir="${GITHUB_WORKSPACE}/utp-artifacts"

          marker_found=0

          scan_markers() {
            local target_dir="$1"
            if command -v rg >/dev/null 2>&1; then
              rg -n --no-ignore -S "$failure_markers" "$target_dir"
            else
              grep -RInE "$failure_markers" "$target_dir"
            fi
          }

          if [ -d "$log_dir" ]; then
            if scan_markers "$log_dir"; then
              echo "::error::Hidden UTP failure marker detected in ${log_dir}"
              marker_found=1
            fi
          fi

          if [ -d "$artifacts_dir" ]; then
            if scan_markers "$artifacts_dir"; then
              echo "::error::Hidden UTP failure marker detected in ${artifacts_dir}"
              marker_found=1
            fi
          fi

          if [ "$marker_found" -ne 0 ]; then
            exit 1
          fi
      - name: Uninstall Editor
        if: ${{ matrix.unity-version != 'none' }}
        timeout-minutes: 5
        continue-on-error: true
        run: |
          if [ -z "${UNITY_EDITOR_PATH}" ]; then
            echo "UNITY_EDITOR_PATH is not set, skipping uninstall"
            exit 0
          fi
          unity-cli uninstall-unity --unity-editor "${UNITY_EDITOR_PATH}"
      - name: Print log paths
        if: ${{ matrix.unity-version != 'none' }}
        run: |
          HUB_LOG_PATH=$(unity-cli hub-logs)
          PACKAGE_MANAGER_LOG_PATH=$(unity-cli package-manager-logs)
          LICENSING_CLIENT_LOG_PATH=$(unity-cli licensing-client-logs)
          LICENSING_AUDIT_LOG_PATH=$(unity-cli licensing-audit-logs)

          echo "Hub Log Path: ${HUB_LOG_PATH}"
          echo "Package Manager Log Path: ${PACKAGE_MANAGER_LOG_PATH}"
          echo "Licensing Client Log Path: ${LICENSING_CLIENT_LOG_PATH}"
          echo "Licensing Audit Log Path: ${LICENSING_AUDIT_LOG_PATH}"

          if [ ! -f "${HUB_LOG_PATH}" ]; then
            echo "::warning:: Hub log file does not exist at ${HUB_LOG_PATH}"
            # find all info-log.json files in ~/.config/unity3d/ - print their paths
            find ~/.config/unity3d/ -type f \( -name "info-log.json" \) -exec echo "{}" \;
            # also try to find in UNITY_HUB_PATH parent directory if set
            if [ -n "${UNITY_HUB_PATH}" ]; then
              HUB_DIR=$(dirname "${UNITY_HUB_PATH}")
              find "${HUB_DIR}" -type f \( -name "info-log.json" \) -exec echo "{}" \;
            fi
            # print all files found in ~/.config/
            find ~/.config/ -type f -exec echo "{}" \;
            echo "::warning:: Hub log file does not exist at any known location"
          fi

          if [ ! -f "${PACKAGE_MANAGER_LOG_PATH}" ]; then
            echo "::warning::Package Manager log file does not exist at ${PACKAGE_MANAGER_LOG_PATH}"
          fi

          if [ ! -f "${LICENSING_CLIENT_LOG_PATH}" ]; then
            echo "::error::Licensing Client log file does not exist at ${LICENSING_CLIENT_LOG_PATH}"
          fi

          if [ ! -f "${LICENSING_AUDIT_LOG_PATH}" ]; then
            echo "::error::Licensing Audit log file does not exist at ${LICENSING_AUDIT_LOG_PATH}"
          fi
      - name: Return License
        if: always()
        run: unity-cli return-license --license personal