CircleCI の GitHub 連携には、従来の GitHub OAuth app 連携と、新しい GitHub App 連携の2種類があります。
OAuth 連携を使用している組織でも GitHub App を追加インストールでき、既存のパイプラインを停止せずに新機能を利用できます。本記事では、2つの連携方式の違い、GitHub App の導入手順、重複ビルドの防止策を解説します。
2つの GitHub 連携方式の違い
CircleCI では、GitHub との連携方法が2種類あります。
| 項目 | GitHub OAuth app 連携 | GitHub App 連携 |
|---|---|---|
| 組織 URL |
/github/ または /gh/
|
/github/・/gh/・/circleci/
|
| インストール方法 | 組み込み済み（削除不可） | add-on として追加可能 |
| 権限の粒度 | リポジトリ全体 | ファイングレインド（細粒度） |
| アクセストークン | 長期トークン | 短期トークン（セキュリティ向上） |
| 推奨 | — | ✅ CircleCI 推奨 |
URL に /github/ が含まれる組織（OAuth 組織）では、GitHub OAuth app 連携が最初から有効になっており、これを削除することはできません。GitHub App 連携は、この組織に追加でインストールできます。両方が共存している状態を dual integration（デュアル統合） と呼びます。
OAuth から GitHub App 連携に移行する２つの理由
GitHub App 連携に移行することで、以下の２つのメリットが生まれます。
1: 新機能が導入されやすい
CircleCI の新しいトリガー・パイプライン機能は、主に GitHub App 連携を通じて提供されます。OAuth 連携は引き続き動作しますが、以下の機能は現時点で GitHub App 連携でのみ利用可能です。
- 1つのプロジェクトに複数のパイプラインを定義する機能
- config ファイルとアプリケーションコードを異なるリポジトリに配置する機能（クロスリポジトリ設定）
- PR のオープン・マージ・レビュー準備完了などのイベント単位でのトリガー設定
- GitHub 以外の外部システムからパイプラインを起動するカスタム Webhook
今後リリースされる新機能についても、CircleCI は GitHub App 連携を優先的な開発対象としており、OAuth 連携側に同等の機能が提供されるかどうかは明言されていません。
2: より安全な連携・アクセス制御が可能になる
また、GitHub App 連携は OAuth 連携と比較して、よりきめ細かいアクセス制御を提供します。
- リポジトリの選択的アクセス：CircleCI がアクセスできるリポジトリを組織単位で限定できます
- 最小権限の原則：必要な権限のみをリクエストします（OAuth は全リポジトリへの読み書き権限を要求）
- 短期トークン：リソースアクセスに長期トークンではなく短期トークンを使用します
OAuthでの連携との並行利用も可能
GitHub App連携はリポジトリ単位で設定できます。そのため、すべてのパイプラインを一度に切り替える必要はなく、OAuth連携とGitHub App連携は並行して利用できます。そのため、GitHub Appでしか利用できない機能やトリガーを必要としたリポジトリから段階的に移行することをお勧めします。
パイプラインタイプの違いと見分け方
GitHub App をインストールすると、同一プロジェクト内に2種類のパイプラインが共存できます。それぞれのパイプラインはバッジの色で区別できます。
| 項目 | OAuth パイプライン | GitHub App パイプライン |
|---|---|---|
| 画像 |  |
 |
| バッジ | グレー（GitHub OAuth） | パープル（GitHub App） |
| 1プロジェクトあたりの数 | 1本固定（削除不可） | 0本以上（自由に作成・削除） |
| config ファイルのパス |
.circleci/config.yml 固定 |
任意のリポジトリ・任意のパス |
| リネーム | 不可 | 可能 |
| 利用可能なトリガー | OAuth トリガー・スケジュール・API | GitHub App トリガー・カスタム Webhook・スケジュール（cron）・API |
すべてのパイプラインタイプは、Project Settings > Project setup から管理できます。
GitHub App のインストール手順
GitHub App のインストールは 組織管理者のみ が実行できる、組織全体への1回限りの操作です。インストールは以下の2ステップで完了します。
- CircleCI の VCS Connections から GitHub App をインストールする
- GitHub 上でリポジトリへのアクセス権を設定する
1. VCS Connections から Install GitHub App を実行する
CircleCI の Organization Settings > VCS Connections に移動し、Install GitHub App を選択します。インストール完了後は、以下のように Permissions と Repository access が表示されます。付与される権限はメタデータへの Read と、コード・コミットステータス・Issue・PR への Read/Write です。
2. GitHub 上でアクセス権を確認・設定する
VCS Connections から遷移すると、GitHub 上で「Install CircleCI App」の画面が表示されます。アクセスするリポジトリを「All repositories」または「Only select repositories」から選択し、Install をクリックします。
インストール後、GitHub の設定ページで CircleCI App に付与された権限とリポジトリアクセス設定を確認できます。
インストールに問題が発生した場合は、こちらのフォームからサポートに問い合わせることができます。
GitHub App パイプラインを追加作成する
GitHub App をインストールしただけでは、GitHub App パイプラインは作成されません。既存の OAuth パイプラインに加えて、GitHub App パイプラインを新規作成する必要があります。
現在の Project setup を確認する
対象プロジェクトの Project Settings > Project setup に移動します。GitHub OAuth バッジのついた既存パイプラインと、そのトリガー設定（「All pushes on リポジトリ名」）が確認できます。
Add pipeline から GitHub App パイプラインを作成する
右上の Add pipeline ボタンをクリックすると、GitHub App パイプラインの作成フォームが表示されます。パイプライン名を入力し、Config source（config ファイルが置かれているリポジトリ）と Checkout source（チェックアウト対象のリポジトリ）をそれぞれ選択します。
リポジトリを選択して入力を完了した状態が以下です。Config filepath はデフォルトで .circleci/config.yml が設定されていますが、任意のパスに変更することも可能です。
Save をクリックするとパイプラインが作成されます。この時点ではトリガーは未設定のため、「Add a trigger to automate when your pipeline runs.」というメッセージが表示されます。
GitHub App トリガーを追加する
パイプラインカード下部の GitHub trigger + をクリックすると、トリガーの作成フォームが展開されます。「Event」ドロップダウンから実行タイミングを選択できます。OAuth トリガーが「All pushes」などの2択のみだったのに対し、GitHub App トリガーでは「Tag pushes」「Pushes to default branch」「PR opened or pushed to, default branch and tag pushes」「PR opened」「Non-draft PR opened」など、イベントを細かく指定できます。
重複ビルドを防止する
OAuth トリガーと GitHub App トリガーが同一リポジトリに対して両方設定されている場合、1回の push で2回ビルドが実行されます。ここからは、二重実行を防止するため、OAuth トリガーでのパイプライン実行を停止する作業を行います。
トリガーを設定した GitHub App パイプラインと OAuth パイプラインが共存すると、以下のような状態になります。GitHub App パイプラインには GitHub App トリガーが設定され、下部の OAuth パイプライン）にも「All pushes」トリガーが存在するため、同一の push イベントで両方が起動します。
重複を防ぐには、OAuth パイプラインの GitHub トリガーを削除します。トリガー行をクリックして展開すると、削除ボタン（ゴミ箱アイコン）と編集ボタンが表示されます。
削除ボタンをクリックすると、確認のため「DELETE」の入力を求めるダイアログが表示されます。入力後 Delete trigger をクリックします。
削除が完了すると、OAuth パイプラインのトリガー欄に「Add a trigger to automate when your pipeline runs.」というメッセージが表示されます。カード下部の click here リンクから、削除した OAuth トリガーをいつでも再作成できます。
GitHub App 導入後に利用できる主な機能
GitHub App を導入することで、以下の機能が利用可能になります。
複数パイプラインと柔軟な config 配置
1つのプロジェクトに複数の GitHub App パイプラインを作成できます。各パイプラインの config ファイルは任意のリポジトリ・任意のパスに配置できるため、アプリケーションコードと CI 設定を別リポジトリで管理する構成が可能です。クロスリポジトリ設定の詳細は こちらの Changelog を参照してください。
豊富な GitHub App トリガーオプション
OAuth トリガーは「全 push」または「PR・デフォルトブランチ・タグへの push」の2択でしたが、GitHub App トリガーでは以下のようなイベント単位でのトリガー設定が可能です。
- All pushes：全リポジトリへの push をトリガーにする基本設定です。
- Tag pushes：リリースタグが作成されたタイミングで、ビルドやリリース処理を自動実行できます。
- Pushes to default branch：デフォルトブランチへの push のみに絞り込みます。
- PR opened or pushed to, default branch and tag pushes：PR の作成・更新とデフォルトブランチへの push をまとめてカバーします。
- PR opened：PR が作成された時点でビルドを開始できます。レビュー前の動作確認に活用できます。
- Non-draft PR opened：Draft を除いた PR のオープンのみをトリガーにします。
- その他多数（GitHub trigger event options を参照）
カスタム Webhook
GitHub 以外の外部システムから HTTP リクエストを送信してパイプラインをトリガーできます。イベント名とイベントソースはユーザーが自由に定義できるため、外部の監視ツールやデプロイシステムとの連携に活用できます。
スケジュールトリガーの cron 化
GitHub App パイプラインのスケジュールトリガーは cron 構文を使用します。OAuth パイプラインの独自 timetable 形式より柔軟な設定が可能です。
まとめ
CircleCI の OAuth 組織に GitHub App を追加インストールすることで、既存のパイプラインを停止せずに新機能を利用できます。インストールは Organization Settings > VCS Connections から実行し、Project setup で GitHub App パイプラインを追加作成します。導入後は OAuth トリガーを削除して重複ビルドを防止することを忘れずに実施してください。
GitHub App パイプラインが安定稼働した後は、OAuth トリガーを削除して GitHub App トリガーに一本化することで、管理がシンプルになります。
詳細情報は以下の公式ドキュメントを参照してください。