Skip to main content

Build Hub for GitHub Actions

Abstract

Bitrise Build Hub is a high-performance build infrastructure for GitHub Actions, purpose-built for mobile app development. It provides fully managed, zero-maintenance runners that execute your GitHub Actions workflows on the industry's fastest Apple silicon and Linux machines.

Bitrise Build Hub is a high-performance build infrastructure for GitHub Actions, purpose-built for mobile app development. It provides fully managed, zero-maintenance runners that execute your GitHub Actions workflows on the industry's fastest Apple silicon and Linux machines.

Key capabilities

  • M4 Pro Apple silicon and AMD EPYC Zen4/Zen5 Linux machines optimized for iOS and Android builds.

  • Latest Xcode versions within 24 hours of Apple release, including betas.

  • Mobile-optimized stacks with preinstalled tooling (Xcode, Android SDK, Flutter, React Native, and more).

  • Co-located caching for near-zero latency and no network egress costs.

  • US and EU data centers for data residency requirements.

  • Pre-warmed VM pools for instant build start with no queue times.

Build Hub works with both GitHub Cloud and GitHub Enterprise Server repositories. Your existing GitHub Actions workflow files stay unchanged—you only update the runs-on label to route builds to Bitrise infrastructure.

Requirements

To run your GitHub Actions workflows on Bitrise Build Hub infrastructure, you need:

  • A Bitrise workspace.

  • A GitHub account and a GitHub personal access token: the token authenticates the runner on GitHub and enables Workflow management and runner configuration.

  • A machine pool on Bitrise: you can select the machine type, the amount of machines, and the system image that contains the software configuration required to launch your instance.

Authentication

Bitrise Build Hub requires a GitHub personal access token for authentication. This token authenticates the runner and enables proper management of the GitHub Action workflows and runner configurations.

You can use two types of tokens:

The different token types require different access types, depending on your target scope. Check out the table below to see the exact permissions for the respective target scopes:

Table 1. Token permissions

Target scope

Required permission for a classic token

Required permissions for a fine-grained access token

GitHub Enterprise (GHE) Cloud: https://github.com/enterprises/<enterprise>

GHE Server: https://<hostname>/enterprises/<enterprise>

manage_runners:enterprise

Not supported

GitHub Cloud organization: https://github.com/<org>

GHE organization: https://<hostname>/<org>

org:admin

read/write permission to Self-hosted runners

GitHub Cloud repository: https://github.com/<owner>/<repo>

GHE repository: https://<hostname>/<owner>/<repo>

workflow

Not supported

Target scope

When you configure a machine pool for GitHub Actions, you need to specify a target scope. The target scope is the context in which the runner is allowed to operate, such as a specific repository or a GitHub organization.

The accepted target scopes are:

  • GitHub Cloud organization: https://github.com/<org>

  • GitHub Cloud repository: https://github.com/<owner>/<repo>

  • GitHub Enterprise (GHE) Cloud: https://github.com/enterprises/<enterprise>

  • GHE Server: https://<hostname>/enterprises/<enterprise>

  • GHE organization: https://<hostname>/<org>

  • GHE repository: https://<hostname>/<owner>/<repo>

Warmup script

Use a warmup script to customize your build environment and improve speed and performance. You can add any script to your configuration when creating a machine pool. The script will run when the machine is set up.

Make sure that it returns a non-zero exit code in case of an error. The script will only fail if your script returns with a non-zero exit code.

Rolling update percentage

When creating a machine pool for Build Hub, you can set a rolling update percentage. This is the ratio of machines that are immediately and simultaneously rebooted after you reconfigure an existing machine pool.

This allows users to update the runner configuration without losing ongoing builds. If you set the value to 100, all machines are rebooted immediately and ongoing builds are aborted.

Creating a machine pool

Create a machine pool that allows running CI builds on Bitrise hardware.

  1. Open your workspace settings page and select Build Hub.

  2. Click Machine pool.

  3. Set a unique name for the pool.

  4. Select the image in the Image dropdown menu and the amount of machines you need in the Nr. of machines field.

    You can check the images on the stack reports page.

    2026-02-04-machine-pool-image.png

  5. Select a machine type.

    For more information about Bitrise machines, check out Build machines.

  6. Set a rolling update percentage: this is the amount of machines to be rebooted simultaneously after reconfiguration.

    Leave it empty if you don’t need a warmup script.

  7. When done, click Next.

  8. Optionally, use labels to organize and categorize your pool.

    By default, Bitrise suggests labels for the pool name, the image, and the machine type. You can change these at any time.

  9. Optionally, add a warmup script to customize your build environment. When done, click Next.

    Non-zero exit code

    Make sure that it returns a non-zero exit code in case of an error. The script will only fail if your script returns with a non-zero exit code.

  10. Select GitHub from the CI tool dropdown menu.

  11. Set a target scope URL.

    Read more about target scopes here: Target scope

    20260204-machine-pool-target-scope.png

  12. Add your GitHub personal access token.

  13. Optionally, add a runner version and a runner group.

    • The runner version needs to be exact, such as v2.328.0. If you don't specify a runner version, the latest version will be used.

    • Runner groups are used to collect sets of runners and create a security boundary around them.

  14. Click Create pool.

Configuring your GitHub Actions workflow

After you successfully create a machine pool, you need to configure your GitHub Actions workflow to use the machine pool when running your builds.

Use the runs-on property in your workflow to specify the Bitrise machines. You can target runners based on the labels assigned to them, or their group membership, or a combination of these.

  1. Open your GitHub repository and select Actions.

  2. On the left, click the name of the Workflow.

  3. Under the name of the Workflow, click deploy.yml.

  4. Add the runs-on property to the jobs you want to run on Build Hub.

    • If you don't have a runner group, use self-hosted as the value:

      jobs:
  build:
    runs-on: self-hosted

    • If you use a runner group, the value should be group:<group-name>. For example:

      jobs:
  build:
    runs-on: 
      group: Bitrise-M4Pro

    • GitHub allows the use of labels in the configuration. For example, the following configuration only allows runners that have all three labels:

      jobs:
  build:
    runs-on: [self-hosted, linux, x64, gpu]

      You can create and edit labels when creating or updating a machine pool.

For more information on the runs-on property, check out the GitHub Actions documentation.

In this section: