メインコンテンツまでスキップ

GitHubアプリのインテグレーション

GitHub Cloudユーザー向けにサポート

Bitrise GitHubアプリは、すべてのGitHub Cloudユーザーでサポートされています。GitHub Enterprise Serverユーザーは、GH Enterprise 連携ガイドで説明されているとおり、別のGitHubアプリを作成してインストールする必要があります。

BitriseアカウントをGitHubリポジトリに接続する最も良い方法は、GitHubアプリと連携することです。Bitrise GitHubアプリには、連携を簡単にするさまざまな機能があります。

  • このアプリを使用すると、SSHキー、Personal Access Token、service credential userが不要になります。アクセスには、ビルドごとに一時的なアクセストークンを生成するため、セキュリティが大幅に向上します。
  • リポジトリへのきめ細かなアクセスを提供します。GitHub組織全体にアクセス権を付与する必要はなく、アプリがアクセスできる特定のリポジトリを選択できます。
  • アプリをインストールすると、GitHub Checksアプリにより、Bitriseのステータス更新がGitHub上に自動的に直接表示されます。ステータスレポートを別途設定する必要はありません。なお、1つのBitrise Workspaceに接続できるGitHubアカウントは1つのみですが、GitHub Checksは他のGitHubアカウントが所有するリポジトリに対しても設定できます。
HTTPS URLが必要

GitHubアプリでは、リポジトリにSSHではなくHTTPS URLが必要です。通常はこの点を気にする必要はありません。GitHubアプリ連携を設定すると、プロジェクトのURLが変更されます。問題が発生した場合は、リポジトリのURLを変更する手順に従って手動でURLを変更できます。

イベントサブスクリプションClick to copy link​

リポジトリまたは組織にBitrise GitHubアプリをインストールすると、GitHubはそのインストールに対してイベントサブスクリプションを自動的に登録します。これらは、GitHubのリポジトリ設定で手動設定できるリポジトリレベルのWebhookとは別のものです。

Bitrise GitHubアプリは、次のイベントをサブスクライブします。

  • push: ブランチへのプッシュおよびタグのプッシュでビルドをトリガーします。
  • pull_request: プルリクエストが作成、更新、または同期されたときにビルドをトリガーします。
  • issue_comment: プルリクエストでのコメントベースのビルドトリガーを有効にします。

これらのサブスクリプションは、アプリのインストールレベルでGitHubにより管理されます。GitHubリポジトリのSettings → WebhooksにWebhookとして表示されることはありません。

GitHubアプリへの切り替え後は手動のWebhookを削除

リポジトリにhooks.bitrise.ioを指す手動設定のWebhookがすでに存在する場合(たとえば、以前のOAuthベースのBitrise連携によるものなど)、該当する各イベントで2つのビルドがトリガーされます。1つはGitHubアプリのサブスクリプションから、もう1つは手動のWebhookからです。

GitHubアプリに切り替えたあとは、ビルドの重複を避けるため、GitHub上のリポジトリのSettings → Webhooksページから手動のBitriseWebhookをすべて削除してください。

GitHubアプリ連携のインストールClick to copy link​

このガイドは、Bitrise GitHubアプリをインストールし、Bitrise WorkspaceをアプリでGitHubアカウントまたは組織に接続したいGitHub Cloudユーザー(GitHub Enterprise Cloudユーザーを含む)を対象としています。

GitHub Enterprise Serverユーザー向けには、別のガイドGitHub EnterpriseとBitriseの連携を用意しています。

GitHubアプリ連携経由での接続には、2つの方法があります。

  • Workspace settingsページから。
  • 新しいBitrise projectを追加するとき。
WorkspaceあたりのGitHubアプリインストール数

次の点に注意してください。

  • 1つのWorkspaceに接続できるGitHubアプリのインストールは最大10個までです。
  • 1つのGitHubアプリのインストールを複数のWorkspacesに接続することはできません。
  • アプリのGitHub Checks機能は、他のGitHubアカウントが所有するリポジトリでも利用できます。

Workspace settingsページからのGitHubアプリの接続Click to copy link​

Bitrise GitHubアプリのインストールはWorkspaceに紐づいています。インストールと接続状況の確認は、いつでもWorkspace settingsページから行えます。

GitHub上のSSO

SAML SSOが必要なGitHub組織向けにGitHubアプリ連携をインストールする場合、組織のリポジトリに接続するにはGitHub上でアクティブなSAML SSOセッションが必要です。

インストール済みのGitHubアプリが本来アクセスできるはずのall repositoriesにアクセスできない場合は、アクティブなSAML SSOセッションがある状態でGitHub上でアプリを取り消してから再度認証する必要がある場合があります。

詳細情報と手順については、GitHubのドキュメントを確認してください。

  1. Bitriseのメインページで、ドロップダウンメニューからWorkspaceを選択します。

  2. 左側のナビゲーションメニューからSettingsを選択します。

  3. Workspace settingsページでIntegrationsを選択します。

  4. GitHubを選択し、Connectをクリックします。

    github-account-connection.png

  5. これまでにBitrise GitHubアプリを認証したことがない場合、この時点で認証を求められます。

  6. 接続したいGitHub accountまたは組織を選択するよう求められます。必要なものがリストに見つからない場合は、先にそのアカウントまたは組織にアプリをインストールする必要があります。アカウントのリストの下にあるリンクをクリックしてください。

    install-the-app.png

  7. リンクをクリックすると、アカウントまたは組織を選択するよう求められます。選択すると、Install & Authorizeページに移動します。

  8. Install & Authorizeページで、アクセスの種類を選択します。

    • All repositories: Bitrise GitHubアプリが、そのアカウントまたは組織に属するall repositories(今後追加されるものを含む)にアクセスできるようになります。
    • Only select repositories: Bitriseがアクセスできるようにするリポジトリを1つ以上選択します。あとから追加することもできますが、その場合はGitHub Appのページでリポジトリへのアクセスを再設定する必要があります。

    authorizing-app.png

  9. 完了したらInstall & Authorizeをクリックします。Workspace settingsページにリダイレクトされます。

    認証

    GitHub上でnot authorizedの場合でも、アプリのインストールをリクエストできます。GitHubの管理者がインストールを承認したら、戻ってリストからApp installationを選択してください。

  10. OAuth連携を使用している既存のアプリがある場合は、GitHubアプリ連携への切り替えをお勧めします。

新しいプロジェクトを追加するときのGitHubアプリの接続Click to copy link​

GitHub上のSSO

SAML SSOが必要なGitHub組織向けにGitHubアプリ連携をインストールする場合、組織のリポジトリに接続するにはGitHub上でアクティブなSAML SSOセッションが必要です。

インストール済みのGitHubアプリが本来アクセスできるはずのall repositoriesにアクセスできない場合は、アクティブなSAML SSOセッションがある状態でGitHub上でアプリを取り消してから再度認証する必要がある場合があります。

詳細情報と手順については、GitHubのドキュメントを確認してください。

Bitriseで新しいプロジェクトを追加する過程で、Bitriseがリポジトリにどのようにアクセスするかを選択する必要があります。この過程で、GitHubアプリ経由でプロジェクトを接続できます。

  1. 新しいプロジェクトの追加を開始します。

  2. Select a repositoryセクションで、ProviderドロップダウンメニューからGitHub App (recommended)を選択します。

    select-repository.png

  3. Connect accountをクリックします。

    connect-github-app.png

  4. 接続したいGitHub accountまたは組織を選択するよう求められます。必要なものがリストに見つからない場合は、先にそのアカウントまたは組織にアプリをインストールする必要があります。アカウントのリストの下にあるリンクをクリックしてください。

    install-the-app.png

  5. リンクをクリックすると、アカウントまたは組織を選択するよう求められます。選択すると、Install & Authorizeページに移動します。

  6. Install & Authorizeページで、アクセスの種類を選択します。

    • All repositories: Bitrise GitHubアプリが、そのアカウントまたは組織に属するall repositories(今後追加されるものを含む)にアクセスできるようになります。
    • Only select repositories: Bitriseがアクセスできるようにするリポジトリを1つ以上選択します。あとから追加することもできますが、その場合はGitHub Appのページでリポジトリへのアクセスを再設定する必要があります。

    authorizing-app.png

  7. 完了したらInstall & Authorizeをクリックします。新しいBitrise projectの追加を続けるためにリダイレクトされます。

複数のGitHub組織を1つのBitrise workspaceに接続する

メインのソースコードとは別のGitHub組織/アカウントに保存されているコードにビルドからアクセスしたい場合は、+ Add GitHub accountボタンを使用して複数のGitHub組織をBitrise Workspaceに接続できます。

WorkspaceのGitHubアプリページでは、Bitrise GitHubアプリをインストール済みのプロジェクト管理者が+ Add GitHub accountボタンを見つけられます。これにより、workspaceに最大10個のGitHub account/組織を接続できます。

multipleGithuborgs.png

GitHub アプリの権限をビルドに拡張するClick to copy link​

