ApidogとGHE.comリポジトリの連携方法

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アプリを作成する

1. 組織のGHE.comテナントにサインインします。
2. OAuthアプリ設定を開きます。
3. 新しいOAuthアプリを作成します。
4. 識別可能なアプリケーション名を入力します。
5. ホームページURLを以下に設定します：https://apidog.com
6. 認証コールバックURLを以下に設定します：https://api.apidog.com/passport/github/callback
7. OAuthアプリを登録します。
8. **Client ID**をコピーします。
9. **Client Secret**を生成し、安全な場所にコピーします。

コールバックURLは、Apidogのドキュメントに記載されているURLと完全に一致している必要があります。

Client Secretは、承認された秘密管理システムに保存してください。スクリーンショット、チケット、共有ドキュメントに配置しないでください。

ステップ2：ApidogでGHE.comテナントを設定する

組織管理者のみがこの統合を設定または解除できます。

1. Apidog組織を開きます。
2. **組織設定**に移動します。
3. **GitHub統合**を開きます。
4. **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プロジェクトからリポジトリを接続する

組織レベルの設定が完了したら：

1. 必要なApidogプロジェクトを開きます。
2. Git接続またはGitインポートワークフローを開始します。
3. **GitHub Enterprise Cloud**を選択します。
4. 設定されたGHE.comテナントの認証ページに進みます。
5. サインインしてOAuthアプリを承認します。
6. GitHub組織を選択します。
7. リポジトリとブランチを選択します。
8. 接続を完了します。

認証は、設定されたGHE.comテナントで実行され、標準のgithub.comでは実行されません。

予期した組織またはリポジトリが見つからない場合は、Apidogの組織設定を変更する前に、GitHubアカウントのアクセス権とOAuthアプリの認証を確認してください。

ステップ4：OpenAPIファイルをインポートする

接続されたリポジトリからOpenAPIまたはSwaggerファイルをインポートするには：

1. Apidogプロジェクトでインポートワークフローを開始します。
2. **OpenAPI/Swagger**を選択します。
3. **Gitリポジトリ**を選択します。
4. GitHub組織、リポジトリ、ブランチ、およびファイルを選択します。
5. **続行**を選択します。
6. 既存のターゲットモジュールを選択するか、新しいモジュールを作成します。
7. インポートを完了します。
8. 結果を承認する前に、インポートされたエンドポイントとスキーマを確認します。

プロジェクトに必要なリポジトリ、ブランチ、仕様ファイルを選択します。

最初のインポートでは、特にターゲットモジュールにすでにAPI定義が含まれている場合は、非本番プロジェクトを使用してください。

ステップ5：継続的な同期ワークフローを選択する

リポジトリ接続は、さまざまなワークフローをサポートできます。唯一の信頼できる情報源（source of truth）を1つ選択し、チームのために文書化してください。

明確な競合解決ルールなしに、同じファイルに対して2つの相反する自動ワークフローを設定しないでください。

バックアップの場合：

1. プロジェクト設定でGit接続を作成または選択します。
2. モジュールの**概要 > API仕様**を開きます。
3. OpenAPI仕様を追加または選択します。
4. **Gitリポジトリへのバックアップ**を有効にします。
5. リポジトリ接続、ブランチ、およびターゲットファイルパスを選択します。
6. 設定を保存します。

リポジトリ駆動の信頼できる情報源（source of truth）については、スケジュールされたインポートを使用するか、Spec-firstモードを確認してください。

ステップ6：統合を確認する

小規模なエンドツーエンドテストを実行します。

1. 認証が設定されたGHE.comテナントを開くことを確認します。
2. 期待される組織とリポジトリのみが利用可能であることを確認します。
3. 既知のOpenAPIファイルをインポートし、結果をソースと比較します。
4. 使い捨てブランチで、選択したバックアップまたは同期の方向をテストします。
5. ブランチ保護とリポジトリ権限が期待通りに動作することを確認します。
6. 同期ログまたはエラーを確認します。
7. OAuthアプリのClient Secretをローテーションし、文書化された更新プロセスが機能することを確認します。

ウェブフック同期を使用している場合は、インストーラーがリポジトリ管理者権限を持ち、予期されるプッシュイベントが同期をトリガーすることを確認してください。

組織設定の更新またはクリア

組織管理者は、ホストURLまたはClient IDを編集したり、新しい値を入力してClient Secretをローテーションしたりできます。

組織レベルの設定を削除するには、**組織設定 > GitHub統合**を開き、データレジデンシー統合を見つけて**設定をクリア**を選択します。

設定がクリアされると、統合が再度設定されるまで、ユーザーは新しいGitHub Enterprise Cloud接続を作成できません。既存の接続は、トークンのステータスや組織設定によっては、再設定または再認証が必要になる場合があります。

トラブルシューティング

セキュリティとデータレジデンシーの境界

• 組織管理者のみが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リポジトリを接続します。

関連する公式ドキュメント：

• Apidog GitHub Enterprise Cloud
• Git接続
• スケジュールされたインポート
• Spec-firstモード
• GitHub: データレジデンシーについて
• GitHub: データレジデンシーでのデータの保存