GitHub Enterprise Server リポジトリを作成する

  • [アーティクル]

Azure DevOps Services

オンプレミスの GitHub Enterprise Server と Azure Pipelines は、統合することができます。 オンプレミス サーバーはインターネットに公開されていることも、公開されていないこともあります。

Azure Pipelines サービスを実行するサーバーから GitHub Enterprise Server に到達できる場合:

  • クラシック ビルドと YAML パイプラインを設定できます
  • CI、PR、スケジュールされたトリガーを構成できます

Azure Pipelines サービスを実行するサーバーから GitHub Enterprise Server に到達できない場合:

  • クラシック ビルド パイプラインのみ設定できます
  • ビルドは手動またはスケジュールによってのみ開始できます
  • YAML パイプラインを設定することはできません
  • クラシック ビルド パイプラインのための CI トリガーまたは PR トリガーを構成することはできません

オンプレミス サーバーに Microsoft ホステッド エージェントから到達可能な場合は、それらを使用してパイプラインを実行できます。 できない場合は、オンプレミス サーバーにアクセスしてコードをフェッチできるセルフホステッド エージェントの設定が必要になります。

Azure Pipelines から到達可能

最初にチェックするのは、Azure Pipelines サービスが GitHub Enterprise Server に到達できるかどうかです。

  1. Azure DevOps UI でプロジェクト設定に移動し、[Pipelines] (パイプライン) の下にある [Service Connections] (サービス接続) を選択します。
  2. [New service connection] (新しいサービス接続) を選択して、接続の種類として [GitHub Enterprise Server] を選択します。
  3. GitHub Enterprise Server への接続を作成するために必要な情報を入力します。
  4. [service connection] (サービス接続) パネルで [Verify] (検証) を選択します。

検証に合格する場合、Azure Pipelines サービスを実行するサーバーは、オンプレミスの GitHub Enterprise Server に到達できます。 続けて接続を設定できます。 そうすれば、クラシック ビルドまたは YAML パイプラインを作成するときに、このサービス接続を使用できます。 また、パイプラインの CI トリガーと PR トリガーを構成することもできます。 GitHub と連携する Azure Pipelines の機能の大部分は、GitHub Enterprise Server でも動作します。 これらの機能を理解するには、GitHub のドキュメントを確認してください。 次のような違いがあります。

  • GitHub と Azure Pipelines の統合は、GitHub マーケットプレースの Azure Pipelines アプリを使用すると容易になります。 このアプリを使用すると、特定のユーザーの OAuth トークンに依存することなく、統合を設定できます。 GitHub Enterprise Server で動作する同様のアプリはありません。 そのため、PAT、ユーザー名とパスワード、または OAuth を使用して、Azure Pipelines と GitHub Enterprise Server 間の接続を設定する必要があります。
  • Azure Pipelines では、外部フォークからのコントリビューションを検証するための GitHub のセキュリティ機能が多数サポートされています。 たとえば、パイプラインに格納されているシークレットは、実行中のジョブでは使用できません。 これらの保護は、GitHub Enterprise Server を使用する場合は利用できません。
  • コメント トリガーは、GitHub Enterprise Server では使用できません。 GitHub Enterprise Server リポジトリの pull request でコメントを使用してパイプラインをトリガーすることはできません。
  • GitHub Checks は、GitHub Enterprise Server では使用できません。 すべてのステータス更新は、基本のステータスを通じて行われます。

Azure Pipelines から到達不可能

上記のセクションで説明した GitHub Enterprise Server への接続の検証が失敗した場合、Azure Pipelines はサーバーと通信できません。 これは、エンタープライズ ネットワークの設定方法が原因である可能性があります。 たとえば、ネットワーク内のファイアウォールによって、外部トラフィックがサーバーに到達できなくなる可能性があります。 この場合には、次の 2 つのオプションがあります。

  • IT 部門と協力して、Azure Pipelines と GitHub Enterprise Server の間のネットワーク パスを開きます。 たとえば、Azure Pipelines からのトラフィックの通過を許可するように、ファイアウォール規則に例外を追加できます。 許可する必要がある IP アドレスについては、Azure DevOps の IP に関するセクションを参照してください。 さらに、Azure Pipelines がサーバーの FQDN を IP アドレスに解決できるように、GitHub Enterprise Server のパブリック DNS エントリを用意する必要があります。 これらの変更をすべて行った後、Azure Pipelines で GitHub Enterprise Server への接続の作成と検証を試みます。

  • GitHub Enterprise Server への接続を使用する代わりに、その他の Git への接続を使用することもできます。 オプション [Attempt accessing this Git server from Azure Pipelines] (この Git サーバーに Azure Pipelines からアクセスしてみる) をオフにします。 この接続の種類では、クラシック ビルド パイプラインのみを構成できます。 この構成では、CI トリガーと PR トリガーは機能しません。 パイプラインの実行は手動またはスケジュールによってのみ開始できます。