APIの使用

このセクションでは、Bitrise websiteでの機能の設定方法を説明します。Bitrise APIからも設定できます。GitHub アプリの設定 API

Bitrise GitHub アプリは、そのアプリを介してトリガーされるビルドごとに、短期間有効な一時トークンを生成します。このトークンには、デフォルトでは content:read という権限だけが付与されています。つまり、ビルドは GitHub リポジトリにアクセスできますが、それ以外の操作はできません。

トークンの有効期間

トークンの有効期間は 1 時間です。この上限は GitHub が設定しており、延長できません。Bitrise はビルドがトリガーされた時点でトークンを生成するため、ビルドが保留状態やキューで待機している時間も、この 1 時間に含まれます。

これらの権限を拡張すると、ビルド中にその他の操作を実行できるようになります。たとえば、ビルドから Git タグをプッシュする、カスタムのステータスレポートを作成する、プルリクエストにラベルを付ける、新しいバージョン番号をプッシュする、といったことが可能になります。

リンクされたリポジトリ

権限を拡張すると、追加でリンクされているすべてのリポジトリにも権限が拡張されます。

拡張できる権限は、GitHub アカウントによって異なります。

  • GitHub Cloud では、GitHub アプリに次の権限があります。

    • issue とメタデータへの読み取りアクセス
    • チェック、コード、コミットステータス、プルリクエストへの読み取りおよび書き込みアクセス
  • GitHub Enterprise Serverのユーザーは、アプリの作成時に GitHub アプリの権限を定義します。

権限を拡張するには、次の手順に従います。

  1. プロジェクトに対するAdminのロールを持つユーザー、またはEdit workflow権限を持つカスタムロールを持つユーザーで、Bitrise上のプロジェクトを開きます。

  2. プロジェクトのメインページで、Project settingsボタンをクリックします。

  3. メニューから Repository を選択します。

  4. Extend GitHub App permissions to builds オプションを見つけてオンにします。これにより、デフォルトのリポジトリと、追加でリンクされているすべてのリポジトリにも権限が拡張されます。

GitHubアプリ経由の追加リンクリポジトリClick to copy link​

APIの使用

このセクションでは、Bitrise websiteでこの機能を設定する方法について説明します。GitHubアプリの設定APIを使用して、Bitrise API経由で設定することもできます。

各Bitrise projectには、プライマリのGitリポジトリがあります。プロジェクトのコードはここに保存され、ビルドを開始するとこのリポジトリがクローンされます。デフォルトでは、Bitrise projectは他のリポジトリにアクセスできません。

しかし、プロジェクトによっては他のリポジトリが必要になる場合があります。たとえば、ビルド中にアクセスする必要があるプライベートなサブモジュールがある場合です。GitHubアプリを使用している場合は、追加のリポジトリをリンクすることでこれに対応できます。この機能はGitHub CloudとGitHub Enterprise Serverの両方で利用できます。

他の接続方法

Bitrise GitHubアプリを使用していない場合でも、追加のリポジトリへのアクセスを設定できます。サブモジュールやプライベートリポジトリの依存関係があるアプリを参照してください。

リンクされたリポジトリとは、Bitrise projectがGitHubアプリのインストールを使用してアクセスできるものの、プロジェクトのプライマリリポジトリではないリポジトリのことです。

GitHubアプリのインストール経由で接続されたプロジェクトのビルドを実行すると、Bitriseはデフォルトでプライマリリポジトリにのみアクセスできる一時トークンを生成します。追加のリポジトリをリンクすると、ビルド用に生成されるトークンでその追加のリポジトリにもアクセスできるようになります。

リポジトリをリンクするには、次の条件をすべて満たす必要があります。

  • GitHub上でそのリポジトリを所有するアカウントまたは組織にGitHubアプリがインストールされていること。

  • そのリポジトリに対してアプリのインストールが有効になっていること。

  • リポジトリをリンクしようとしているユーザーが、GitHub上でそのリポジトリにアクセスできること。GitHubのユーザーアカウントがリポジトリにアクセスできない場合は、Bitrise上でそのリポジトリをリンクできません。

    GitHub Enterprise Server

    GitHub Enterprise Serverインスタンスへの接続にGitHubアプリを使用している場合、アプリはユーザーのアクセス権をチェックしません。GitHubアプリがアクセスできるリポジトリであれば、どれでもリンクできます。

追加のリポジトリをリンクするClick to copy link​

GitHubアプリの連携がすでに確立されているプロジェクトに追加のリポジトリをリンクするには:

  1. プロジェクトに対するAdminのロールを持つユーザー、またはEdit workflow権限を持つカスタムロールを持つユーザーで、Bitrise上のプロジェクトを開きます。

  2. プロジェクトのメインページで、Project settingsボタンをクリックします。

  3. 左側でRepositoryを選択します。

  4. Authorizationで、Additional repositoriesカードを見つけてChangeをクリックします。

  5. Link additional repositoriesダイアログで、リンクしたいリポジトリを選択します。

    SCR-20260331-pmhi.png

    追加のリポジトリは最大50個までリンクできます。

    リポジトリの一覧が表示されます。リポジトリを一覧に表示するには:

    • GitHub Cloud上では、GitHubユーザーがそのリポジトリにアクセスできる必要があります。GitHub Enterprise Serverを使用している場合、ユーザー権限はチェックされません。
    • GitHubアプリのインストールがそのリポジトリにアクセスできること。
    リポジトリの無効化

    すでにリポジトリがリンクされている場合、それらのリポジトリへのアクセス権を本来持たないユーザーでも無効化はできますが、再度追加することはできない点に注意してください。

  6. 完了したらSave changesをクリックします。

all repositoriesを自動的にリンクするClick to copy link​

GitHub組織のオーナーは、Grant access to all current and future repositoriesトグルを切り替えることで、GitHubアプリがアクセスを許可されているすべてのGitHubリポジトリ(今後追加される新しいリポジトリを含む)にBitriseのビルドがアクセスできるようにできます。

この機能を正しく使用するには:

  • セキュリティ上の理由から、組織のGitHubオーナーでもあるBitriseユーザーとしてログインしている必要があります。オーナーでない場合は、オーナーにBitriseにログインしてこの機能を有効にしてもらってください。
  • 必要なリポジトリにアクセスできるようにGitHubアプリを設定していることを確認してください。
  1. Bitriseで、プロジェクトのProject Settingsページに移動します。

  2. 左側でRepositoryを選択します。

  3. AuthorizationでAdditional repositoriesを見つけてChangeをクリックします。

  4. Grant access to all current and future repositoriesスイッチを右側に切り替えます。

    linkadditionalrepositories.png

    これで、プロジェクトのビルドは、Bitrise GitHubアプリがアクセスできる現在および将来のGitHubリポジトリすべてにアクセスできるようになります。

権限の許可に関するGitHubのメール通知

Bitriseがこの機能をリリースした際、Bitrise GitHubアプリのユーザーは、Grant access to all current and future repositoriesトグルの使用に必要な新しい権限についてGitHubからメールを受け取りました。Bitrise GitHubアプリは、「read organization membership」と呼ばれる追加の権限をリクエストします。メール内のリンクをたどってこの機能をチームで利用可能にする権限を持つのは、GitHubの組織オーナーのみです。

これはGitHubからの標準的かつ正規のメッセージであり、この権限を許可してもBitriseのビルドに悪影響を及ぼすことはありません。Bitriseが必要とする新しい権限の詳細はこちらをご覧ください。

GitHubアプリ経由でプライベートなStepライブラリを使用するClick to copy link​

各Bitrise projectには、デフォルトのStepライブラリ(Stepsのリポジトリ)があります。Stepの正確な取得元が設定で指定されていない場合、Bitrise CLIはデフォルトのライブラリからStepデータを取得します。

このライブラリは、プライベートなStepライブラリにすることもできます。GitHubアプリ経由でそのようなライブラリにアクセスするには、Workflow内で最初に実行されるStepとしてAuthenticate host with netrc Stepを追加する必要があります。

format_version: "13"
default_step_lib_source: https://github.com/my-private-org/my-bitrise-steplib.git
project_type: ios
workflows:
example:
steps:
- https://github.com/bitrise-io/bitrise-steplib.git::authenticate-host-with-netrc@0:

Authenticate host with netrc Stepには、プライベートライブラリではなく公式のBitrise Stepライブラリから確実に取得されるように完全なソース識別子が指定されている点に注意してください。

Stepを使用するには、host、Gitのユーザー名、Gitのパスワードという3つの入力を指定する必要があります。Bitrise GitHubアプリ連携ではトークンベースの認証が使用されます。各ビルドは、GIT_HTTP_PASSWORD環境変数の下で1回限りのトークンを受け取ります。この環境変数はパスワードとして使用できます。ユーザー名を空にするとStepが失敗するため空にはできませんが、実際には使用されないため、何を入力しても構いません。

