AntigravityとGitHubの連携は、画面上では簡単に見えても、実際は認証方式、Webhook、権限設定の3点を揃えないと安定しません。
AIzen株式会社は、AI活用を前提にした開発フロー設計や実装支援を行う中で、まずGitHub側のアクセス設計を固めることを重視しています。
個人検証ならPAT、ユーザー認可が必要ならOAuth App、組織横断や本番運用ならGitHub Appを第一候補にし、Webhookは X-Hub-Signature-256 の検証まで含めて設定するのが安全です。
AntigravityとGitHubを連携する前に整理したい3つの詰まりどころ
連携エラーの多くは、Antigravity固有の問題ではなくGitHub側の前提整理不足で起こります。先に詰まりどころを見えている状態にしておくと、設定のやり直しを減らせます。
認証方式の選定で起きやすいミスと、PAT・OAuth App・GitHub Appの使い分け
一番多いのは、個人用のPATで始めた設定をそのまま組織運用へ持ち込むケースです。GitHub公式でも、OAuth AppよりGitHub Appのほうが細かい権限設定、短命トークン、集中Webhookの点で優先されています。用途に合わない方式を選ぶと、後から全面的な組み直しになります。
Webhookが届かないときに確認したいURL・Secret・イベント設定
Webhookが動かないときは、受信サーバーの問題と決めつけないことが重要です。Payload URLの誤り、対象イベント未選択、Secret未設定、受信側での署名検証失敗がよくある原因で、GitHubのRecent Deliveriesからかなりの範囲を切り分けられます。
トークン権限が足りない場合と広すぎる場合のエラーの違い
権限不足では 403 が出やすく、対象リポジトリに届いていない場合は 404 に見えることがあります。一方で権限を広く取りすぎると、本番運用でセキュリティレビューや組織承認が重くなります。最小権限で通す前提が基本です。
| 先に見る項目 | 典型的な症状 | 最初の確認先 |
|---|---|---|
| 認証方式 | ログインできるが運用に乗らない | PAT/OAuth/GitHub Appの選定 |
| Webhook | イベントが反応しない | Payload URL、Secret、Recent Deliveries |
| 権限 | APIやcloneが失敗する | スコープ、App permissions、SSO |
AntigravityとGithubの連携で最初に決める認証方式
ここを曖昧にすると、手順は合っていても運用設計が崩れます。まずは誰の権限で、どの範囲へ、どれくらい継続してアクセスさせるかを決めてください。
Personal Access Tokenが向くケースと向かないケース
PATは、個人リポジトリや短期間の検証には向きます。反対に、複数ユーザー利用、組織リポジトリ、本番自動化には不向きです。SAML SSOが有効な組織では、classic PATは作成後に Configure SSO から認可しないとアクセスできない点も見落としやすいです。
OAuth Appを選ぶケースと認可フローの基本
OAuth Appは、GitHubアカウントでユーザーにログインさせたいときに使います。GitHub公式のWeb application flowでは、client_id、redirect_uri、scope、state を設定し、必要に応じてPKCEも使います。ブラウザ経由でユーザー認可を得る設計と相性がよいです。
Organizationリポジトリ連携でGitHub Appを検討したいケース
組織リポジトリへの継続アクセス、Webhook一元管理、細かい権限制御が必要ならGitHub Appが第一候補です。GitHub公式でもOAuth Appより推奨されており、installation tokenでリポジトリ単位のアクセスを制御しやすく、運用担当者が変わっても構成を維持しやすいです。
| 方式 | 向く用途 | 注意点 |
|---|---|---|
| PAT | 個人検証、短期接続 | 組織運用やSSOで詰まりやすい |
| OAuth App | ユーザーログイン | redirect_uri と state 管理が必要 |
| GitHub App | 組織運用、自動化、Webhook | 権限設計とインストール設計が必要 |
AntigravityとGithub連携の認証設定手順
認証設定は、GitHub側の登録情報と、Antigravity側へ渡す接続情報を一致させる作業です。画面ごとに分けて考えると整理しやすくなります。
GitHub側でアプリを登録し、必要な認証情報を発行する
OAuth Appなら client_id と client_secret、GitHub AppならApp登録後に必要権限とWebhook設定を定義し、必要に応じて秘密鍵やinstallation flowを用意します。PATを使う場合でも、対象リポジトリに必要なアクセスだけを付けて発行してください。
SSO有効のOrganizationで認可が通らない場合の確認項目
SAML SSO環境では、トークンやアプリ認可の前に、ユーザー自身がその組織へSSOログイン済みかを確認する必要があります。GitHub公式でも、SSO対象組織ではPATやOAuth App、GitHub Appの再認可が必要になる場合があると案内されています。
PATでアクセス拒否が続く場合に見直したい設定と切り替え基準
PATで 403 や Repository not found が続く場合は、対象組織のSSO認可、権限不足、対象リポジトリ未付与を順に見直します。複数人が同じ設定を使うなら、ここで無理にPATを延命せず、GitHub Appへ切り替えたほうが後工程が軽くなります。
AntigravityとGithubの連携でWebhookを設定する手順
Webhookは「受け取れたか」だけでなく「正しい送信元か」を検証して初めて実運用に使えます。通知到達と署名検証をセットで考えてください。
Payload URLと受信エンドポイントを設定する
GitHubではWebhook作成時にURLとイベント種別を設定します。ローカル検証ならsmee.ioなどの転送を挟む方法も公式で案内されています。本番では、Antigravity側または中継サーバー側で受けるエンドポイントを固定し、イベント種別は必要なものだけに絞るのが基本です。
Webhook SecretとHMACシグネチャー検証を実装する
GitHub公式では、Webhook Secretを使い、受信時に X-Hub-Signature-256 をHMAC-SHA256で検証することを推奨しています。比較には通常の == ではなく、タイミング攻撃を避ける安全な比較関数を使うべきです。Secret未設定のまま本番へ出すのは避けてください。
Webhook受信後に処理が動かない場合の切り分け手順
Recent DeliveriesでHTTPステータス、送信ペイロード、再送結果を確認し、次に受信側ログで署名検証、JSONパース、イベント分岐の順に見ます。GitHubは2XX応答を10秒以内に返せないと失敗扱いになるため、重い処理は後段ジョブへ逃がす設計が安全です。
AntigravityとGithubの連携で見直したい権限設定とトークン管理
連携が通った後は、権限を狭めて安定運用に寄せます。ここを省くと、あとで監査や担当者交代のときに困ります。
必要な操作に合わせて権限スコープを最小化する
GitHub Appはデフォルト権限が空で、必要なrepository、organization、account permissionsを明示して付けます。REST APIで権限不足時は 403 になり、X-Accepted-GitHub-Permissions ヘッダーで必要権限を確認できるため、まず最小権限で試すのが効率的です。
SSO認可が反映されない場合の確認ポイント
classic PATは作成後にSSO認可が必要で、scope変更や再生成で再認可が必要になることがあります。OAuth AppやGitHub Appでも、組織がSSOを要求している場合は、アプリ認可時点で有効なSSOセッションがないと対象組織へ届きません。
トークンの保管・ローテーション・失効対応の基本
Secretやトークンはコードへ直書きせず、環境変数やシークレットマネージャーで管理します。期限付きトークンを基本にし、失効時の差し替え手順をRunbook化しておくと、担当者交代や緊急停止に対応しやすくなります。
弊社エンジニアからのコメント：
AntigravityとGitHubの連携では、接続手順そのものよりも、認証方式、Webhook、権限設定を最初に整理することが重要です。特に個人検証の延長でPATを使い続けると、組織運用や本番自動化の段階で見直しが必要になりやすいため、利用範囲に応じてOAuth AppやGitHub Appまで含めて選定する必要があります。
また、Webhookは通知を受け取れるだけでは不十分で、Secret設定や署名検証まで含めて設計しておくことが重要です。連携を安定させるには、最小権限の考え方を前提に、SSO認可やトークン管理、配信確認の手順まで運用に組み込んでおくことがポイントです。
AntigravityとGithubの連携完了前に確認したいテスト項目
最後は設定画面の保存ではなく、実際に連携が成立しているかを順番に確認します。テストの順序を固定すると、障害時も復旧しやすくなります。
認証成功・リポジトリアクセス・Webhook受信を順番に確認する
最初に認証だけを確認し、その後で対象リポジトリの参照、必要ならcloneやAPIアクセス、最後にWebhook受信を確認します。最初から全部まとめて試すと、どこで失敗しているのか分かりにくくなります。
403・404・署名検証失敗が出たときの確認順序を決める
403 は権限不足、SSO未認可、App permissions不足を疑います。404 は対象リポジトリ未付与や対象違いを疑います。署名検証失敗はSecret違い、受信前の本文改変、UTF-8処理の不一致を先に確認すると切り分けやすいです。
Recent Deliveriesを使ってWebhookの配信結果を確認する
Recent Deliveriesには、GitHubが何を送り、受信先が何を返したかが残ります。再送もできるため、コード修正後の確認がしやすいです。Webhookが届いているのに処理が動かない場合は、ここでGitHub側と受信側の責任範囲を分けられます。
| テスト順 | 確認内容 | 合格条件 |
|---|---|---|
| 1 | 認証 | ログインまたはinstallationが成功する |
| 2 | リポジトリアクセス | 対象repoを参照できる |
| 3 | Webhook受信 | Recent Deliveriesで2XXが返る |
| 4 | 署名検証 | X-Hub-Signature-256 を通過する |
まとめ
AntigravityとGitHubの連携で失敗しにくくするポイントは、次の3つです。
- 認証方式は、個人検証ならPAT、ユーザー認可ならOAuth App、組織運用ならGitHub Appを基準に選ぶことです。
- WebhookはURL登録だけで終わらせず、Secret設定と X-Hub-Signature-256 検証まで含めて完了と考えることです。
- 権限は最小化し、SSO認可、トークン保管、Recent Deliveriesでの確認手順まで運用に組み込むことです。
AIzen株式会社では、AIエージェント活用を前提にしたGitHub連携設計、Webhook実装、権限設計の整理まで伴走しています。自社の運用条件に合わせて安全に連携したい場合は、実装前の設計段階からご相談ください。
コメント