Skip to main content

Build Hub for GitHub Actions overview

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 capabilitiesClick to copy link​

  • 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.

RequirementsClick to copy link​

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

  • A Bitrise workspace.
  • A GitHub account.
  • A way to authenticate the Build Hub machines to GitHub Actions. You can either use a personal access token or the Bitrise - Build Hub app. We recommend using the app.
  • 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.

AuthenticationClick to copy link​

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 authenticationClick to copy link​

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.

You can install the app to the GitHub account or organization of your choice when creating a machine pool.

GitHub personal access tokenClick to copy link​

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:

Target scopeRequired permission for a classic tokenRequired permissions for a fine-grained access token
GitHub Enterprise (GHE) Cloud: https://github.com/enterprises/&lt;enterprise> GHE Server: https://<hostname>/enterprises/<enterprise>manage_runners:enterpriseNot supported
GitHub Cloud organization: https://github.com/&lt;org> GHE organization: https://<hostname>/<org>org:adminread/write permission to Self-hosted runners
GitHub Cloud repository: https://github.com/&lt;owner&gt;/&lt;repo> GHE repository: https://<hostname>/<owner>/<repo>workflowNot supported

Create a personal access token before creating a machine pool.

Provisioning machines for GitHub ActionsClick to copy link​

When creating a machine pool, you must request a certain number of machines that will run your builds. The number of machines we keep running at a time depends on the authentication method:

  • If you use our GitHub app: We create and start machines on-demand. When a GitHub Actions workflow starts, we provision a machine. If you start multiple GitHub Actions workflows at the same time, we start a machine for each, up to the maximum number of machines defined by the machine pool configuration. When the GitHub Actions build ends, the machines are shut down.
  • If you use a GitHub personal access token: We always keep running as many machines as you requested in the machine pool. If you need fewer machines at a given time, you need to manually reduce the number of machines in the machine pool configuration.

Target scopeClick to copy link​

When using a GitHub personal access token to authenticate the Build Hub, you need to set a target scope when creating a machine pool. 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:

Warmup scriptClick to copy link​

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 percentageClick to copy link​

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.