format_version: '13'
default_step_lib_source: https://github.com/tothszabi/steplib.git
project_type: ios
workflows:
example:
steps:
- https://github.com/bitrise-io/bitrise-steplib.git::authenticate-host-with-netrc@0:
inputs:
- host: github.com
- username: username
- password: "$GIT_HTTP_PASSWORD"
- private-script@1: {}

リンクされたリポジトリでgit cloneを実行するClick to copy link​

リンクされたリポジトリに対してgit cloneやその他のgitコマンドを実行しようとすると、ビルドが認証エラーで失敗することがあります。これは、認証情報がローカルのnetrcファイルに保存されているためです。このファイルは、公式のGit Clone Stepによって自動的に生成されます。

ただし、独自のスクリプトでgit cloneを行う場合や、Git Clone Stepより前に認証が必要な他のGitコマンドを使用する場合は、netrcファイルを作成する必要があります。方法は2つあります。

HTTP URL

プライベートリポジトリの依存関係をクローンする際は、必ずHTTP URLを使用してください。

Stepを使用するには、host、Gitのユーザー名、Gitのパスワードという3つの入力を指定する必要があります。Bitrise GitHubアプリ連携ではトークンベースの認証が使用されます。各ビルドは、GIT_HTTP_PASSWORD環境変数の下で1回限りのトークンを受け取ります。この環境変数はパスワードとして使用できます。ユーザー名を空にするとStepが失敗するため空にはできませんが、実際には使用されないため、何を入力しても構いません。

workflows:
example:
steps:
- authenticate-host-with-netrc@0:
inputs:
- host: github.com
- username: "username"
- password: "$GIT_HTTP_PASSWORD"

OAuth接続からGitHubアプリへの切り替えClick to copy link​

Using the API

ここでは、Bitrise websiteで機能を設定する方法を説明します。Bitrise APIからも設定できます。GitHubアプリの設定 API

Bitrise プロジェクトに、GitHubアカウントへのOAuth接続が設定されている場合、機能を失うことなく、いつでもBitrise GitHubアプリに切り替えることができます。切り替えを強くお勧めします。Bitrise GitHubアプリをインストールすれば、Bitriseビルドの実行にservice credential user、SSHキー、Webhookは不要になります。

HTTPS URL required

GitHubアプリでは、リポジトリに対してSSHのものではなく、HTTPS URLが必要です。通常は気にする必要はありません。GitHubアプリ接続を設定すると、プロジェクトのURLが変更されます。問題がある場合は、URLを手動で変更できます。Changing the repository URL

切り替えるには、次の手順を実行します。

  1. 該当するガイドに従ってInstall the Bitrise GitHub Appします。Installing the GitHub App integration

  2. プロジェクトに対するAdminロールを持つユーザーで、Bitriseのプロジェクトを開きます。

  3. プロジェクトのメインページで、Project settingsボタンをクリックします。

    project-settings-button.png

  4. 左側のナビゲーションメニューで、Repositoryを選択します。

  5. GitHub Appのサポートに関する情報が表示された青いカードが表示されます。切り替えるには、Setup GitHub Appをクリックします。

    SCR-20260331-prho.png

  6. GitHub Appの設定が完了したら、WebhooksタブのIncoming Webhooksページから、既存の手動Webhookをすべて削除してください。

    このページには、Project Settings → Integrations → Webhooksタブ → Incoming Webhooksの順に移動して開けます。削除しないと、ビルドが重複してトリガーされます。詳細については、Event subscriptionsを参照してください。

  7. 必要に応じて、service credential userと、OAuth接続に使用していたSSHキーやパーソナルアクセストークンを削除できます。

OAuth連携への切り戻しClick to copy link​

GitHubアプリに切り替える前にリポジトリへのアクセスにOAuth連携を使用していた場合、いつでもその連携に戻すことができます。

注記

OAuth連携では、authorization methodに応じて、Gitプロバイダー側でSSHキーまたはpersonal access tokenが必要です。GitHubアプリに切り替える際にこれらを削除する必要はありません。削除していなければ、OAuth連携に戻すときにそのまま使用できます。

  1. プロジェクトに対するAdminのロールを持つユーザー、またはEdit workflow権限を持つカスタムロールを持つユーザーで、Bitrise上のプロジェクトを開きます。

  2. プロジェクトのメインページで、Project settingsボタンをクリックします。

  3. Bitrise CIでIntegrationsを選択し、次にGit providerタブを選択します。

  4. Connection typeカードを見つけてChangeをクリックします。

  5. ダイアログでOAuthを選択し、Changeをクリックします。