Configuring Build Hub for GitHub Actions

概要

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

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

Create a machine pool on Bitrise.

The machine pool requires authentication information. You can either:
- Install the Bitrise - Build Hub GitHub app while creating the machine pool. We recommend this authentication method.
- Create a GitHub personal access token.
Configure your GitHub Actions workflow to use Bitrise infrastructure for your builds.

Creating GitHub personal access tokens for Build Hub

You can use a GitHub personal access token to authenticate Build Hub to GitHub Actions. 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: [認証].

Go through the process described here until you get to selecting a resource owner.
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.
Under Repository access, select All repositories.
Under Permissions, select Organizations.
Click Add permissions.
Select Self-hosted runners.
Set the access to Read and write.
Click Generate token.
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: [認証].

Go through the process described here until you get to selecting the scopes.
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.
Click Generate token.
Copy your personal access token: you won't be able to see it again but you need it when creating a machine pool.

マシンプールの作成

Bitriseハードウェア上でGitHub Actionビルドを実行できるマシンプールを作成します。このプロセスは、使用するかどうかによって少し異なります。 GitHub アプリケーションまたは GitHub パーソナルアクセストークン認証用。

GitHub アプリケーション認証

GitHub パーソナルアクセストークン

左側のナビゲーションバーで、ビルドハブ。
クリック +マシンプール。
を開くアカウントを選択ドロップダウンメニューをクリックしてクリックアカウントを接続。
GitHub を選択してください (GitHub アプリケーション) そしてクリックインストールを続行。
リソース所有者を選択します。
リポジトリスコープを選択します。
- すべてのリポジトリ: リソース所有者が所有する現在および将来のすべてのリポジトリに適用されます。パブリックリポジトリ (読み取り専用) も含まれます
- リポジトリのみを選択: リポジトリを少なくとも 1 つ選択してください。パブリックリポジトリ (読み取り専用) も含まれます
ランナーグループとオプションでランナーバージョンを追加し、をクリックします。 [次へ]。
- ランナーのバージョンは v2.328.0 のように正確である必要があります。ランナーバージョンを指定しない場合、最新バージョンが使用されます
- ランナーグループ複数のランナーを集め、その周囲にセキュリティ境界を設けるために使用されます。
Check Use Bitrise for GitHub Actions caching if you want Bitrise infrastructure to handle GitHub Actions cache requests instead of GitHub's cache backend.

This results in faster cache operations.
Click Next.
プールに一意の名前を設定します。
で画像を選択します [イメージ] ドロップダウンメニューと必要なマシンの数マシン数フィールド。

で画像を確認できますスタックレポートページ。
マシンタイプを選択します。

Bitriseマシンの詳細については、以下をご覧くださいマシンを構築する。
ローリングアップデートの割合を設定します。これは、再構成後に同時に再起動されるマシンの数です。
完了したら、をクリックします [次へ]。
ラベルの作成:次のことが可能になります GitHub アクション設定 Bitrise ランナープールをターゲットにするためです。少なくとも 1 つのラベルが必要です

ラベルはキーと値のペアですが、必須はキーだけです。デフォルトでは、Bitriseはプール名、イメージ、マシンタイプのラベルを提案します。これらはいつでも変更できます
オプションで、ウォームアップスクリプトを追加してビルド環境をカスタマイズします。完了したら、をクリックしますプールを作成。

ウォームアップスクリプトが必要ない場合は空のままにしてください。

0 以外の終了コード

エラーが発生した場合は、必ず 0 以外の終了コードを返すようにしてください。スクリプトが失敗するのは、スクリプトが 0 以外の終了コードを返した場合だけです

左側のナビゲーションバーで、ビルドハブ。
クリック + マシンプール。
を開くアカウントを選択ドロップダウンメニューをクリックしてクリックアカウントを接続。
クリックアカウントを接続そして選択してください GitHub (PAT)。
接続名とターゲットスコープ URL を設定します。

ターゲットスコープの詳細については、こちらをご覧ください。ターゲットスコープ
の中に個人アクセストークンフィールドに GitHub 個人アクセストークンを追加してクリック [接続]。
ランナーグループと、オプションでランナーバージョンを追加します。
- ランナーのバージョンは v2.328.0 のように正確である必要があります。ランナーバージョンを指定しない場合、最新バージョンが使用されます
- ランナーグループ複数のランナーを集め、その周囲にセキュリティ境界を設けるために使用されます。
Check Use Bitrise for GitHub Actions caching if you want Bitrise infrastructure to handle GitHub Actions cache requests instead of GitHub's cache backend.

