Documentation

​
​

Development

User Acquisition

Monetization

Industry

Unity Cloud

Get Started

Asset Manager SDKs and services

Open Unity Dashboard

Unity Cloud

​
​
Unity Dashboard
  • Accounts
  • Organizations
  • Projects
  • Products
  • Billing
Developer Data
  • Introduction to the Developer Data Framework
  • Get started
  • View Diagnostics for your project
    • Access Diagnostics
    • View events leading to a crash
    • Manage reports
      • Set up custom reports
      • Test reports
      • Debugging symbols
        • Introduction to debugging symbols
        • Upload symbol files through the Unity Dashboard
        • Upload debugging symbols from CI/CD pipelines
        • Runner examples for uploading debugging symbols through CI/CD pipelines
        • Troubleshooting symbol file uploads from CI/CD pipelines
        • Symbol file uploads API reference
    • Diagnostics page reference
  • Privacy and consent
Unity Asset Manager
  • What's new
  • Asset Manager web
  • Asset Store
  • Manage Assets in the Editor
  • Unity Version Control
  • Developer documentation
Unity Pipeline Automation
  • About
  • Get started
  • Pipelines
  • Automations
  • Monitor jobs
  1. Unity Cloud Documentation
  3. Developer Data framework

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 5 minutes
Last updated 3 months 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: deploy  tags:    - macos  variables:    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
Copyright © 2026 Unity Technologies
LegalPrivacy PolicyCookiesDocumentation Terms of UseDo Not Sell or Share My Personal InformationYour Privacy Choices (Cookie Settings)

"Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S and elsewhere (more info here). Other names or brands are trademarks of their respective owners.

Some pages are machine-translated for convenience, and may contain inaccuracies. In the event of conflicting information, the English version is authoritative.

  • On this page

    • GitHub Actions example macOS runner for Android

    • GitHub Actions example Windows runner for Windows

    • GitLab CI example macOS runner for macOS

Report a problem with this page