Skip to main content

Configuring Build Hub for GitHub Actions

Abstract

Create a personal access token, a Bitrise machine pool, and then configure your GitHub Actions workflow to successfully run it on Bitrise Build Hub infrastructure.

To successfully use Build Hub for GitHub Actions, you need to:

  1. Create a GitHub personal access token, either a classic or a fine-grained one, depending on your requirements.

  2. Create a machine pool on Bitrise.

  3. Configure your GitHub Actions workflow to use Bitrise infrastructure for your builds.

Creating GitHub personal access tokens for Build Hub

To authenticate Build Hub to GitHub Actions, you need personal access tokens on GitHub. You can use either a classic access token or a fine-grained access token, depending on your needs. Read more on how authentication works: Authentication for Build Hub.

To create the token on GitHub:

Fine-grained

Classic

Token availability

Only organization-level target scopes can have fine-grained access tokens: Authentication.

  1. Go through the process described here until you get to selecting a resource owner.

  2. Select a resource owner: it should be the organization.

    Authorization

    The organization might require authorization for the token: for example, you might be prompted to log in via SSO.

  3. Under Repository access, select All repositories.

  4. Under Permissions, select Organizations.

  5. Click Add permissions.

  6. Select Self-hosted runners.

  7. Set the access to Read and write.

    2026-02-06-github-token.png

  8. Click Generate token.

  9. Copy your personal access token: you won't be able to see it again but you need it when creating a machine pool.

Target scopes

Check the required permissions for the different target scopes: Authentication.

  1. Go through the process described here until you get to selecting the scopes.

  2. Select the right scope: it depends on the target scope you need for your machine pool.

    • GitHub Cloud organization (https://github.com/<org>) and GHE organization (https://<hostname>/<org>): org:admin

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

    • GitHub Cloud repository (https://github.com/<owner>/<repo>) and GHE repository (https://<hostname>/<owner>/<repo>): workflow.

  3. Click Generate token.

  4. Copy your personal access token: you won't be able to see it again but you need it when creating a machine pool.

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.

  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.

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

    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: