Documentation

Unity Cloud

Get Started

Asset Manager SDKs and services

Open Unity Dashboard

Unity Cloud

Runner examples for uploading debugging symbols through CI/CD pipelines

Find runner code samples for uploading debugging symbol files for various host and target platforms.
Read time 2 minutesLast updated 7 hours ago
You can configure example runner configurations to automate the upload of debugging symbol files through CI/CD pipelines. By integrating symbol uploads into your pipeline, you can automatically process and upload symbols whenever you build your project, eliminating manual steps and ensuring symbols stay synchronized with your builds. The following example runners cover various host and target platform combinations. Each runner demonstrates how to configure environment variables, inject CI values at runtime, and execute the appropriate symbol upload script. Each example runner does the following:
  • It automatically sets 
    UNITY_PROJECT_PATH
    to the CI workspace directory.
  • It assumes that the scripts are located in a 
    scripts/
    directory in your repository, such as 
    ./scripts/usymtool.sh
    .
Important
If you commit the scripts to a directory other than 
/scripts
, then adjust the path to match. For example, if the scripts are located in the repository root, then the corresponding path for 
usymtool.sh
is 
./usymtool.sh
.

GitHub Actions example macOS runner for Android

The following example provides a sample configuration for a macOS runner for the Android target platform.
Tip
To target a different platform, change the 
PLATFORM
environment variable. You can add any platform-specific variables, such as 
IOS_BUILD_PRODUCTS_PATH
for iOS.
name: Build and Upload Symbolson:  push:    branches: [main]env:  PLATFORM: "android"  UNITY_EDITOR_PATH: "/Applications/Unity/Hub/Editor/6000.3.10f1"  BUILD_NAME: "MyGame"jobs:  upload-symbols:    runs-on: macos-latest    steps:      - name: Checkout        uses: actions/checkout@v4      # ... your Unity build steps here ...      - name: Upload debug symbols        env:          UNITY_PROJECT_ID: ${{ secrets.UNITY_PROJECT_ID }}          UNITY_SA_AUTH: ${{ secrets.UNITY_SA_AUTH_HEADER }}          UNITY_PROJECT_PATH: ${{ github.workspace }}          BUILD_OUTPUT_PATH: ${{ github.workspace }}/Build        run: |          sed -i '' "s|PLATFORM=\"macos\"|PLATFORM=\"${PLATFORM}\"|" ./scripts/usymtool.sh          sed -i '' "s|UNITY_PROJECT_ID=\"<your-unity-project-id>\"|UNITY_PROJECT_ID=\"${UNITY_PROJECT_ID}\"|" ./scripts/usymtool.sh          sed -i '' "s|UNITY_SERVICE_ACCOUNT_AUTH_HEADER=\"<your-service-account-auth-header>\"|UNITY_SERVICE_ACCOUNT_AUTH_HEADER=\"${UNITY_SA_AUTH}\"|" ./scripts/usymtool.sh          sed -i '' "s|UNITY_EDITOR_PATH=\"/Applications/Unity/Hub/Editor/6000.3.10f1\"|UNITY_EDITOR_PATH=\"${UNITY_EDITOR_PATH}\"|" ./scripts/usymtool.sh          sed -i '' "s|UNITY_PROJECT_PATH=\"<your-unity-project-path>\"|UNITY_PROJECT_PATH=\"${UNITY_PROJECT_PATH}\"|" ./scripts/usymtool.sh          sed -i '' "s|BUILD_OUTPUT_PATH=\"<your-build-output-path>\"|BUILD_OUTPUT_PATH=\"${BUILD_OUTPUT_PATH}\"|" ./scripts/usymtool.sh          sed -i '' "s|BUILD_NAME=\"<your-build-name>\"|BUILD_NAME=\"${BUILD_NAME}\"|" ./scripts/usymtool.sh          chmod +x ./scripts/usymtool.sh          ./scripts/usymtool.sh
Important
If you use 
game-ci/unity-builder
, then ensure that Debug Symbols is enabled in your Unity project's Build Profiles or Player Settings before the build step runs. If Debug Symbols isn't enabled, the 
.so
files produced by the build are stripped and won't contain any debug data for 
usymtool
to upload.

GitHub Actions example Windows runner for Windows

