Build Metrics → Documentation → GitHub Actions Integration

GitHub Actions Integration

Integrate Build Metrics with GameCI for automated Unity builds on GitHub Actions

Looking for self-hosted runners? See the Self-Hosted GitHub Actions guide →

Quick Start

⚡ 3-Step Setup

  1. Add BUILD_METRICS_API_KEY to GitHub Secrets
  2. Add Unity license secrets (UNITY_EMAIL, UNITY_PASSWORD, UNITY_LICENSE)
  3. Copy the verified workflow example below

✅ This configuration is verified and working - tested with Unity Personal license on GitHub hosted runners.

Step 1: Add Build Metrics API Key

  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: Unity License Setup

✅ Both Free & Paid Work!

Unity Personal (free) and Pro/Plus both work with GameCI. Setup is simple with just 2-3 GitHub secrets.

🆓 Unity Personal (Free)

3 secrets needed - email, password, and .ulf license file

📋 License File Method

  • • UNITY_EMAIL
  • • UNITY_PASSWORD
  • • UNITY_LICENSE (contents of .ulf file)

💼 Unity Pro/Plus (Paid)

Use serial number for best results

🔑 Serial Method

  • • UNITY_EMAIL
  • • UNITY_PASSWORD
  • • UNITY_SERIAL

Unity Personal (Free) - Email & Password

📋 How to Get Your .ulf File

Unity Personal licenses require a .ulf license file for CI/CD activation. Here's how to get it:

  1. Open Unity Hub → Manage Licenses
  2. Click "Manual Activation"
  3. Save the .alf file
  4. Upload to Unity Manual License
  5. Download the .ulf file
  6. Copy its entire contents into the UNITY_LICENSE secret

📖 Detailed guide: GameCI Activation Docs

Add these 3 secrets to GitHub (Repository → Settings → Secrets and variables → Actions):

UNITY_EMAIL

Your Unity account email

UNITY_PASSWORD

Your Unity account password

💡 Tip: Avoid special characters - use alphanumeric only to prevent activation issues

UNITY_LICENSE

Contents of your .ulf license file

💡 Generate via Unity Hub: Manage Licenses → Manual Activation → Copy file contents

📖 Official Guide: See GameCI Activation Documentation → for detailed steps on getting your .ulf file

⚠️ Important Notes

  • • Your .ulf license file is tied to your Unity account and machine - generate it once and store in GitHub Secrets
  • • If you have 2FA enabled on Unity account, you'll need to configure TOTP (see GameCI docs)
  • • Personal licenses are rate-limited by Unity - avoid running too many parallel builds
  • • The license file contents should be pasted as plain text into the UNITY_LICENSE secret

Unity Pro/Plus - Serial Number (Recommended)

For Unity Pro or Plus licenses, use your serial key instead of a license file:

UNITY_EMAIL

Your Unity account email

UNITY_PASSWORD

Your Unity account password

UNITY_SERIAL

Your Unity serial key (format: XX-XXXX-XXXX-XXXX-XXXX-XXXX)

✅ Advantages

  • • No manual .ulf file generation needed
  • • More stable for CI/CD pipelines
  • • Supports multiple concurrent builds

Step 3: Workflow Configuration

Create .github/workflows/build.yml in your repository:

📱 Android Platform Example

This workflow builds an unsigned development APK for Android. Perfect for testing and CI/CD pipelines.

  • • Output: Unsigned APK (development build)
  • • Disk cleanup: Prevents "No space left on device" errors (GameCI Docker images are large)
  • • No keystore required for this basic setup
  • • For signed release builds, see the optional keystore section below

💾 Why Disk Cleanup Instead of Caching?

GitHub hosted runners have limited disk space (~14GB free). GameCI's Unity Docker images are very large, so we free up space by removing unused Docker images and tools before building. Library folder caching can actually cause builds to fail with "No space left on device" errors.

yaml
name: Build Unity Project

on:
  push:
    branches: [main]
  pull_request:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      # Free up runner disk space
      - name: Free up runner disk space
        run: |
          df -h
          sudo docker image prune --all --force
          sudo docker builder prune --all --force
          sudo rm -rf /opt/hostedtoolcache/*
          sudo apt clean
          df -h

      # Checkout repository
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          lfs: true
          fetch-depth: 0  # Full git history for commit tracking

      # Build with Unity (license activation happens automatically)
      - name: Build Project
        uses: game-ci/unity-builder@v4
        env:
          BUILD_METRICS_API_KEY: ${{ secrets.BUILD_METRICS_API_KEY }}
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
          UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
          UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}

          # Unity Pro/Plus (Paid) - Comment out above, uncomment below
          # UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
          # UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
          # UNITY_SERIAL: ${{ secrets.UNITY_SERIAL }}
        with:
          customParameters: "-development -BUILD_METRICS_API_KEY ${{ secrets.BUILD_METRICS_API_KEY }}"
          targetPlatform: Android
          unityVersion: auto
          buildName: MyGame

      # Upload build artifacts
      - name: Upload Build
        uses: actions/upload-artifact@v4
        with:
          name: Build-Android
          path: build/Android

# Build Metrics uploads automatically after Unity build completes!
# View results at: https://app.buildmetrics.moonlightember.com

✅ How It Works

  • 1. Free up disk space to prevent "No space left on device" errors
  • 2. Unity license activates automatically using env: variables (UNITY_EMAIL, UNITY_PASSWORD, UNITY_LICENSE)
  • 3. GameCI's unity-builder runs Unity in Docker with your build settings
  • 4. Build Metrics API key is passed via customParameters to Unity (Docker doesn't expose env vars to Unity)
  • 5. Build Metrics plugin detects the API key from command line and uploads metrics automatically
  • 6. View results in your Build Metrics dashboard

💡 Important Tips

  • • Personal License: Needs 3 secrets - UNITY_EMAIL, UNITY_PASSWORD, and UNITY_LICENSE (contents of .ulf file)
  • • Pro/Plus License: Use UNITY_EMAIL, UNITY_PASSWORD, and UNITY_SERIAL
  • • No separate activation step needed - GameCI v4 handles it automatically in the build step
  • • Critical for Build Metrics: API key MUST be in customParameters - env vars don't reach Unity in Docker
  • • License credentials: Go in env: block, NOT in with: inputs
  • • See official guide: GameCI Activation Documentation

⚠️ Unity Project Not in Repository Root?

If your Unity project is in a subfolder (e.g., MyUnityProject/ instead of repository root), add projectPath:

# Update build step - add projectPath - name: Build Project uses: game-ci/unity-builder@v4 env: BUILD_METRICS_API_KEY: ${{ secrets.BUILD_METRICS_API_KEY }} UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }} UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }} UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }} with: customParameters: "-development -BUILD_METRICS_API_KEY ${{ secrets.BUILD_METRICS_API_KEY }}" projectPath: MyUnityProject # <-- Add this targetPlatform: Android unityVersion: auto buildName: MyGame

Reference: Signed Release Builds with Keystore

For signed release APKs ready for Google Play Store, you'll need Android keystore signing. Build Metrics works the same way - just add the highlighted lines below to your signed build workflow.

Additional Secrets Needed

Beyond the standard secrets (BUILD_METRICS_API_KEY, UNITY_EMAIL, UNITY_PASSWORD, UNITY_LICENSE), add these keystore secrets to GitHub:

ANDROID_KEYSTORE_BASE64

Base64-encoded keystore file

ANDROID_KEYSTORE_PASS

Keystore password

ANDROID_KEYALIAS_NAME

Key alias name

ANDROID_KEYALIAS_PASS

Key alias password

Build Metrics Integration

The key difference: Build Metrics uses the same highlighted configuration as the basic setup.

yaml (excerpt)
- name: Build Signed Release
  uses: game-ci/unity-builder@v4
  env:
    BUILD_METRICS_API_KEY: ${{ secrets.BUILD_METRICS_API_KEY }}
    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
    UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
    UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
  with:
    customParameters: "-BUILD_METRICS_API_KEY ${{ secrets.BUILD_METRICS_API_KEY }}"
    targetPlatform: Android
    androidKeystoreName: user.keystore
    androidKeystorePass: ${{ secrets.ANDROID_KEYSTORE_PASS }}
    androidKeyaliasName: ${{ secrets.ANDROID_KEYALIAS_NAME }}
    androidKeyaliasPass: ${{ secrets.ANDROID_KEYALIAS_PASS }}

✅ Result

  • • Build Metrics automatically tracks signed builds
  • • Same API key configuration as development builds
  • • Works with both APK and AAB (Android App Bundle)

📖 Learn More

For complete keystore setup instructions, see GameCI Android Build Documentation →

Reference: Multi-Platform Matrix Builds

To build for multiple platforms in parallel (Android, iOS, WebGL, Windows, etc.), use GitHub Actions matrix strategy. Build Metrics integration is the same - just add the highlighted configuration to your matrix build.

Matrix Strategy Example

The key parts: use strategy.matrix to define platforms, and Build Metrics tracks each one separately.

yaml (excerpt)
jobs:
  build:
    runs-on: ubuntu-latest

    strategy:
      fail-fast: false
      matrix:
        targetPlatform:
          - Android
          - iOS
          - WebGL
          - StandaloneWindows64

    env:
      BUILD_METRICS_API_KEY: ${{ secrets.BUILD_METRICS_API_KEY }}
      UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
      UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
      UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}

    steps:
      # ... checkout, disk cleanup, etc ...

      - name: Build Project
        uses: game-ci/unity-builder@v4
        env:
          BUILD_METRICS_API_KEY: ${{ secrets.BUILD_METRICS_API_KEY }}
          UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
          UNITY_EMAIL: ${{ secrets.UNITY_EMAIL }}
          UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
        with:
          customParameters: "-development -BUILD_METRICS_API_KEY ${{ secrets.BUILD_METRICS_API_KEY }}"
          targetPlatform: ${{ matrix.targetPlatform }}
          unityVersion: auto

✅ Result

  • • Each platform builds in parallel (faster CI/CD)
  • • Build Metrics tracks each platform separately
  • • Dashboard shows builds grouped by platform
  • • Same API key works for all platforms

📖 Learn More

For complete matrix build setup, see GameCI Matrix Build Documentation →

Troubleshooting

⚠️ License Activation Fails

Error:

"Invalid credentials" or "License activation failed"

Unity Personal: Verify UNITY_EMAIL and UNITY_PASSWORD are correct. Check for 2FA issues.

Unity Pro: Verify UNITY_LICENSE base64 encoding is correct (no line breaks)

Check: Unity version in workflow matches your project's Unity version

📊 Build Succeeds But Metrics Don't Upload

  • • Verify BUILD_METRICS_API_KEY secret is set correctly
  • • Check GitHub Actions logs for "Build Metrics" output
  • • Ensure API key is active in Build Metrics dashboard
  • • Verify build actually completed successfully (check exit code)

🐌 Slow Builds

  • • Add Library caching (see examples above)
  • • Use fetch-depth: 1 instead of fetch-depth: 0 if you don't need git history
  • • Consider self-hosted runners for larger projects

Next Steps

Self-Hosted Runners →

Use your own build machines with custom Unity setups and build profiles

Offline Mode →

Track builds locally without internet connection

📚 More Examples

Find complete workflow examples in the GitHub repository:

View workflow examples on GitHub →