Microsoft ホステッド エージェントから到達可能

また、パイプラインの実行に Microsoft ホステッド エージェントとセルフホステッド エージェントのどちらを使用するかについても決定する必要があります。 多くの場合、これは Microsoft ホステッド エージェントがサーバーに到達可能かどうかによって決まります。 それが可能かどうかをチェックするために、Microsoft ホステッド エージェントを使用する単純なパイプラインを作成して、サーバーからソース コードをチェックアウトする手順を必ず追加してください。 これに成功した場合は、Microsoft ホステッド エージェントを引き続き使用できます。

Microsoft ホステッド エージェントから到達不可

前述のセクションで説明した単純なテスト パイプラインがエラー TF401019: The Git repository with name or identifier <your repo name> does not exist or you do not have permissions for the operation you are attempting で失敗する場合、Microsoft ホステッド エージェントは GitHub Enterprise Server に到達できません。 前述したように、これはファイアウォールが該当するサーバーからのトラフィックをブロックしていることが原因であると考えられます。 この場合には、次の 2 つのオプションがあります。

  • IT 部門と協力して、Microsoft ホステッド エージェントと GitHub Enterprise Server の間のネットワーク パスを開きます。 Microsoft ホステッド エージェントのネットワークに関するセクションを参照してください。

  • セルフホステッド エージェントまたはスケール セット エージェントに切り替えます。 こうしたエージェントはネットワーク内に設定できるため、GitHub Enterprise Server にアクセスできるようになります。 そのようなエージェントで必要なのは、Azure Pipelines への送信接続だけです。 受信接続のためにファイアウォールを開く必要はありません。 GitHub Enterprise Server への接続の作成時に指定したサーバーの名前が、セルフホステッド エージェントから解決可能であることを確認します。

Azure DevOps の IP アドレス

Azure Pipelines は、GitHub Enterprise Server に次のことを行う要求を送信します。

  • パイプラインの作成時にリポジトリの一覧をクエリする (クラシック パイプラインと YAML パイプライン)
  • パイプラインの作成時に既存の YAML ファイルを検索する (YAML パイプライン)
  • YAML ファイルをチェックインする (YAML パイプライン)
  • パイプラインの作成時に Webhook を登録する (クラシック パイプラインと YAML パイプライン)
  • YAML ファイルのエディターを表示する (YAML パイプライン)
  • 実行前にテンプレートを解決し、YAML ファイルを展開する (YAML パイプライン)
  • 前回スケジュールされた実行以降に変更があるかどうかを確認する (クラシック パイプラインと YAML パイプライン)
  • 最新のコミットに関する詳細をフェッチし、ユーザー インターフェイスに表示する (クラシック パイプラインと YAML パイプライン)

YAML パイプラインには、根本的に Azure Pipelines と GitHub Enterprise Server 間の通信が必要であることがわかります。 そのため、Azure Pipelines から GitHub Enterprise Server に到達できない場合は、YAML パイプラインを設定できません。

クラシック パイプラインを設定するためにその他の Git 接続を使用し、Azure Pipelines サービスと GitHub Enterprise Server 間の通信を無効にし、コードのビルドにセルフホステッド エージェントを使用すると、次のようにエクスペリエンスが低下します。

  • パイプラインの作成時にリポジトリ名の手動による入力が必要になります
  • Azure Pipelines では GitHub Enterprise Server に Webhook を登録できないため、CI トリガーまたは PR トリガーを使用することはできません
  • スケジュールされたトリガーは、変更がある場合にのみビルドするオプションで使用できません
  • ユーザー インターフェイスでは最新のコミットに関する情報を表示できません

YAML パイプラインを設定したい場合、またはクラシック パイプラインのエクスペリエンスを強化したい場合は、Azure Pipelines から GitHub Enterprise Server への通信を有効にすることが重要です。

Azure DevOps からのトラフィックが GitHub Enterprise Server サーバーに到達できるようにするには、「受信接続」で指定された IP アドレスまたはサービス タグをファイアウォールの許可リストに追加します。 ExpressRoute を使用する場合は、ファイアウォールの許可リストに ExpressRoute の IP 範囲も含めるようにしてください。

制限事項

  • 最高のパフォーマンスを実現するには、1 つのリポジトリに含めるパイプライン数を最大 50 個にすることをお勧めします。 許容できるパフォーマンスを実現するには、1 つのリポジトリに含めるパイプライン数を最大 100 個にすることをお勧めします。 リポジトリへのプッシュを処理するために必要な時間は、そのリポジトリ内のパイプラインの数に応じて増加します。 Azure Pipelines は、リポジトリへのプッシュがあるたびに、そのリポジトリ内のすべての YAML パイプラインを読み込んで、それらのいずれかを実行する必要があるかどうかを判断する必要があり、各パイプラインを読み込むとパフォーマンスが低下します。 パフォーマンスの問題に加えて、1 つのリポジトリにパイプラインが多すぎると、Azure Pipelines が短時間で多すぎる要求を行う可能性があるため、GitHub 側で調整が発生する可能性があります。
  • extend とinclude テンプレートを使用すると、Azure Pipelines が GitHub API リクエストを行う速度に影響し、GitHub 側での調整につながる可能性があります。 パイプラインを実行する前に、Azure Pipelines は完全な YAML コードを生成する必要があるため、すべてのテンプレート ファイルをフェッチする必要があります。
  • Azure Pipelines は、リポジトリから Azure DevOps ポータルのドロップダウン リストに最大 2,000 個のブランチを読み込みます。たとえば、[手動のビルドとスケジュールされたビルドの既定のブランチ] 設定に読み込んだり、パイプラインを手動で実行するときにブランチを選択したときです。 目的のブランチが一覧に表示されない場合は、目的のブランチ名を手動で入力してください。

よく寄せられる質問

GitHub Enterprise 統合に関連する問題は、次のカテゴリに分類されます。

  • トリガーの失敗: リポジトリに更新をプッシュしたときに、パイプラインがトリガーされません。
  • チェックアウトの失敗: パイプラインはトリガーされますが、チェックアウト手順で失敗します。
  • 間違ったバージョン: パイプラインは実行されますが、ソース/YAML の予期しないバージョンが使用されています。

トリガーの失敗

CI/PR トリガーを使用して新しい YAML パイプラインを作成しましたが、パイプラインはトリガーされていません。

次の各手順を実行して、失敗するトリガーをトラブルシューティングしてください。

  • YAML CI または PR トリガーは、UI のパイプライン設定によってオーバーライドされますか? パイプラインの編集時に、[...] を選択し、[トリガー] を選択します。

    Pipeline settings UI.

    リポジトリで使用できるトリガーの種類 ([継続的インテグレーション] または [pull request 検証]) に対する "ここから YAML トリガーをオーバーライドする" 設定を調べます。

    Override YAML trigger from here.

  • Webhook は、GitHub Enterprise から Azure Pipelines に更新について伝達するために使用されます。 GitHub Enterprise で、リポジトリの設定に移動し、[Webhook] に移動します。 Webhook があることを確認します。 通常は push と pull-request の 2 つの Webhook があるはずです。 ない場合は、サービス接続を再作成し、新しいサービス接続を使用するようにパイプラインを更新する必要があります。

  • GitHub Enterprise で各 Webhook を選択し、ユーザーのコミットに対応するペイロードが存在することと、それが Azure DevOps に正常に送信されたことを確認します。 イベントを Azure DevOps に伝達できなかった場合は、ここにエラーが表示される場合があります。

  • Azure Pipelines は GitHub から通知を受け取ると、GitHub へ通信し、リポジトリと YAML ファイルに関する詳細情報の取得を試みます。 GitHub Enterprise Server がファイアウォールの内側にあると、このトラフィックはサーバーに到達できないことがあります。 「Azure DevOps の IP アドレス」を参照して、すべての必要な IP アドレスに例外を認めていることを確認してください。 こうした IP アドレスは、最初に例外ルールを設定した後で変更されている可能性があります。

  • パイプラインが一時停止または無効化されていませんか? パイプライン用のエディターを開いて、[設定] を選択して確認してください。 パイプラインが一時停止または無効化されている場合、トリガーは機能しません。

  • 正しいブランチの YAML ファイルを更新しましたか? ブランチに更新をプッシュすると、そのブランチ内の YAML ファイルによって CI の動作が制御されます。 ソース ブランチに更新をプッシュすると、ソース ブランチとターゲット ブランチのマージによって生成される YAML ファイルによって PR の動作が制御されます。 正しいブランチの YAML ファイルに、必要な CI または PR 構成があることを確認します。

  • トリガーを正しく構成しましたか? YAML トリガーを定義する場合は、ブランチ、タグ、パスに対して include 句と exclude 句の両方を指定できます。 include 句がコミットの詳細と一致していることと、exclude 句がそれらを除外していないことを確認します。 トリガーの構文を確認し、正確であることを確認します。

  • トリガーまたはパスを定義するときに変数を使用しましたか? これはサポートされていません。

  • YAML ファイルにテンプレートを使用しましたか? その場合は、トリガーがメインの YAML ファイルで定義されていることを確認します。 テンプレート ファイル内で定義されたトリガーはサポートされていません。

  • 変更のプッシュ先のブランチまたはパスを除外しましたか? 変更を含まれているブランチに含まれているパスにプッシュしてテストします。 トリガーのパスは、大文字と小文字が区別される点に注意してください。 トリガーのパスを指定するときには、実際のフォルダーと同じ大文字と小文字を使用してください。

  • 新しいブランチをプッシュしましたか? その場合、新しいブランチで新しい実行が開始されない場合があります。 「新しいブランチが作成されたときのトリガーの動作」セクションを参照してください。

