Alon Farchy

Jan 23, 2026

Share this

Copied!

Automating Unity Builds for Meta Quest

Developing for VR on the Meta Quest involves a lot of iteration. Since many device capabilities only work on the headset, you’ll find yourself making frequent builds to sideload. Distributing those builds to playtesters manually can consume much of your time. As your app and team grow, you start wishing this process was automated.

In this guide, we’ll set up a completely automated pipeline that takes your code from GitHub, builds it in the cloud, and delivers it directly to a release channel on the Meta Quest Store.

Note

This guide assumes you are already familiar with setting up basic Unity builds with GitHub Actions. If you're just starting out, check out my guide on Automating Unity Builds with GitHub Actions first.

By the end of this tutorial, you will have a GitHub Actions workflow that:

1. Triggers whenever you push to your main branch.
2. Builds your Unity project for Android (Meta Quest).
3. Uploads the resulting APK directly to a specific Release Channel (e.g., Alpha) on the Meta Quest Store.

Table of Contents

1. Setting up the Meta Developer Portal
2. Configure GitHub Secrets for Meta
3. Configure GitHub Secrets for Keystores and Signing
4. Update Your Build Workflow
5. Installing the Build on Your Headset

Setting up the Meta Developer Portal

Before we touch any YAML configuration, we need to prepare our application on the Meta Developer Dashboard.

Create Your App

If you haven’t created an app yet:

1. Log in to the Developer Dashboard.
2. Click Create New App.
3. Give it a name and click Create.

Get Your Credentials

To allow GitHub Actions to upload builds on your behalf, you need two pieces of information: the App ID and the App Secret.

1. Navigate to the Development > API tab in your app’s dashboard.
2. Copy the App ID. You’ll need this for your workflow file.
3. Copy the App Secret. Do not commit this to your repository! We will save this as a secret in GitHub.

Tip

On some accounts, you may need to verify your account or complete the Data Use Checkup before you can access full API functionality. If your upload fails later with permission errors, double-check that your developer account status is in good standing.

Create a Release Channel

Release channels let you to distribute different versions of your app to different users. For example, you might have a “Live” channel for the public and an “Alpha” channel for internal testing.

1. Go to Distribution > Release Channels.
2. You likely already have LIVE, ALPHA, BETA, and RC.
3. You can use one of these (e.g., ALPHA) or create a new one specifically for automated builds, like NIGHTLY or ACTIONS.
4. Note the exact name of the channel you want to target.

Configure GitHub Secrets for Meta

We never want to hardcode our App Secret into our workflow files where anyone could see them. Instead, we use GitHub Secrets.

1. Navigate to your GitHub repository.
2. Click on Settings > Secrets and variables > Actions.
3. Click New repository secret.
4. Create a secret named META_APP_SECRET and paste the value you copied from the Meta Developer Dashboard.
5. (Optional) You can also store your App ID as META_APP_ID, though it is generally considered public information.

Configure GitHub Secrets for Keystores and Signing

One critical detail for Android builds is code signing. The Meta Quest Store requires your APKs to be signed with a production keystore, even for the Alpha channel. If you try to upload a development build signed with a default debug keystore, the action will successfully build, but the Meta server will reject the upload during validation.

What is a Keystore?

A keystore is a binary file that acts as a digital certificate for your app. It proves that the update comes from the same developer as the original app. If you lose your keystore, you lose the ability to update your app on the store—forever. So keep it safe!

Creating a Keystore

1. Open your Unity project.
2. Go to Project Settings > Player > Publishing Settings.
3. Under Keystore Manager, create a new keystore.
4. Choose a location inside your project folder.
5. Set a Keystore Password, create a new Key Alias, and set a Key Password.
6. Go to your GitHub repository Settings > Secrets and variables > Actions.
7. Create two new secrets for your passwords: ANDROID_KEYSTORE_PASS and ANDROID_KEYALIAS_PASS.

The Buildalon build script we are using is designed to pick up these secrets from the command line arguments and apply them to the keystore found in your project settings.

Keystore Security

For better security, you can encode your keystore in base64 and store it as a GitHub Secret instead of committing the file.

1. Encode the keystore in base64.

On macOS/Linux:

openssl base64 -in user.keystore -out user.keystore.base64.txt

On Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("user.keystore")) | Set-Content user.keystore.base64.txt

2. Store: Add it as a secret named ANDROID_KEYSTORE_BASE64.
3. Decode: Add a step in your workflow (below) to decode it back to a file using openssl base64 -d
4. Build: Pass -keystorePath user.keystore in your unity-action build arguments.

Update Your Build Workflow

Now, let’s look at the workflow file. We’ll build upon the standard Buildalon Android workflow but add a crucial final step: the upload.

We’ll be using the following actions:

• buildalon/setup-ovr-platform-util - Installs OVR Platform Tool.
• buildalon/upload-meta-quest-build - Invokes OVR Platform Tool to upload your build.

Create or update your .github/workflows/quest-build.yml file with the following configuration:

name: Deploy to Quest

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    name: Build & Deploy to Quest
    runs-on: buildalon-windows

    steps:
      # Checkout the repository
      - uses: actions/checkout@v4
        with:
          lfs: true

      # Setup Unity
      - uses: buildalon/unity-setup@v1
        with:
          build-targets: Android

      # Activate Unity License
      - uses: buildalon/activate-unity-license@v1
        with:
          license: 'Personal'
          username: ${{ secrets.UNITY_EMAIL }}
          password: ${{ secrets.UNITY_PASSWORD }}

      # Temporarily add the Buildalon command line package to your Unity project
      - name: Add Build Pipeline Package
        working-directory: ${{ env.UNITY_PROJECT_PATH }}
        run: |
          npm install -g openupm-cli
          openupm add com.virtualmaker.buildalon

      # Build the Project
      - uses: buildalon/unity-action@v1
        name: Build Android APK
        with:
          build-target: Android
          # Optional: add a previous step to decode a base64 keystore, and add: -keystorePath path/to/keystore/file
          args: >-
            -quit -batchmode
            -executeMethod Buildalon.Editor.BuildPipeline.UnityPlayerBuildTools.StartCommandLineBuild
            -keyaliasPass "${{ secrets.ANDROID_KEYALIAS_PASS }}"
            -keystorePass "${{ secrets.ANDROID_KEYSTORE_PASS }}"
          log-name: Quest-Build

      # Setup OVR Platform Util
      - uses: buildalon/setup-ovr-platform-util@v1

      # Upload to Meta Quest Store
      - uses: buildalon/upload-meta-quest-build@v1
        name: Upload to Meta Quest
        with:
          # Your App ID (can be hardcoded or a secret)
          appId: '123456789012345'

          # Your App Secret
          appSecret: ${{ secrets.META_APP_SECRET }}

          # The path to your built APK.
          buildDir: ${{ env.UNITY_PROJECT_PATH }}/Builds/Android

          # The channel to upload to (ALPHA, BETA, LIVE, etc.)
          releaseChannel: 'ALPHA'

          # Optional, uploads the build even if there are validation errors.
          force: true

Key Changes:

• Set the build platform to Android.
• Pass the keystore credentials to the build step.
• Install the OVR Platform Tools
• Upload the built APK.

The magic happens in the buildalon/upload-meta-quest-build step. This action wraps the Oculus Platform Command Line Utility, handling the authentication and upload process for you.

• appId: Identifies which application specifically you are updating.
• appSecret: Authenticates the upload request.
• buildDir: Tells the uploader where to find your build. Note that StartCommandLineBuild by default outputs builds to the Builds/{Platform} folder.
• releaseChannel: Ensures the build lands in the right place so your testers get the update without affecting live users.

Installing the Build on Your Headset

Once your build succeeds, it will be uploaded to the ALPHA channel.

1. Invite Users: In the Meta Developer Dashboard, go to Distribution > Users. Add yourself and your teammates to the ALPHA channel using their Meta account emails.
2. Accept the Invite: Each person will receive an email invitation to test the app. They must accept this invite.
3. Find the App:
   • Put on your Quest headset.
   • Navigate to your App Library.
   • Look for the app in the All or Not Installed category. It may also appear in the My Preview Apps section of the Store.
   • Install the application.
4. Confirm the Channel:
   • Navigate to the app details in your Library or on the Store page.
   • Click the version number to verify or switch the release channel to “ALPHA” (or your chosen channel).

Once installed, future updates from your GitHub Actions pipeline will appear as regular app updates on the headset!

Mission complete!

About Buildalon

Buildalon provides verified GitHub Actions and dedicated build infrastructure to streamline Unity development. Register for Buildalon to get support with your Unity build automation needs.

Further Reading

• How to Stream Unity Logs from Your Game
• Automating Unity Builds to iOS, macOS, and visionOS
• Automating Unity Builds with GitHub Actions