Skip to main content

Build Hub for GitHub Actions overview

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.

Find out how to set up Build Hub for GitHub Actions: Configuring Build Hub for GitHub Actions.

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 either the Bitrise - Build Hub GitHub app or a GitHub personal access token to authenticate the runners and enable proper management of the GitHub Action workflows and runner configurations.

We recommend using the GitHub app integration.

GitHub app authentication

The Bitrise - Build Hub app can be installed to a GitHub account or a GitHub organization. The app can be scoped to access either:

  • All repositories: All current and future repositories owned by the resource owner. Includes public repositories.

  • Select repositories: At least one repository must be selected. Build Hub won't be able to access other repositories owned by the same resource owner.

The app has the following access rights:

  • Read access to actions, metadata, and organization events.

  • Read and write access to organization self hosted runners.

Set up the Bitrise - Build Hub app before creating a machine pool.

GitHub personal access token

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

Create a personal access token before creating a machine pool.

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.

In this section: