Apidogは、専用の*.ghe.comドメインでホストされたGitHub Enterprise Cloudデータレジデンシーテナントに接続できます。組織管理者がテナントとOAuthアプリを設定すると、許可されたプロジェクトユーザーはリポジトリを接続し、OpenAPIのインポート、バックアップ、同期ワークフローを利用できます。
この統合は、GitHub Enterprise CloudデータレジデンシーSaaSテナント専用です。GitHub Enterprise ServerやカスタムGitHubドメインはサポートしていません。
始める前に
以下を準備します。
- 統合機能を利用できるApidog Enterprise組織
- Apidogの組織管理者権限
-
https://company.ghe.comのようなルート*.ghe.comドメイン上のGitHub Enterprise Cloudデータレジデンシーテナント - テナントでOAuthアプリを作成する権限
- 接続対象のGitHub組織、リポジトリ、ブランチへのアクセス権
リポジトリを接続するユーザーには、ApidogでプロジェクトレベルのGit接続権限も必要です。
ステップ1：GHE.comテナントでOAuthアプリを作成する
- 組織のGHE.comテナントにサインインします。
- OAuthアプリ設定を開き、新しいOAuthアプリを作成します。
- 識別可能なアプリケーション名を入力します。
- ホームページURLを
https://apidog.comに設定します。 - 認証コールバックURLを
https://api.apidog.com/passport/github/callbackに設定します。 - OAuthアプリを登録します。
- Client IDをコピーします。
- Client Secretを生成し、安全な場所にコピーします。
コールバックURLは、Apidogのドキュメントに記載されているURLと完全に一致している必要があります。
Client Secretは、承認済みの秘密管理システムに保存してください。スクリーンショット、チケット、共有ドキュメントには記載しないでください。
ステップ2：ApidogでGHE.comテナントを設定する
この統合を設定または解除できるのは組織管理者だけです。
- Apidog組織を開きます。
- 組織設定に移動します。
- GitHub統合を開きます。
- GitHub Enterprise Cloud Data Residencyを見つけ、設定を選択します。
- GHE.comホストURLを入力します（例：
https://company.ghe.com）。 - 認証方法としてOAuth Appを選択します。
- OAuthアプリのClient IDを入力します。
- OAuthアプリのClient Secretを入力します。
- 設定を保存します。
テナントホストとOAuthアプリの認証情報は、組織レベルで設定します。
保存後、Apidogは設定済みのホストURLを表示します。Client Secretが再表示されたり、事前入力されたりすることはありません。
設定を編集するときにClient Secretフィールドを空のままにすると、既存のシークレットが保持されます。新しい値を入力するのは、シークレットをローテーションする場合だけです。
ステップ3：Apidogプロジェクトからリポジトリを接続する
組織レベルの設定が完了したら、次の手順で接続します。
- 対象のApidogプロジェクトを開きます。
- Git接続またはGitインポートワークフローを開始します。
- GitHub Enterprise Cloudを選択します。
- 設定済みのGHE.comテナントの認証ページに進みます。
- サインインしてOAuthアプリを承認します。
- GitHub組織を選択します。
- リポジトリとブランチを選択します。
- 接続を完了します。
認証は標準のgithub.comではなく、設定済みのGHE.comテナントで実行されます。
組織またはリポジトリが表示されない場合は、Apidogの組織設定を変更する前に、GitHubアカウントのアクセス権とOAuthアプリの認証状態を確認してください。
ステップ4：OpenAPIファイルをインポートする
接続済みのリポジトリからOpenAPIまたはSwaggerファイルをインポートします。
- Apidogプロジェクトでインポートワークフローを開始します。
- OpenAPI/Swaggerを選択します。
- Gitリポジトリを選択します。
- GitHub組織、リポジトリ、ブランチ、ファイルを選択します。
- 続行を選択します。
- 既存のターゲットモジュールを選択するか、新しいモジュールを作成します。
- インポートを完了します。
- 結果を承認する前に、インポートされたエンドポイントとスキーマを確認します。
プロジェクトに必要なリポジトリ、ブランチ、仕様ファイルを選択します。
初回インポートでは、特にターゲットモジュールに既存のAPI定義がある場合、非本番プロジェクトを使用してください。
ステップ5：継続的な同期ワークフローを選択する
リポジトリ接続では、次のワークフローを利用できます。チーム内で信頼できる情報源（source of truth）を1つ決め、運用ルールを文書化してください。
| ワークフロー | 使用する状況 | 重要な動作 |
|---|---|---|
| 手動インポート | 必要なときだけ変更をApidogに取り込む | 各インポートとターゲットモジュールを確認する |
| スケジュールされたインポート | Gitファイルをソースとして、Apidogを一定間隔で更新する | 設定した実行モードに従い、ローカルクライアントまたはセルフホスト型Runnerで実行する |
| Gitへのバックアップ | Apidogのコンテンツをリポジトリファイルに書き込む | リポジトリ、ブランチ、ターゲットファイルパスを設定する。自動バックアップは夜間のランダムなオフピーク時間に実行される |
| Spec-firstモード | 仕様ファイルを唯一の信頼できる情報源として、Git中心のワークフローで編集する | 現在ベータ版。ウェブフックのインストールには通常、リポジトリ管理者権限が必要 |
明確な競合解決ルールがない状態で、同じファイルに相反する自動ワークフローを2つ設定しないでください。
Gitへのバックアップを設定する
- プロジェクト設定でGit接続を作成または選択します。
- モジュールの概要 > API仕様を開きます。
- OpenAPI仕様を追加または選択します。
- Gitリポジトリへのバックアップを有効にします。
- リポジトリ接続、ブランチ、ターゲットファイルパスを選択します。
- 設定を保存します。
リポジトリを信頼できる情報源にする場合は、スケジュールされたインポートまたはSpec-firstモードを確認してください。
ステップ6：統合を確認する
小規模なエンドツーエンドテストを実行します。
- 認証ページが設定済みのGHE.comテナントで開くことを確認する
- 期待する組織とリポジトリだけが利用可能であることを確認する
- 既知のOpenAPIファイルをインポートし、結果をソースと比較する
- 使い捨てブランチで、選択したバックアップまたは同期の方向をテストする
- ブランチ保護とリポジトリ権限が期待どおりに動作することを確認する
- 同期ログとエラーを確認する
- OAuthアプリのClient Secretをローテーションし、文書化した更新プロセスが機能することを確認する
ウェブフック同期を使用する場合は、インストーラーがリポジトリ管理者権限を持ち、想定したプッシュイベントで同期が開始されることも確認してください。
組織設定の更新またはクリア
組織管理者は、ホストURLまたはClient IDを編集できます。Client Secretをローテーションする場合は、新しい値を入力します。
組織レベルの設定を削除するには、組織設定 > GitHub統合を開き、データレジデンシー統合を見つけて設定をクリアを選択します。
設定をクリアすると、統合を再設定するまでユーザーは新しいGitHub Enterprise Cloud接続を作成できません。既存の接続も、トークンの状態や組織設定によっては再設定または再認証が必要になる場合があります。
トラブルシューティング
| 問題 | 確認事項 |
|---|---|
| 統合オプションが利用できない | 組織がEnterprise機能にアクセスでき、自分が組織管理者であることを確認する |
| OAuthがコールバックエラーを返す | OAuthアプリのコールバックがhttps://api.apidog.com/passport/github/callbackと完全に一致していることを確認する |
| 認証でgithub.comが開く | 組織レベルのホストが意図したルート*.ghe.comテナントであることを確認する |
| リポジトリが見つからない | 認証済みGitHubユーザーの組織・リポジトリへのアクセス権とOAuthの制限を確認する |
| プロジェクトユーザーが接続を作成できない | 必要なプロジェクトレベルのGit接続権限を確認する |
| インポートまたは同期が失敗する | 選択したブランチ、ファイルパス、ファイル形式、リポジトリ権限、同期ログを確認する |
セキュリティとデータレジデンシーの境界
- GHE.com統合を設定または解除できるのは組織管理者だけです。
- Client Secretは設定後に表示されません。
- プロジェクト権限によって、Git接続を作成または更新できるユーザーが制御されます。
- OAuth認証は設定済みのGHE.comテナントを通じて実行されます。
- OAuth権限には、組織、リポジトリ、ブランチの読み取り、ファイルのインポート、バックアップの書き込み、同期ワークフローで必要なリポジトリフックの管理に必要なアクセスが含まれる場合があります。
データレジデンシーテナントに接続しただけでは、GitHubまたはApidog関連のすべてのデータが単一リージョンに留まることは証明されません。GitHubは、レジデンシーサービスの対象データと関連する例外を文書化しています。Apidogは独自のストレージおよびデプロイメントモデルを持つ独立した接続サービスです。データレジデンシーまたはコンプライアンス評価では、両ベンダーの最新ドキュメントを確認してください。
関連するAPIガバナンスチュートリアル
エンタープライズAPIワークスペースを管理するための補完的な制御については、以下を参照してください。
- APIガバナンスフレームワーク：所有権、コントロール、証拠、ライフサイクルの判断をつなげる
- Microsoft Entra IDとのSAMLグループマッピング：IDプロバイダーのグループからチームアクセスを割り当てる
- シークレットスキャナー：Apidogアセットに露出する可能性のある認証情報を確認する
- 監査ログ：管理組織のアクティビティを調査・エクスポートする
- SCIMプロビジョニング：IDライフサイクル全体で組織ユーザーを管理する
- エンタープライズポリシー：認証情報、メンバーシップ、SSOセッション、招待を制御する
- セルフサービスAPIチーム：メンバー作成チームを許可しながら所有権を監視する
- GitHub Enterprise Cloud統合：OpenAPIワークフロー向けにサポート対象のGHE.comリポジトリを接続する
Top comments (0)