The following example provides a sample configuration for a Windows runner for the Windows target platform. 
name: Build and Upload Symbols (Windows)on:  push:    branches: [main]env:  PLATFORM: "windows"  UNITY_EDITOR_PATH: "C:\\Program Files\\Unity\\Hub\\Editor\\6000.3.10f1"  BUILD_NAME: "MyGame"jobs:  upload-symbols:    runs-on: windows-latest    steps:      - name: Checkout        uses: actions/checkout@v4      # ... your Unity build steps here ...      - name: Upload debug symbols        shell: pwsh        env:          UNITY_PROJECT_ID: ${{ secrets.UNITY_PROJECT_ID }}          UNITY_SA_AUTH: ${{ secrets.UNITY_SA_AUTH_HEADER }}        run: |          $content = Get-Content ./scripts/usymtool.ps1 -Raw          $content = $content.Replace('$PLATFORM = "android"', '$PLATFORM = "${{ env.PLATFORM }}"')          $content = $content.Replace('$UNITY_PROJECT_ID = "<your-unity-project-id>"', ('$UNITY_PROJECT_ID = "' + $env:UNITY_PROJECT_ID + '"'))          $content = $content.Replace('$UNITY_SERVICE_ACCOUNT_AUTH_HEADER = "<your-service-account-auth-header>"', ('$UNITY_SERVICE_ACCOUNT_AUTH_HEADER = "' + $env:UNITY_SA_AUTH + '"'))          $content = $content.Replace('$UNITY_EDITOR_PATH = "C:\Program Files\Unity\Hub\Editor\6000.3.10f1"', ('$UNITY_EDITOR_PATH = "${{ env.UNITY_EDITOR_PATH }}"'))          $content = $content.Replace('$UNITY_PROJECT_PATH = "<your-unity-project-path>"', ('$UNITY_PROJECT_PATH = "' + $env:GITHUB_WORKSPACE + '"'))          $content = $content.Replace('$BUILD_OUTPUT_PATH = "<your-build-output-path>"', ('$BUILD_OUTPUT_PATH = "' + $env:GITHUB_WORKSPACE + '\Build"'))          $content = $content.Replace('$BUILD_NAME = "<your-build-name>"', '$BUILD_NAME = "${{ env.BUILD_NAME }}"')          $content | Set-Content ./scripts/usymtool.ps1          .\scripts\usymtool.ps1

GitLab CI example macOS runner for macOS

The following example provides a sample GitLab CI configuration for a macOS runner for the macOS target platform. When you use this configuration, you need to set the following GitLab CI variables in Settings > CI/CD > Variables: 
  • UNITY_PROJECT_ID
  • UNITY_SA_AUTH_HEADER
    (masked)
upload-symbols:stage: deploytags:  - macosvariables:  PLATFORM: "macos"  UNITY_EDITOR_PATH: "/Applications/Unity/Hub/Editor/6000.3.10f1"  BUILD_NAME: "MyGame"script:  - sed -i '' "s|UNITY_PROJECT_ID=\"<your-unity-project-id>\"|UNITY_PROJECT_ID=\"${UNITY_PROJECT_ID}\"|" ./scripts/usymtool.sh  - sed -i '' "s|UNITY_SERVICE_ACCOUNT_AUTH_HEADER=\"<your-service-account-auth-header>\"|UNITY_SERVICE_ACCOUNT_AUTH_HEADER=\"${UNITY_SA_AUTH_HEADER}\"|" ./scripts/usymtool.sh  - sed -i '' "s|UNITY_EDITOR_PATH=\"/Applications/Unity/Hub/Editor/6000.3.10f1\"|UNITY_EDITOR_PATH=\"${UNITY_EDITOR_PATH}\"|" ./scripts/usymtool.sh  - sed -i '' "s|UNITY_PROJECT_PATH=\"<your-unity-project-path>\"|UNITY_PROJECT_PATH=\"${CI_PROJECT_DIR}\"|" ./scripts/usymtool.sh  - sed -i '' "s|BUILD_OUTPUT_PATH=\"<your-build-output-path>\"|BUILD_OUTPUT_PATH=\"${CI_PROJECT_DIR}/Build\"|" ./scripts/usymtool.sh  - sed -i '' "s|BUILD_NAME=\"<your-build-name>\"|BUILD_NAME=\"${BUILD_NAME}\"|" ./scripts/usymtool.sh  - chmod +x ./scripts/usymtool.sh  - ./scripts/usymtool.sh