CI トリガーまたは PR トリガーは正常に動作していましたが、 今は動作していません。

まず、前の質問のトラブルシューティング手順を実行してから、以下の追加の手順を実行してください。

  • PR でマージ競合が発生していますか? パイプラインをトリガーしなかった PR の場合は、パイプラインを開き、マージの競合があるかどうかをチェックします。 マージ競合を解決してください。

  • プッシュ イベントまたは PR イベントの処理に遅延が発生していますか? 通常、遅延を検証するには、問題が 1 つのパイプラインに固有のものか、プロジェクト内のすべてのパイプラインまたはリポジトリに共通のものかを確認します。 いずれかのリポジトリへのプッシュまたは PR 更新でこの現象が発生している場合は、更新イベントの処理に遅延が発生している可能性があります。 遅延が発生する理由を次に示します。

    • 状態ページでサービスの停止が発生しています。 ステータス ページに問題が表示される場合は、Microsoft のチームが既に作業を開始しているはずです。 この問題に関する最新情報をこまめに確認してください。
    • リポジトリに含まれる YAML パイプラインが多すぎます。 最高のパフォーマンスを実現するには、1 つのリポジトリに含めるパイプライン数を最大 50 個にすることをお勧めします。 許容できるパフォーマンスを実現するには、1 つのリポジトリに含めるパイプライン数を最大 100 個にすることをお勧めします。 パイプライン数が多くなるほど、そのリポジトリへのプッシュ処理は遅くなります。 リポジトリへのプッシュがあるたびに、Azure Pipelines はそのリポジトリ内のすべての YAML パイプラインを読み込んで、実行する必要があるパイプラインがあるかどうかを判断する必要があり、新しいパイプラインごとにパフォーマンスのペナルティが発生します。
    • GitHub Enterprise Server インスタンスのプロビジョニングが不足し、Azure Pipelines からの要求の処理が遅くなる可能性があります。 GitHub Enterprise Server のハードウェアに関する考慮事項の詳細を参照してください。

チェックアウトの失敗

Microsoft ホステッド エージェントを使用していますか? その場合、これらのエージェントは GitHub Enterprise Server に到達できない可能性があります。 詳細については、「Microsoft ホステッド エージェントから到達不可」を参照してください。

バージョンが正しくない

パイプラインで間違ったバージョンの YAML ファイルが使用されています。 なぜでしょうか。

  • CI トリガーの場合、プッシュするブランチにある YAML ファイルが評価され、CI ビルドを実行する必要があるかどうかが確認されます。
  • PR トリガーの場合、PR のソース ブランチとターゲット ブランチをマージした結果の YAML ファイルが評価され、PR ビルドを実行する必要があるかどうかが確認されます。