Build Metrics → Documentation → Self-Hosted GitHub Actions

Self-Hosted GitHub Actions

Integrate Build Metrics with your existing build infrastructure and custom Unity setups

🎯 Perfect For:

  • ✓ Teams with existing macOS/Windows build machines
  • ✓ Projects using custom build profiles and methods
  • ✓ Pipelines with fastlane, AWS, Firebase, or custom deployment
  • ✓ Organizations avoiding GameCI Docker containers
  • ✓ Builds requiring specific Unity versions or licensed packages

⚡ Zero Pipeline Changes Required

Just add BUILD_METRICS_API_KEY environment variable to your workflow. Build Metrics automatically detects Unity builds and uploads metrics. Your existing build scripts, deployment steps, and custom logic remain unchanged.

Quick Setup

Step 1: Add API Key to GitHub Secrets

  1. Get your API key from Build Metrics Dashboard
  2. Go to your GitHub repo → Settings → Secrets and variables → Actions
  3. Click "New repository secret"
  4. Name: BUILD_METRICS_API_KEY
  5. Value: Your API key (starts with bm_)

Step 2: Update Your Workflow

Add the environment variable to your job:

yaml
jobs:
  build-android:
    runs-on: [self-hosted, macOS, Unity]

    env:
      BUILD_METRICS_API_KEY: ${{ secrets.BUILD_METRICS_API_KEY }}

    steps:
      # Your existing build steps here...

That's it! Metrics upload automatically after Unity builds complete.

Real-World Example: Android Build with Custom Pipeline

This example shows a production Android build with custom build profiles, Firebase distribution, and S3 deployment:

yaml
name: Build Android

on:
  push:
    branches: [main, develop]
  workflow_dispatch:

jobs:
  build-android:
    runs-on: [self-hosted, macOS, Unity, Mac-Mini-1]
    timeout-minutes: 60

    env:
      BUILD_METRICS_API_KEY: ${{ secrets.BUILD_METRICS_API_KEY }}

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          lfs: true
          fetch-depth: 0

      - name: Build Android with Unity
        run: |
          /Applications/Unity/Hub/Editor/6000.0.52f1/Unity.app/Contents/MacOS/Unity \
            -quit -batchmode -nographics \
            -projectPath . \
            -executeMethod BuildConfiguration.Profiles.AndroidBuildProfile.Build \
            -logFile -

      - name: Upload to Firebase
        run: |
          fastlane android firebase

      - name: Upload to S3
        run: |
          aws s3 cp ./Builds/Android s3://your-bucket/android/ --recursive

      - name: Invalidate CloudFront
        run: |
          aws cloudfront create-invalidation \
            --distribution-id YOUR_DIST_ID \
            --paths "/*"

# Build Metrics uploads happen automatically after Unity build step
# No changes to your existing pipeline required

✅ What Happens Here

  • 1. Workflow runs on self-hosted macOS runner with Unity installed
  • 2. Unity CLI builds using custom AndroidBuildProfile.Build method
  • 3. Build Metrics post-build hook uploads metrics automatically
  • 4. Your existing deployment continues (Firebase, S3, CloudFront)
  • 5. View build metrics in dashboard while deployment proceeds

Self-Hosted Runner Requirements

Prerequisites

  • ✓ Unity installed and activated on your build machine
  • ✓ Build Metrics plugin installed in your Unity project
  • ✓ Internet access for metrics upload
  • ✓ Self-hosted runner configured (GitHub Docs)

✅ That's It!

No special runner configuration needed for Build Metrics. Just add the API key to your workflow and metrics upload automatically.

Advanced Configuration

Build Metrics automatically works with any Unity build method - custom scripts, addressables, or third-party tools. Just set the BUILD_METRICS_API_KEY environment variable and metrics upload automatically.

Conditional Metrics Upload

Only upload metrics on specific branches:

yaml
env:
  # Only upload metrics on main branch
  BUILD_METRICS_API_KEY: ${{ github.ref == 'refs/heads/main' && secrets.BUILD_METRICS_API_KEY || '' }}

Troubleshooting

📊 Metrics Not Uploading

  • • Check that BUILD_METRICS_API_KEY environment variable is set
  • • Verify Build Metrics plugin is installed in your Unity project
  • • Check Unity build actually completed (look for "Build completed" in logs)
  • • Ensure runner has internet access
  • • Check GitHub Actions logs for Build Metrics output

🔑 Unity License Issues

  • • Ensure Unity is activated on the self-hosted runner
  • • Unity Pro: license can be used on multiple machines
  • • Unity Personal: each machine needs separate activation
  • • Verify license hasn't expired

❌ Build Fails

  • • Check Unity path is correct for your runner OS
  • • Verify all required SDKs are installed (Android SDK, Xcode)
  • • Check Unity version matches your project
  • • Review Unity logs (-logFile - outputs to console)

Next Steps

← GameCI Integration

Using GitHub-hosted runners? See the GameCI guide

Webhooks & Alerts →

Get notified about build regressions and failures

📚 More Examples

Find complete workflow examples in the GitHub repository:

View workflow examples on GitHub →