This results in faster cache operations.
Click Next.
プールに一意の名前を設定します。
で画像を選択します [イメージ] ドロップダウンメニューと必要なマシンの数マシン数フィールド。

で画像を確認できますスタックレポートページ。
マシンタイプを選択します。

Bitriseマシンの詳細については、以下をご覧くださいマシンを構築する。
ローリングアップデートの割合を設定します。これは、再構成後に同時に再起動されるマシンの数です。
完了したら、をクリックします [次へ]。
ラベルの作成:次のことが可能になります GitHub アクション設定 Bitrise ランナープールをターゲットにするためです。少なくとも 1 つのラベルが必要です

ラベルはキーと値のペアですが、必須はキーだけです。デフォルトでは、Bitriseはプール名、イメージ、マシンタイプのラベルを提案します。これらはいつでも変更できます
オプションで、ウォームアップスクリプトを追加してビルド環境をカスタマイズします。完了したら、をクリックしますプールを作成。

ウォームアップスクリプトが必要ない場合は空のままにしてください。

0 以外の終了コード

エラーが発生した場合は、必ず 0 以外の終了コードを返すようにしてください。スクリプトが失敗するのは、スクリプトが 0 以外の終了コードを返した場合だけです

GitHub アクションワークフローを設定する

マシンプールを正常に作成したら、ビルドの実行時にマシンプールを使用するように GitHub Actions ワークフローを設定する必要があります。

を使う runs-on Bitrise マシンを指定するためのワークフロー内のプロパティ。ランナーに割り当てられたラベルに基づいてランナーをターゲットにできます

GitHub リポジトリを開いて選択してくださいアクション。
左側で、ワークフローの名前をクリックします。
ワークフローの名前の下で、をクリックしますデプロイ.yml。
を追加 runs-on Build Hub で実行したいジョブのプロパティ。次の場合に作成するラベルをターゲットにする必要がありますマシンプールの作成または更新。
- ラベルは 1 つだけ使用できます。これにより、指定したラベルを持つすべてのランナーが使用できるようになります
```
jobs:
  build:
    runs-on: xcode-26
```
- ラベルの配列を使用できます。ランナーが許可されるのは、指定されたラベルがすべて揃っている場合だけです。
```
jobs:
  build:
    runs-on: [bitrise-runner, xcode-26]
```

についての詳細は runs-on プロパティ、チェックして GitHub アクションドキュメンテーション。

Linux マシンがツールにアクセスできるようにする

Linuxマシンでは、ビルドハブでGitHub Actionsワークフローを実行するときに、Linuxイメージにプリインストールされているツールにアクセスするための回避策が必要です。

GitHub Actions ワークフローがを使用するとき container: Docker コンテナ内のステップを実行するプロパティです。ランナーはイメージのツール設定を壊すような方法で環境を変更します。つまり、ビルドはアクセスできないということです asdf ツールマネージャーなので、プリインストールされているツールにはアクセスできません。

問題を解決するには:

を追加 env GitHub Actions ワークフローのコンテナ設定へのプロパティ。3 つの環境変数を設定すると asdf そのコアスクリプトとプラグイン、インストール済みバージョン、シムがどこにあるか、そしてイメージのスクリプトをオーバーライドするには BASH_ENV=/.bashrc。
```
container:
  image: bitriseio/ubuntu-noble-24.04-bitrise-2025-android:latest
  env:
    ASDF_DIR: /root/.asdf
    ASDF_DATA_DIR: /root/.asdf
    BASH_ENV: /root/.asdf/asdf.sh
```

の下に defaults プロパティ、デフォルトシェルをに設定 bash。

container:
  image: bitriseio/ubuntu-noble-24.04-bitrise-2025-android:latest
  env:
    ASDF_DIR: /root/.asdf
    ASDF_DATA_DIR: /root/.asdf
    BASH_ENV: /root/.asdf/asdf.sh
  defaults:
    run:
      shell: bash

の下に steps プロパティ、イメージのデフォルトツールバージョンを次の場所にコピーするステップを追加 asdf 彼らを期待しています。
```
steps:
  - name: Setup environment
    run: |
      cp /root/.tool-versions "$HOME/.tool-versions"
```
すべての作業ディレクトリを安全なものとして扱うように Git に指示してください。これがないと、ディレクトリの所有権が一致しないために一部のコマンドが失敗する可能性があります
```
steps:
  - name: Setup environment
    run: |
      cp /root/.tool-versions "$HOME/.tool-versions"
      git config --global --add safe.directory '*'
```

このセクションの内容: