GitHub リポジトリを作成する

Azure DevOps Services

Azure Pipelines では、すべての pull request を自動的にビルドして検証し、GitHub リポジトリに対してコミットできます。 この記事では、GitHub と Azure Pipelines の統合を構成する方法について説明します。

GitHub とのパイプライン統合を初めて使用する場合は、「最初のパイプラインを作成する」の手順に従ってください。 GitHub と Azure Pipelines の統合の構成とカスタマイズについて詳しく学習するには、この記事に戻ってください。

組織とユーザー

GitHub と Azure Pipelines は、適切に統合される 2 つの独立したサービスです。 それぞれが独自の方法で組織とユーザーを管理します。 このセクションでは、GitHub から Azure Pipelines に組織とユーザーをレプリケートする方法についての推奨事項を示します。

組織

GitHub の構造は、リポジトリを含む組織とユーザー アカウントで構成されています。 GitHub のドキュメントを参照してください。

GitHub の組織の構造

Azure DevOps の構造は、プロジェクトを含む組織で構成されています。 「組織の構造を計画する」を参照してください。

Azure DevOps の組織の構造

Azure DevOps では、次のように GitHub の構造を反映できます。

  • GitHub の組織またはユーザー アカウントに対して DevOps の組織
  • GitHub のリポジトリに対して DevOps のプロジェクト

Azure DevOps にマップされた GitHub 構造

Azure DevOps で同じ構造を設定するには:

  1. GitHub の組織またはユーザー アカウントにちなんだ名前の DevOps の組織を作成します。 その URL は https://dev.azure.com/your-organization のようになります。
  2. DevOps の組織で、リポジトリにちなんだ名前のプロジェクトを作成します。 その URL は https://dev.azure.com/your-organization/your-repository のようになります。
  3. DevOps のプロジェクトで、GitHub の組織とそれが構築するリポジトリにちなんだ名前のパイプラインを作成します (your-organization.your-repository など)。 こうすると、その対象となるリポジトリが明らかになります。

このパターンに従うと、GitHub のリポジトリと Azure DevOps のプロジェクトの URL パスが一致します。 次に例を示します。

サービス URL
GitHub https://github.com/python/cpython
Azure DevOps https://dev.azure.com/python/cpython

ユーザー

GitHub ユーザーに Azure Pipelines へのアクセス権が自動的に付与されることはありません。 Azure Pipelines では GitHub ID が認識されません。 このため、GitHub ID とメール アドレスを使ってビルドの失敗や PR 検証の失敗をユーザーに自動的に通知するように Azure Pipelines を構成する方法はありません。 Azure Pipelines で新しいユーザーを明示的に作成し、GitHub ユーザーをレプリケートする必要があります。 新しいユーザーを作成したら、Azure DevOps でそのアクセス許可を構成し、GitHub でのアクセス許可を反映させることができます。 DevOps でユーザーの DevOps ID を使って通知を構成することもできます。

GitHub 組織のロール

GitHub 組織のメンバー ロールは、https://github.com/orgs/your-organization/people で確認できます (your-organization を置き換えてください)。

DevOps 組織のメンバーのアクセス許可は、https://dev.azure.com/your-organization/_settings/security で確認できます (your-organization を置き換えてください)。

GitHub 組織のロールと、Azure DevOps 組織の対応するロールを次に示します。

GitHub 組織のロール DevOps 組織の対応するロール
所有者 Project Collection Administrators のメンバー
支払いマネージャー Project Collection Administrators のメンバー
メンバー Project Collection Valid Users のメンバー。 既定では、メンバー グループには新しいプロジェクトを作成するためのアクセス許可がありません。 アクセス許可を変更するには、グループの Create new projects アクセス許可を Allow に設定するか、必要なアクセス許可を持つ新しいグループを作成します。

GitHub ユーザー アカウントのロール

GitHub ユーザー アカウントは、1 つのロールを持ちます。そのアカウントの所有権です。

DevOps 組織のメンバーのアクセス許可は、https://dev.azure.com/your-organization/_settings/security で確認できます (your-organization を置き換えてください)。

GitHub ユーザー アカウントのロールは、次のように DevOps 組織のアクセス許可にマップされます。

GitHub ユーザー アカウントのロール DevOps 組織の対応するロール
所有者 Project Collection Administrators のメンバー

GitHub リポジトリのアクセス許可

GitHub リポジトリのアクセス許可は、https://github.com/your-organization/your-repository/settings/collaboration で確認できます (your-organizationyour-repository を置き換えてください)。

DevOps プロジェクトのアクセス許可は、https://dev.azure.com/your-organization/your-project/_settings/security で確認できます (your-organizationyour-project を置き換えてください)。

GitHub リポジトリと Azure DevOps プロジェクト間で対応するアクセス許可は次のとおりです。

GitHub リポジトリのアクセス許可 DevOps プロジェクトの対応するアクセス許可
[Admin] Project Administrators のメンバー
Write Contributors のメンバー
Read Readers のメンバー

GitHub リポジトリがチームにアクセス許可を付与している場合は、Azure DevOps プロジェクト設定の Teams セクションで対応するチームを作成できます。 その後、ユーザーと同様に、上記のセキュリティ グループにそのチームを追加します。

パイプライン固有のアクセス許可

DevOps プロジェクト内の特定のパイプラインに対するアクセス許可をユーザーまたはチームに付与するには、次の手順に従います。

  1. プロジェクトの [パイプライン] ページにアクセスします (例: https://dev.azure.com/your-organization/your-project/_build)。
  2. 特定のアクセス許可を設定するパイプラインを選択します。
  3. [...] コンテキスト メニューで、[セキュリティ] を選択します。
  4. [追加...] を選択して、特定のユーザー、チーム、またはグループを追加し、パイプラインへのアクセス許可をカスタマイズします。

GitHub リポジトリへのアクセス

最初に GitHub リポジトリを選択し、そのリポジトリ内の YAML ファイルを選択して、新しいパイプラインを作成します。 YAML ファイルが存在するリポジトリは、self リポジトリと呼ばれます。 既定では、これはパイプラインによってビルドされるリポジトリです。

後で、別のリポジトリまたは複数のリポジトリをチェックアウトするようにパイプラインを構成できます。 これを行う方法については、複数のリポジトリのチェックアウトに関する記事を参照してください。

ビルドをトリガーし、ビルド中にコードをフェッチするには、Azure Pipelines にリポジトリへのアクセス権を付与する必要があります。

パイプラインの作成時に、GitHub リポジトリへの Azure Pipelines アクセス権を付与するための認証の種類は 3 つあります。

認証の種類 パイプライン実行で使われるもの GitHub Checks との連携
1. GitHub App Azure Pipelines ID はい
2. OAuth 個人用 GitHub ID いいえ
3. 個人用アクセス トークン (PAT) 個人用 GitHub ID いいえ

GitHub アプリ認証

Azure Pipelines の GitHub App は、継続的インテグレーション パイプラインに推奨される認証の種類です。 GitHub アカウントまたは組織に GitHub App をインストールすると、個人用 GitHub ID を使わずにパイプラインが実行されます。 ビルドと GitHub の状態の更新は、Azure Pipelines ID を使って実行されます。 アプリは GitHub Checks と連携して、GitHub でビルド、テスト、コード カバレッジの結果を表示します。

GitHub App を使うには、一部またはすべてのリポジトリに対して GitHub の組織またはユーザー アカウントにインストールします。 GitHub App は、アプリのホームページからインストールおよびアンインストールできます。

インストール後、GitHub App は、リポジトリのパイプラインが作成されるときの GitHub に対する Azure Pipelines の既定の認証方法 (OAuth ではなく) になります。

GitHub 組織内のすべてのリポジトリに対して GitHub App をインストールする場合、Azure Pipelines によって大量のメールが送信されたり、ユーザーに代わってパイプラインが自動的に設定されたりすることを心配する必要はありません。 リポジトリ管理者は、すべてのリポジトリに対してアプリをインストールする代わりに、個々のリポジトリに対して一度に 1 つずつインストールできます。 この場合、管理者の作業は増えますが、長所も短所もありません。

GitHub で必要なアクセス許可

Azure Pipelines の GitHub アプリをインストールするには、GitHub 組織の所有者またはリポジトリ管理者である必要があります。さらに、継続的インテグレーションと pull request トリガーを使って GitHub リポジトリのパイプラインを作成するには、必要な GitHub アクセス許可が構成されている必要があります。 そうでない場合は、パイプラインの作成時にリポジトリの一覧にリポジトリが表示されません。 認証の種類とリポジトリの所有権に応じて、適切なアクセス権が構成されていることを確認してください。

  • リポジトリが個人用 GitHub アカウントにある場合は、個人用 GitHub アカウントに Azure Pipelines の GitHub App をインストールします。これで Azure Pipelines でパイプラインを作成するときにこのリポジトリを表示できます。

  • リポジトリが別のユーザーの個人用 GitHub アカウントにある場合は、その別のユーザーが自分の個人用 GitHub アカウントに Azure Pipelines の GitHub App をインストールする必要があります。 ご自身は、リポジトリの設定の [コラボレーター] でコラボレーターとして追加される必要があります。 メールで送信されてきたリンクを使って、コラボレーターになる招待を承諾します。 完了したら、そのリポジトリのパイプラインを作成できます。

  • リポジトリが自分の所有する GitHub 組織にある場合は、GitHub 組織に Azure Pipelines の GitHub App をインストールします。 また、リポジトリの設定の [コラボレーターとチーム] で、ご自身がコラボレーターとして追加されるか、ご自身のチームが追加される必要もあります。

  • リポジトリが他のユーザーが所有する GitHub 組織にある場合、GitHub 組織の所有者またはリポジトリ管理者が、組織に Azure Pipelines の GitHub App をインストールする必要があります。 リポジトリの設定の [コラボレーターとチーム] で、ご自身がコラボレーターとして追加されるか、ご自身のチームが追加される必要があります。 メールで送信されてきたリンクを使って、コラボレーターになる招待を承諾します。

GitHub アプリのアクセス許可

GitHub App は、インストール中に次のアクセス許可を要求します。

アクセス許可 Azure Pipelines でアクセス許可が使用される方法
コードへの書き込みアクセス権 意図的なアクションを実行するときのみ、Azure Pipelines によって、GitHub リポジトリの選択したブランチに YAML ファイルをコミットすることで、パイプラインの作成が簡素化されます。
メタデータへの読み取りアクセス権 Azure Pipelines は、ビルドの概要でビルドに関連付けられているリポジトリ、ブランチ、イシューを表示するために、GitHub メタデータを取得します。
チェックへの読み取りおよび書き込みアクセス権 Azure Pipelines は、GitHub に表示される独自のビルド、テスト、コード カバレッジの結果の読み取りと書き込みを行います。
pull request への読み取りおよび書き込みアクセス権 意図的なアクションを実行するときのみ、Azure Pipelines によって、GitHub リポジトリの選択したブランチにコミットされた YAML ファイルの pull request を作成することで、パイプラインの作成が簡素化されます。 Pipelines は、pull request に関連付けられているビルドの概要に表示する要求メタデータを取得します。

GitHub App のインストールのトラブルシューティング

GitHub に次のようなエラーが表示される場合があります。

You do not have permission to modify this app on your-organization. Please contact an Organization Owner.

これは、GitHub App が組織に既にインストールされている可能性があることを意味します。 その組織でリポジトリのパイプラインを作成すると、GitHub への接続に GitHub App が自動的に使用されます。

Azure DevOps の複数の組織とプロジェクトでパイプラインを作成する

GitHub App がインストールされたら、さまざまな Azure DevOps の組織およびプロジェクトで組織のリポジトリのパイプラインを作成できます。 ただし、Azure DevOps の複数の組織で 1 つのリポジトリのパイプラインを作成する場合、GitHub のコミットまたは pull request によって自動的にトリガーできるのは、最初の組織のパイプラインのみです。 セカンダリの Azure DevOps 組織では、引き続き手動またはスケジュールされたビルドを実行できます。

OAuth 認証

OAuth は、個人用 GitHub アカウントのリポジトリで使用を開始するための最もシンプルな認証の種類です。 GitHub の状態の更新が、個人用 GitHub ID に代わって実行されます。 パイプラインが機能し続けるためには、リポジトリへのアクセスがアクティブなままである必要があります。 Checks などの一部の GitHub 機能は OAuth では使用できず、GitHub App が必要になります。

OAuth を使うには、パイプラインの作成時にリポジトリの一覧の下にある [別の接続を選択する] を選択します。 次に、[承認] を選択して GitHub にサインインし、OAuth で承認します。 OAuth 接続は、後で使用するために Azure DevOps プロジェクトに保存され、作成されるパイプラインで使用されます。

GitHub で必要なアクセス許可

継続的インテグレーションと pull request トリガーを使って GitHub リポジトリのパイプラインを作成するには、必要な GitHub アクセス許可が構成されている必要があります。 そうでない場合は、パイプラインの作成時にリポジトリの一覧にリポジトリが表示されません。 認証の種類とリポジトリの所有権に応じて、適切なアクセス権が構成されていることを確認してください。

  • リポジトリが個人用 GitHub アカウントにある場合は、少なくとも 1 回は、個人用 GitHub アカウントの資格情報を使って OAuth で GitHub に対して認証を行います。 これは、Azure DevOps プロジェクト設定の [パイプライン] > [サービス接続] > [新しいサービス接続] > [GitHub] > [承認] で行うことができます。 こちらの [アクセス許可] で、リポジトリへのアクセス権を Azure Pipelines に付与します。

  • リポジトリが別のユーザーの個人用 GitHub アカウントにある場合は、少なくとも 1 回は、その別のユーザーが自分の個人用 GitHub アカウントの資格情報を使って OAuth で GitHub に対して認証を行う必要があります。 これは、Azure DevOps プロジェクト設定の [パイプライン] > [サービス接続] > [新しいサービス接続] > [GitHub] > [承認] で行うことができます。 その別のユーザーは、こちらの [アクセス許可] で自分のリポジトリへのアクセス権を Azure Pipelines に付与する必要があります。 ご自身は、リポジトリの設定の [コラボレーター] でコラボレーターとして追加される必要があります。 メールで送信されてきたリンクを使って、コラボレーターになる招待を承諾します。

  • リポジトリが自分の所有する GitHub 組織にある場合は、少なくとも 1 回は、個人用 GitHub アカウントの資格情報を使って OAuth で GitHub に対して認証を行います。 これは、Azure DevOps プロジェクト設定の [パイプライン] > [サービス接続] > [新しいサービス接続] > [GitHub] > [承認] で行うことができます。 こちらの [組織のアクセス] で、組織へのアクセス権を Azure Pipelines に付与します。 リポジトリの設定の [コラボレーターとチーム] で、ご自身がコラボレーターとして追加されるか、ご自身のチームが追加される必要があります。

  • リポジトリが別のユーザーが所有する GitHub 組織にある場合は、少なくとも 1 回は、GitHub 組織の所有者が自分の個人用 GitHub アカウントの資格情報を使って OAuth で GitHub に対して認証を行う必要があります。 これは、Azure DevOps プロジェクト設定の [パイプライン] > [サービス接続] > [新しいサービス接続] > [GitHub] > [承認] で行うことができます。 組織の所有者は、こちらの [組織のアクセス] で、組織へのアクセス権を Azure Pipelines に付与する必要があります。 リポジトリの設定の [コラボレーターとチーム] で、ご自身がコラボレーターとして追加されるか、ご自身のチームが追加される必要があります。 メールで送信されてきたリンクを使って、コラボレーターになる招待を承諾します。

OAuth アクセスを取り消す

Azure Pipelines による OAuth の使用を承認した後、それを取り消し、それ以上使用できないようにするには、GitHub 設定の [OAuth アプリ] にアクセスします。 また、Azure DevOps プロジェクト設定の GitHub サービス接続の一覧から削除することもできます。

個人用アクセス トークン (PAT) 認証

PAT は実質的に OAuth と同じですが、Azure Pipelines に付与されるアクセス許可を制御できます。 ビルドと GitHub の状態の更新が、個人用 GitHub ID に代わって実行されます。 ビルドが機能し続けるためには、リポジトリへのアクセスがアクティブなままである必要があります。

PAT を作成するには、GitHub 設定の [個人用アクセス トークン] にアクセスします。 必須のアクセス許可は repoadmin:repo_hookread:useruser:email です。 これらは、上記の OAuth を使用するときに必要なものと同じアクセス許可です。 生成された PAT をクリップボードにコピーし、Azure DevOps プロジェクト設定の新しい GitHub サービス接続に貼り付けます。 後で思い出しやすいように、GitHub ユーザー名にちなんだ名前をサービス接続に付けます。 これは、後でパイプラインを作成するときに Azure DevOps プロジェクトで使用できるようになります。

GitHub で必要なアクセス許可

継続的インテグレーションと pull request トリガーを使って GitHub リポジトリのパイプラインを作成するには、必要な GitHub アクセス許可が構成されている必要があります。 そうでない場合は、パイプラインの作成時にリポジトリの一覧にリポジトリが表示されません。 認証の種類とリポジトリの所有権に応じて、次のアクセス権が構成されていることを確認してください。

  • リポジトリが個人用 GitHub アカウントにある場合、PAT には、[個人用アクセス トークン] で必要なアクセス スコープが必要です (repoadmin:repo_hookread:useruser:email)。

  • リポジトリが別のユーザーの個人用 GitHub アカウントにある場合、PAT には、[個人用アクセス トークン] で必要なアクセス スコープが必要です (repoadmin:repo_hookread:useruser:email)。 ご自身は、リポジトリの設定の [コラボレーター] でコラボレーターとして追加される必要があります。 メールで送信されてきたリンクを使って、コラボレーターになる招待を承諾します。

  • リポジトリが自分の所有する GitHub 組織にある場合、PAT には、[個人用アクセス トークン] で必要なアクセス スコープが必要です (repoadmin:repo_hookread:useruser:email)。 リポジトリの設定の [コラボレーターとチーム] で、ご自身がコラボレーターとして追加されるか、ご自身のチームが追加される必要があります。

  • リポジトリが別のユーザーが所有する GitHub 組織にある場合、PAT には、[個人用アクセス トークン] で必要なアクセス スコープが必要です (repoadmin:repo_hookread:useruser:email)。 リポジトリの設定の [コラボレーターとチーム] で、ご自身がコラボレーターとして追加されるか、ご自身のチームが追加される必要があります。 メールで送信されてきたリンクを使って、コラボレーターになる招待を承諾します。

PAT アクセスを取り消す

Azure Pipelines による PAT の使用を承認した後、それを削除し、それ以上使用できないようにするには、GitHub 設定の [個人用アクセス トークン] にアクセスします。 また、Azure DevOps プロジェクト設定の GitHub サービス接続の一覧から削除することもできます。

CI トリガー

継続的インテグレーション (CI) トリガーを使用すると、指定したブランチに更新をプッシュするか、指定したタグをプッシュするたびにパイプラインが実行されます。

YAML パイプラインは、Azure DevOps スプリント 227 で導入された [暗黙的な YAML CI トリガー設定を無効化する] 設定が有効になっていない限り、すべてのブランチで CI トリガーを使用して既定で構成されます。 [暗黙的な YAML CI トリガーの無効化] 設定は、組織レベルまたはプロジェクト レベルで構成できます。 [暗黙的な YAML CI トリガーの無効化] 設定が有効になっているときに、YAML パイプラインに trigger セクションがない場合、YAML パイプラインの CI トリガーは有効になりません。 既定では、[暗黙的な YAML CI トリガーの無効化] は有効になっていません。

ブランチ

簡単な構文を使用して、CI トリガーを取得するブランチを制御できます。

trigger:
- main
- releases/*

ブランチの完全な名前 (例: main) またはワイルドカード (例: releases/*) を指定できます。 ワイルドカード構文の詳細については、「ワイルドカード」を参照してください。

注意

変数は実行時 (トリガーの起動後) に評価されるため、トリガーで変数を使用することはできません。

注意

テンプレートを使用して YAML ファイルを作成する場合は、パイプラインのメイン YAML ファイルでのみトリガーを指定できます。 テンプレート ファイルにトリガーを指定することはできません。

exclude または batch を使用する複雑なトリガーの場合は、次の例に示すように完全な構文を使用する必要があります。

# specific branch build
trigger:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

上記の例では、変更が main またはリリース ブランチにプッシュされると、パイプラインがトリガーされます。 ただし、old で始まるリリース ブランチに変更が加えられた場合はトリガーされません。

include 句を指定せずに exclude 句を指定すると、include 句に * を指定した場合と同じになります。

branches 一覧でブランチ名を指定するだけでなく、次の形式を使用してタグに基づいてトリガーを構成することもできます。

trigger:
  branches:
    include:
      - refs/tags/{tagname}
    exclude:
      - refs/tags/{othertagname}

トリガーを指定せず、[暗黙的な YAML CI トリガーを無効にする] 設定が有効になっていない場合、既定値は次のように記述します。

trigger:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

重要

トリガーを指定すると、既定の暗黙的なトリガーが置き換えられ、含まれるように明示的に構成されたブランチへのプッシュのみがパイプラインをトリガーします。 インクルードは最初に処理され、次に除外がリストから削除されます。

CI 実行のバッチ処理

多くのチーム メンバーが頻繁に変更をアップロードしている場合は、開始する実行の数を減らすことができます。 パイプラインの実行中に batchtrue に設定すると、システムは実行が完了するまで待機し、まだビルドされていないすべての変更で別の実行を開始します。

# specific branch build with batching
trigger:
  batch: true
  branches:
    include:
    - main

注意

batch は、リポジトリ リソース トリガーではサポートされていません。

この例を明確にするために、Amain にプッシュした場合に、上記のパイプラインが実行されたとします。 そのパイプラインの実行中に、追加のプッシュ BC がリポジトリに送信されます。 これらの更新では、独立した新しい実行はすぐに開始されません。 ただし、最初の実行が完了すると、その時点までのすべてのプッシュがバッチ処理され、新しい実行が開始されます。

注意

パイプラインに複数のジョブとステージがある場合でも、2 回目の実行を開始する前にすべてのジョブとステージを完了またはスキップして、最初の実行が終了状態に達する必要があります。 このため、複数のステージまたは承認を含むパイプラインでこの機能を使用する場合は注意が必要です。 このような場合にビルドをバッチ処理する場合は、CI/CD プロセスを 2 つのパイプライン (ビルド用 (バッチ処理あり) とデプロイ用) に分割することをお勧めします。

パス

含めるか除外するファイル パスを指定できます。

# specific path build
trigger:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

パスを指定する場合は、Azure DevOps Server 2019.1 以降を使用している場合にトリガーするブランチを明示的に指定する必要があります。 パス フィルターのみでパイプラインをトリガーすることはできません。ブランチ フィルターも必要です。また、パス フィルターに一致する変更されたファイルは、ブランチ フィルターに一致するブランチからのものである必要があります。 Azure DevOps Server 2020 以降を使用している場合は、branches を省略して、パス フィルターと組み合わせて、すべてのブランチをフィルター処理できます。

ワイルドカードは、パス フィルターでサポートされています。 たとえば、src/app/**/myapp* に一致するすべてのパスを含めることができます。 パス フィルターを指定する場合は、ワイルドカード文字 (***、または ?)) を使用できます。

  • パスは、常にリポジトリのルートを基準にして指定されます。
  • パス フィルターを設定しない場合、リポジトリのルート フォルダーは既定で暗黙的に含まれます。
  • パスを除外した場合は、より深いフォルダーを指すよう修飾しない限り、それを含めることはできません。 たとえば、/tools を除外した場合、/tools/trigger-runs-on-these を含めることはできます
  • パス フィルターの順序は関係ありません。
  • Git のパスでは、"大文字と小文字が区別されます"。 実際のフォルダーと同じ大文字と小文字の区別を使用してください。
  • 変数は実行時 (トリガーの起動後) に評価されるため、パスで変数を使用することはできません。

Tags

前のセクションで説明したように、branches リストでタグを指定するだけでなく、含めるタグまたは除外するタグを直接指定できます。

# specific tag
trigger:
  tags:
    include:
    - v2.*
    exclude:
    - v2.0

タグ トリガーを指定しない場合、既定では、タグはパイプラインをトリガーしません。

重要

ブランチ フィルターと組み合わせてタグを指定すると、ブランチ フィルターが満たされているか、タグ フィルターが満たされている場合にトリガーが起動します。 たとえば、プッシュされたタグがブランチ フィルターを満たす場合、プッシュがブランチ フィルターを満たしていたため、タグがタグ フィルターによって除外された場合でもパイプラインがトリガーされます。

CI のオプトアウト

CI トリガーの無効化

trigger: none を指定すると、CI トリガーを完全にオプトアウトできます。

# A pipeline with no CI trigger
trigger: none

重要

ブランチに変更をプッシュすると、そのブランチ内の YAML ファイルが評価され、CI 実行を開始する必要があるかどうかを判断します。

個々のコミットの CI のスキップ

また、プッシュが通常トリガーするパイプラインの実行をスキップするように Azure Pipelines に指示することもできます。 Azure Pipelines では、プッシュの一部であるコミットのメッセージまたは説明に [skip ci] を含めるだけで、このプッシュの実行 CI をスキップします。 次のバリエーションのいずれかを使用することもできます。

  • [skip ci] または [ci skip]
  • skip-checks: true または skip-checks:true
  • [skip azurepipelines] または [azurepipelines skip]
  • [skip azpipelines] または [azpipelines skip]
  • [skip azp] または [azp skip]
  • ***NO_CI***

条件でトリガーの種類を使用する

実行を開始したトリガーの種類に応じて、パイプラインでさまざまなステップ、ジョブ、またはステージを実行するのが一般的なシナリオです。 これを行うには、システム変数 Build.Reason を使用します。 たとえば、次の条件をステップ、ジョブ、またはステージに追加して、PR 検証から除外します。

condition: and(succeeded(), ne(variables['Build.Reason'], 'PullRequest'))

新しいブランチが作成されたときのトリガーの動作

同じリポジトリに対して複数のパイプラインを構成するのが一般的です。 たとえば、アプリのドキュメントをビルドするためのパイプラインと、ソース コードをビルドするためのパイプラインがあるとします。 これらの各パイプラインで、適切なブランチ フィルターとパス フィルターを使用して CI トリガーを構成できます。 たとえば、docs フォルダーに更新をプッシュするときに 1 つのパイプラインをトリガーし、アプリケーション コードに更新をプッシュするときにもう 1 つのパイプラインをトリガーするとします。 このような場合は、新しいブランチが作成されたときにパイプラインがどのようにトリガーされるかを理解する必要があります。

新しいブランチ (ブランチ フィルターに一致する) をリポジトリにプッシュするときの動作を次に示します。

  • パイプラインにパス フィルターがある場合は、新しいブランチがそのパス フィルターに一致するファイルに変更を加えた場合にのみトリガーされます。
  • パイプラインにパス フィルターがない場合は、新しいブランチに変更がない場合でもトリガーされます。

ワイルドカード

ブランチ、タグ、またはパスを指定する場合は、正確な名前またはワイルドカードを使用できます。 ワイルドカード パターンでは、* が 0 個以上の文字と一致し、? が 1 つの文字と一致するようにできます。

  • YAML パイプラインでパターンを * で開始する場合は、"*-releases" のようにパターンを引用符で囲む必要があります。
  • ブランチとタグの場合:
    • ワイルドカードは、パターン内の任意の場所に表示できます。
  • パスの場合:
    • Azure DevOps Services を含む Azure DevOps Server 2022 以降では、パス パターン内の任意の場所にワイルドカードが表示され、* または ? を使用できます。
    • Azure DevOps Server 2020 以前では、最後の文字として * を含めることができますが、ディレクトリ名を単独で指定する場合と何も変わりません。 パス フィルターの途中に * を含めることはできず? を使用することはできません。
trigger:
  branches:
    include:
    - main
    - releases/*
    - feature/*
    exclude:
    - releases/old*
    - feature/*-working
  paths:
    include:
    - docs/*.md

PR トリガー

また、pull request が指定されたターゲット ブランチのいずれかで開かれるとき、またはそのような pull request に対して更新が行われるたびにパイプラインが実行されるように pull request (PR) トリガーを構成することもできます。

ブランチ

pull request を検証するときにターゲット ブランチを指定できます。 たとえば、mainreleases/* をターゲットとする pull request を検証するには、次の pr トリガーを使用できます。

pr:
- main
- releases/*

この構成により、新しい pull request が初めて作成されたときと、その pull request に対して更新が行われるたびに、新しい実行が開始されます。

ブランチの完全な名前 (例: main) またはワイルドカード (例: releases/*) を指定できます。

注意

変数は実行時 (トリガーの起動後) に評価されるため、トリガーで変数を使用することはできません。

注意

テンプレートを使用して YAML ファイルを作成する場合は、パイプラインのメイン YAML ファイルでのみトリガーを指定できます。 テンプレート ファイルにトリガーを指定することはできません。

GitHub では、pull request の作成時に新しい ref が作成されます。 ref は "マージ コミット" を指します。これは、pull request のソース ブランチとターゲット ブランチの間でマージされたコードです。 PR 検証パイプラインは、この ref が指すコミットをビルドします。 つまり、パイプラインの実行に使用される YAML ファイルは、ソース ブランチとターゲット ブランチの間のマージでもあります。 その結果、pull request のソース ブランチの YAML ファイルに加えた変更は、ターゲット ブランチの YAML ファイルによって定義された動作をオーバーライドできます。

YAML ファイルに pr トリガーが含まれていない場合は、次のような pr トリガーを記述したかのように、すべてのブランチに対して pull request 検証が自動的に有効になります。 この構成により、任意の pull request が作成されたときと、任意のアクティブな pull request のソース ブランチにコミットが送信されたときに、ビルドがトリガーされます。

pr:
  branches:
    include:
    - '*'  # must quote since "*" is a YAML reserved character; we want a string

重要

ブランチのサブセットで pr トリガーを指定すると、それらのブランチに更新がプッシュされたときにのみパイプラインがトリガーされます。

特定のブランチを除外する必要があるより複雑なトリガーの場合は、次の例に示すように完全な構文を使う必要があります。 この例では、main または releases/* をターゲットとする pull request が検証され、ブランチ releases/old* は除外されます。

# specific branch
pr:
  branches:
    include:
    - main
    - releases/*
    exclude:
    - releases/old*

パス

含めるか除外するファイル パスを指定できます。 次に例を示します。

# specific path
pr:
  branches:
    include:
    - main
    - releases/*
  paths:
    include:
    - docs
    exclude:
    - docs/README.md

ヒント:

  • Azure Pipelines は、パスの除外ルールのために検証ビルドを実行しないと判断したときに、中立の状態を GitHub にポストバックします。 これにより、Azure Pipelines の処理が完了したことを示す明確な指示が GitHub に提供されます。 詳しくは、「ビルドがスキップされたときに中立の状態を GitHub にポストする」を参照してください。
  • ワイルドカードがパス フィルターでサポートされるようになりました
  • パスは、常にリポジトリのルートを基準にして指定されます。
  • パス フィルターを設定しない場合、リポジトリのルート フォルダーは既定で暗黙的に含まれます。
  • パスを除外した場合は、より深いフォルダーを指すよう修飾しない限り、それを含めることはできません。 たとえば、/tools を除外した場合、/tools/trigger-runs-on-these を含めることはできます
  • パス フィルターの順序は関係ありません。
  • Git のパスでは、"大文字と小文字が区別されます"。 実際のフォルダーと同じ大文字と小文字の区別を使用してください。
  • 変数は実行時 (トリガーの起動後) に評価されるため、パスで変数を使用することはできません。
  • Azure Pipelines は、パスの除外ルールのために検証ビルドを実行しないと判断したときに、中立の状態を GitHub にポストバックします。

複数の PR 更新

PR に対する追加の更新によって、同じ PR に対する進行中の検証の実行を取り消すかどうかを指定できます。 既定値は、true です。

# auto cancel false
pr:
  autoCancel: false
  branches:
    include:
    - main

ドラフト PR の検証

既定では、pull request トリガーは、ドラフトの pull request とレビューの準備ができている pull request に対して起動します。 ドラフトの pull request に対する pull request トリガーを無効にするには、drafts プロパティを false に設定します。

pr:
  autoCancel: boolean # indicates whether additional pushes to a PR should cancel in-progress runs for the same PR. Defaults to true
  branches:
    include: [ string ] # branch names which will trigger a build
    exclude: [ string ] # branch names which will not
  paths:
    include: [ string ] # file paths which must match to trigger a build
    exclude: [ string ] # file paths which will not trigger a build
  drafts: boolean # whether to build draft PRs, defaults to true

PR 検証のオプトアウト

pr: none を指定することで、pull request の検証を完全にオプトアウトできます。

# no PR triggers
pr: none

詳しくは、YAML スキーマPR トリガーに関する記事を参照してください。

注意

pr トリガーが起動しない場合は、FAQ のトラブルシューティング手順に従ってください。

開いている PR があり、そのソース ブランチに変更をプッシュすると、複数のパイプラインが実行される可能性があります。

  • PR のターゲット ブランチに対して PR トリガーを持つパイプラインは、"マージ コミット" (pull request のソース ブランチとターゲット ブランチ間でマージされたコード) で実行されます。メッセージまたは説明に [skip ci] (またはそのバリアントのいずれか) が含まれるプッシュされたコミットが存在するかどうかは関係ありません。
  • メッセージまたは説明に [skip ci] (またはそのバリアントのいずれか) が含まれるプッシュされたコミットがない場合、PR のソース ブランチへの変更によってパイプラインがトリガーされます。 少なくとも 1 つのプッシュされたコミットに [skip ci] が含まれる場合、パイプラインは実行されません。

最後に、PR をマージした後、マージ コミットのメッセージまたは説明に [skip ci] (またはそのバリアントのいずれか) が含まれていない場合、Azure Pipelines により、ターゲット ブランチへのプッシュによってトリガーされる CI パイプラインが実行されます。

保護されたブランチ

ブランチをターゲットとするコミットまたは pull request ごとに検証ビルドを実行し、検証ビルドが成功するまで pull request がマージされないようにすることもできます。

GitHub リポジトリに対して必須の検証ビルドを構成するには、その所有者であるか、管理ロールを持つコラボレーター、または書き込みロールを持つ GitHub 組織のメンバーである必要があります。

  1. まず、リポジトリのパイプラインを作成し、少なくとも 1 回はビルドして、その状態が GitHub にポストされるようにします。これにより、そのパイプラインの名前を GitHub に認識させます。

  2. 次に、リポジトリの設定で保護されたブランチを構成するための GitHub のドキュメントに従います。

    状態の確認では、[状態の確認] の一覧からパイプラインの名前を選択します。

    GitHub パイプラインの状態の確認

重要

パイプラインがこの一覧に表示されない場合は、次のことを確認してください。

  • GitHub アプリ認証を使用している
  • パイプラインが過去 1 週間以内に少なくとも 1 回実行されている

外部ソースからのコントリビューション

GitHub リポジトリがオープンソースである場合は、Azure DevOps プロジェクトをパブリックにすることで、誰もがパイプラインのビルド結果、ログ、テスト結果をサインインせずに表示できるようにすることができます。 組織外のユーザーがリポジトリをフォークして pull request を送信した場合、それらの pull request が自動的に検証されるビルドの状態を表示できます。

パブリック プロジェクトで Azure Pipelines を使用し、外部ソースからのコントリビューションを受け入れる場合は、次の考慮事項に留意する必要があります。

アクセスの制限

Azure DevOps パブリック プロジェクトでパイプラインを実行する場合は、次のアクセス制限に注意してください。

  • シークレット: 既定では、パイプラインに関連付けられているシークレットは、フォークの pull request 検証では使用できません。 フォークからのコントリビューションの検証に関するセクションを参照してください。
  • プロジェクト間アクセス: Azure DevOps パブリック プロジェクト内のすべてのパイプラインは、そのプロジェクトに制限されたアクセス トークンで実行されます。 パブリック プロジェクト内のパイプラインは、そのプロジェクト内のビルド成果物やテスト結果などのリソースにのみアクセスでき、Azure DevOps 組織の他のプロジェクト内のリソースにはアクセスできません。
  • Azure Artifacts パッケージ: パイプラインで Azure Artifacts からパッケージにアクセスする必要がある場合は、パッケージ フィードにアクセスするためのアクセス許可をプロジェクト ビルド サービス アカウントに明示的に付与する必要があります。

フォークからのコントリビューション

重要

これらの設定は、パイプラインのセキュリティに影響します。

パイプラインを作成した場合、リポジトリのフォークからの pull request に対して自動的にトリガーされます。 この動作は変更できますが、セキュリティに与える影響を慎重に考慮してください。 この動作を有効または無効にするには:

  1. Azure DevOps プロジェクトに移動します。 [パイプライン] を選択し、使用するパイプラインを見つけて、[編集] を選択します。
  2. [トリガー] タブを選択します。[Pull request のトリガー] を有効にした後、[このリポジトリのフォークから pull requests をビルドする] チェック ボックスをオンまたはオフにします。

GitHub リポジトリでは、既定で、ビルド パイプラインに関連付けられているシークレットはフォークの pull request ビルドでは使用できません。 これらのシークレットは、GitHub Enterprise Server パイプラインでは既定で有効になっています。 シークレットには次のものが含まれます:

GitHub パイプラインでこの予防措置を回避するには、[フォークのビルドでシークレットを使用可能にします] チェック ボックスをオンにします。 この設定がセキュリティに及ぼす影響に注意してください。

注意

フォーク ビルドによるシークレットへのアクセスを有効にすると、Azure Pipelines は既定でフォーク ビルドに使われるアクセス トークンを制限します。 通常のアクセス トークンより、リソースを開くためのアクセスがいっそう制限されます。 通常のビルドと同じアクセス許可をフォーク ビルドに付与するには、[Make fork builds have the same permissions as regular builds] (フォーク ビルドが通常のビルドと同じアクセス許可を持つようにする) の設定を有効にします。

詳しくは、「リポジトリの保護」の「フォーク」を参照してください。

フォークされた GitHub リポジトリからの pull request をビルドする制限を使用して、フォークされた GitHub リポジトリからパイプラインが PR をビルドする方法を一元的に定義できます。 Organization とプロジェクト レベルで使用できます。 以下を選択できます:

  • フォークされたリポジトリからの pull request のビルドを無効にする
  • フォークされたリポジトリからの pull request を安全にビルドする
  • フォークされたリポジトリからの pull request をビルドするためのルールをカスタマイズする

フォークされた GitHub リポジトリからパイプラインが PR をビルドする方法に関する一元化されたコントロール設定のスクリーンショット。

スプリント 229 以降では、パイプラインのセキュリティを向上させるために、 Azure Pipelines では、フォークされた GitHub リポジトリから pull request が自動的にビルドされなくなりました。 新しいプロジェクトと組織の場合、[フォークされた GitHub リポジトリからのプル要求のビルドを制限する] 設定の既定値は、[フォークされたリポジトリからの pull request のビルドを無効にする] です。

[フォークされたリポジトリからの pull request を安全にビルドする] オプションを選択すると、すべてのパイプライン (organization またはプロジェクト全体) で、フォークされたリポジトリからの PR のビルドでシークレットを使用することが "できません"。また、これらのビルドに通常のビルドと同じアクセス許可を持たせることも "できず"、PR コメントによってトリガーする "必要があります"。 プロジェクトでは、引き続きパイプラインでこのような PR のビルドを許可 "しない" ように決定できます。

[カスタマイズ] オプションを選択すると、パイプライン設定を制限する方法を定義できます。 たとえば、PR が非チーム メンバーと非共同作成者に属している場合に、フォークされた GitHub リポジトリから PR をビルドするために、すべてのパイプラインにコメントを必要とするようにできます。 ただし、そのようなビルドでシークレットを使用できるようにすることもできます。 プロジェクトでは、パイプラインでこのような PR をビルドしたり、安全にビルドしたり、Organization レベルで指定された設定よりもさらに制限の厳しい設定を行ったりすることを許可 "しない" ようにすることができます。

既存の Organization のコントロールはオフです。 2023 年 9 月以降の新規の組織では、[フォークされたリポジトリからの pull request を安全にビルドする] がデフォルトで有効化されます

重要なセキュリティに関する考慮事項

GitHub ユーザーは、リポジトリをフォークして変更し、リポジトリへの変更を提案する pull request を作成できます。 この pull request には、トリガーされたビルドの一部として実行される悪意のあるコードが含まれている可能性があります。 このようなコードは、次のように危害を引き起こすおそれがあります。

  • パイプラインからシークレットを漏洩する。 このリスクを軽減するには、リポジトリがパブリックであるか、ビルドが自動的にトリガーされる pull request を信頼されていないユーザーが送信できる場合は、[フォークのビルドでシークレットを使用可能にします] チェック ボックスを有効にしないでください。 既定では、このオプションは無効になっています。

  • エージェントを実行しているマシンを侵害して、他のパイプラインからコードやシークレットを盗む。 これを軽減するには:

    • Microsoft によってホストされるエージェント プールを使って、フォークからの pull request をビルドします。 Microsoft によってホストされるエージェント マシンは、ビルドが完了すると直ちに削除されるため、侵害されても永続的な影響はありません。

    • セルフホステッド エージェントを使う必要がある場合は、リポジトリがプライベートであり pull request の作成者を信頼する場合を除き、シークレットを格納したり、同じエージェント上でシークレットを使用する他のビルドやリリースを実行したりしないでください。

コメント トリガー

リポジトリのコラボレーターは、pull request にコメントして、パイプラインを手動で実行できます。 これを行ういくつかの一般的な理由を次に示します。

  • その変更内容をレビューできるまでは、不明なユーザーからの pull request を自動的にビルドしたくない場合があります。 チーム メンバーの 1 人が最初にコードをレビューしてから、パイプラインを実行する必要があります。 これは、フォークされたリポジトリから提供されたコードをビルドする場合のセキュリティ対策としてよく使われます。
  • オプションのテスト スイートや、もう 1 つの検証ビルドを実行したい場合があります。

コメント トリガーを有効にするには、次の 2 つの手順に従う必要があります。

  1. パイプラインの pull request トリガーを有効にし、ターゲット ブランチを除外していないことを確認します。
  2. Azure Pipelines の Web ポータルで、パイプラインを編集し、[その他のアクション][トリガー] の順に選択します。 次に、[Pull request 検証] で、[pull request をビルドする前にチーム メンバーのコメントを要求する] を有効にします。
    • [すべての pull request 時] を選択して、pull request をビルドする前にチーム メンバーのコメントを要求します。 このワークフローでは、チーム メンバーが pull request をレビューし、pull request が安全と見なされると、コメントでビルドをトリガーします。
    • [チーム メンバー以外からの pull request 時のみ] を選択して、チーム メンバー以外が PR を作成した場合にのみチーム メンバーのコメントを要求します。 このワークフローでは、チーム メンバーがビルドをトリガーするために、二次的なチーム メンバーのレビューは必要ありません。

これら 2 つの変更により、pull request 検証ビルドは自動的にトリガーされなくなります。ただし、[チーム メンバー以外からの pull request 時のみ] を選択していて、PR がチーム メンバーによって作成された場合は除きます。 '書き込み' アクセス許可を持つリポジトリの所有者とコラボレーターのみが、/AzurePipelines run または /AzurePipelines run <pipeline-name> を使って pull request にコメントすることでビルドをトリガーできます。

次のコマンドは、コメントで Azure Pipelines に発行できます。

コマンド 結果
/AzurePipelines help サポートされているすべてのコマンドのヘルプを表示します。
/AzurePipelines help <command-name> 指定したコマンドのヘルプを表示します。
/AzurePipelines run このリポジトリに関連付けられているすべてのパイプラインを実行します。そのトリガーはこの pull request を除外しません。
/AzurePipelines run <pipeline-name> 指定したパイプラインを、そのトリガーがこの pull request を除外しない限り、実行します。

注意

簡潔にするために、/AzurePipelines ではなく /azp を使ってコメントできます。

重要

これらのコマンドに対する応答は、パイプラインで Azure Pipelines の GitHub App が使用されている場合にのみ、pull request ディスカッションに表示されます。

pull request コメント トリガーのトラブルシューティング

必要なリポジトリのアクセス許可を持っているのに、パイプラインがコメントによってトリガーされない場合は、リポジトリの組織で自分のメンバーシップがパブリックになっていることを確認するか、自分自身をリポジトリ コラボレーターとして直接追加してください。 パイプラインでは、プライベートな組織のメンバーは、直接のコラボレーターであるか、直接のコラボレーターであるチームに属していない限り、認識されません。 GitHub 組織のメンバーシップは、https://github.com/orgs/Your-Organization/people でプライベートからパブリックに変更できます (Your-Organization はご自分の組織名に置き換えてください)。

情報提供の実行

情報提供の実行では、Azure DevOps が YAML パイプラインのソース コードの取得に失敗したことが通知されます。 ソース コードの取得は、プッシュされたコミットなどの外部イベントに応答して実施されます。 また、コードの変更があるかどうかや、スケジュールされた実行を開始するかどうかなどのチェックのために、内部トリガーに応答して実施されます。 ソース コードの取得は複数の原因で失敗する可能性があります。よくある原因として Git リポジトリ プロバイダーによる要求調整が挙げられます。 情報提供の実行の存在は、Azure DevOps がパイプラインを実行しようとしたことを意味しないこともあります。

情報提供の実行は、次のスクリーンショットで示すようなものです。

情報提供のパイプライン実行のスクリーンショット。

情報提供の実行は、次の属性によって認知できます。

  • 状態は Canceled です
  • 期間は < 1s です
  • 実行名に、次のテキストのいずれかが含まれいる。
    • Could not retrieve file content for {file_path} from repository {repo_name} hosted on {host} using commit {commit_sha}.
    • Could not retrieve content for object {commit_sha} from repository {repo_name} hosted on {host}.
    • Could not retrieve the tree object {tree_sha} from the repository {repo_name} hosted on {host}.
    • Could not find {file_path} from repository {repo_name} hosted on {host} using version {commit_sha}. One of the directories in the path contains too many files or subdirectories.
  • 通常、実行名には YAML パイプラインの読み込みが失敗する原因になった BitBucket/GitHub エラーが含まれています
  • ステージ/ジョブ/ステップはありません

詳細は、「情報提供の実行」を参照してください。

チェックアウト

パイプラインがトリガーされると、Azure Pipelines によって Azure Repos Git リポジトリからソース コードがプルされます。 この動作のさまざまな側面を制御できます。

注意

パイプラインにチェックアウト ステップを含めると、次のコマンドが実行されます: git -c fetch --force --tags --prune --prune-tags --progress --no-recurse-submodules origin --depth=1。 これがお客様のニーズを満たさない場合は、checkout: none で組み込みのチェックアウトを除外し、スクリプト タスクを使用して独自のチェックアウトを実行できます。

Git の優先バージョン

Windows エージェントには、Git の独自のコピーが付属しています。 付属のコピーを使用せずに、独自の Git を指定する場合は、System.PreferGitFromPathtrue に設定します 。 この設定は、Windows 以外のエージェントでは常に true です。

チェックアウト パス

1 つのリポジトリをチェックアウトする場合、既定では、ソース コードは s という名前のディレクトリにチェックアウトされます。 YAML パイプラインの場合は、path を使用して checkout を指定すると、これを変更できます。 指定したパスは、$(Agent.BuildDirectory) に対する相対パスです。 たとえば、チェックアウト パスの値が mycustompath$(Agent.BuildDirectory)C:\agent\_work\1 の場合、ソース コードは C:\agent\_work\1\mycustompath にチェックアウトされます。

複数の checkout ステップを使って、複数のリポジトリをチェックアウトしている場合、path を使ってフォルダーを明示的に指定しないと、各リポジトリは、リポジトリにちなんだ名前が付けられた s のサブフォルダーに配置されます。 たとえば、toolscode という名前の 2 つのリポジトリをチェックアウトすると、ソース コードは C:\agent\_work\1\s\toolsC:\agent\_work\1\s\code にチェックアウトされます。

チェックアウト パスの値を $(Agent.BuildDirectory) より上位のディレクトリ レベルに設定することはできないことに注意してください。そのため、path\..\anotherpath は有効なチェックアウト パスになりますが (C:\agent\_work\1\anotherpath)、..\invalidpath のような値は有効なチェックアウト パスにはなりません (C:\agent\_work\invalidpath)。

path 設定は、パイプラインのチェックアウト ステップで構成できます。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

サブモジュール

サブモジュールからファイルをダウンロードする場合は、パイプラインのチェックアウト ステップで submodules 設定を構成できます。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

ビルド パイプラインでは、次の場合に限り、Git サブモジュールをチェックアウトします。

  • 未認証: クローンまたはフェッチに必要な資格情報を持たない、認証されていないパブリック リポジトリ。

  • 認証済み:

    • 上記で指定した Azure Repos Git リポジトリと同じプロジェクトに含まれている。 メイン リポジトリからソースを取得するためにエージェントによって使用されるのと同じ資格情報を使用して、サブモジュールのソースを取得することもできます。

    • メイン リポジトリに対する相対 URL を使用して追加された。 次に例を示します。

      • 次はチェックアウトされます: git submodule add ../../../FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

        この例では、サブモジュールが参照するのは、同じ Azure DevOps 組織内の、別のプロジェクト (FabrikamFiberProject) 内のリポジトリ (FabrikamFiber) です。 メイン リポジトリからソースを取得するためにエージェントによって使用されるのと同じ資格情報を使用して、サブモジュールのソースを取得することもできます。 そのためには、ジョブ アクセス トークンが 2 番目のプロジェクトのリポジトリにアクセスできる必要があります。 上記のセクションで説明したようにジョブ アクセス トークンを制限した場合、これを行うことはできません。 ジョブ アクセス トークンが 2 番目のプロジェクトのリポジトリにアクセスできるようにするには、(a) 2 番目のプロジェクトのプロジェクト ビルド サービス アカウントへのアクセスを明示的に許可するか、(b) 組織全体のプロジェクト スコープ トークンではなくコレクション スコープのアクセス トークンを使用します。 これらのオプションとそのセキュリティへの影響について詳しくは、「リポジトリ、成果物、およびその他のリソースにアクセスする」を参照してください。

      • 次はチェックアウトされません: git submodule add https://fabrikam-fiber@dev.azure.com/fabrikam-fiber/FabrikamFiberProject/_git/FabrikamFiber FabrikamFiber

[サブモジュールのチェックアウト] オプションの使用に代わる方法

[サブモジュールをチェックアウト] オプションを使用できない場合があります。 各サブモジュールにアクセスするために別の資格情報セットが必要になるシナリオが考えられます。 これは、たとえば、メイン リポジトリとサブモジュール リポジトリが同じ Azure DevOps 組織に格納されていない場合や、ジョブ アクセス トークンが別のプロジェクトのリポジトリにアクセスできない場合などに発生する可能性があります。

[サブモジュールのチェックアウト] オプションを使用できない場合は、代わりにカスタム スクリプト ステップを使用してサブモジュールをフェッチできます。 まず、個人用アクセス トークン (PAT) を取得し、pat: のプレフィックスを付けます。 次に、このプレフィックス付き文字列を base64 でエンコードして、基本認証トークンを作成します。 最後に、次のスクリプトをパイプラインに追加します。

git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: Basic <BASE64_ENCODED_STRING>" submodule update --init --recursive

"<BASE64_ENCODED_STRING>" は必ず Base64 でエンコードした "pat:token" 文字列に置き換えてください。

プロジェクトまたはビルド パイプラインでシークレット変数を使用して、生成した基本認証トークンを格納します。 その変数を使用して、上記の Git コマンドでシークレットを設定します。

Note

Q: エージェントで Git 資格情報マネージャーを使用できないのはなぜですか? A: プライベート ビルド エージェントにインストールされている Git 資格情報マネージャーにサブモジュールの資格情報を格納することは、通常は有効ではありません。これは、サブモジュールが更新されるたびに資格情報を再入力するように資格情報マネージャーから求められる場合があるためです。 これは、ユーザーの操作が不可能な自動ビルド中は望ましくありません。

タグを同期する

重要

同期タグ機能は、Azure DevOps Server 2022.1 以降の Azure Repos Git でサポートされています。

チェックアウト ステップでは、Git リポジトリの内容をフェッチするときに --tags オプションを使用します。 これにより、サーバーはすべてのタグと、それらのタグが指すすべてのオブジェクトをフェッチします。 これにより、特に多数のタグを持つ大規模なリポジトリがある場合に、パイプラインでタスクを実行する時間が長くなります。 さらに、チェックアウト ステップでは、浅いフェッチ オプションを有効にした場合でもタグが同期されるため、逆効果になる可能性があります。 Git リポジトリからフェッチまたはプルされるデータの量を減らすために、タグの同期の動作を制御するための新しいオプションが Microsoft によってチェックアウトに追加されました。 このオプションは、クラシック パイプラインと YAML パイプラインの両方で使用できます。

リポジトリをチェックアウトするときにタグを同期するかどうかは、YAML で fetchTags プロパティを設定するか、UI で [タグの同期] 設定を構成することで構成できます。

fetchTags 設定は、パイプラインのチェックアウト ステップで構成できます。

YAML で設定を構成するには、fetchTags プロパティを設定します。

steps:
- checkout: self
  fetchTags: true

パイプライン設定 UI の [タグの同期] オプションを使用して、この設定を構成することもできます。

  1. YAML パイプラインを編集し、[その他のアクション][トリガー] を選択します。

    その他のトリガー メニューのスクリーンショット。

  2. [YAML][ソースの取得] を選択します。

    ソースの取得のスクリーンショット。

  3. [タグの同期] 設定を構成します。

    [タグの同期] 設定のスクリーンショット。

注意

checkout ステップで fetchTags を明示的に設定した場合、その設定はパイプライン設定 UI で構成された設定よりも優先されます。

既定の動作

  • 2022 年 9 月にリリースされた Azure DevOps スプリント 209 のリリース前に作成された既存のパイプラインの場合、タグの同期の既定値は、[タグの同期] オプションが追加される前の既存の動作 (true) と同じままです。
  • Azure DevOps スプリント リリース 209 の後に作成された新しいパイプラインの場合、タグの同期の既定値は false です。

注意

checkout ステップで fetchTags を明示的に設定した場合、その設定はパイプライン設定 UI で構成された設定よりも優先されます。

浅いフェッチ

履歴をどれだけさかのぼってダウンロードするかを制限したい場合があります。 その場合は、実質的に git fetch --depth=n を使うことになります。 リポジトリが大きい場合、このオプションを使用すると、ビルド パイプラインの効率が高まる可能性があります。 リポジトリが長い間使用されており、サイズの大きい履歴がある場合は、リポジトリが大きくなる可能性があります。 また、大きなファイルを追加して後で削除した場合も大きくなる可能性があります。

重要

2022 年 9 月の Azure DevOps スプリント 209 更新後に作成された新しいパイプラインでは、既定で [浅いフェッチ] が有効になっており、深さが 1 で構成されています。 以前は、既定では浅いフェッチは行われませんでした。 パイプラインをチェックするには、次のセクションで説明するように、パイプライン設定 UI で [浅いフェッチ] 設定を表示します。

fetchDepth 設定は、パイプラインのチェックアウト ステップで構成できます。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

パイプライン設定 UI で [浅い深度] オプションを設定して、フェッチの深さを構成することもできます。

  1. YAML パイプラインを編集し、[その他のアクション][トリガー] を選択します。

    その他のトリガー メニューのスクリーンショット。

  2. [YAML][ソースの取得] を選択します。

    ソースの取得のスクリーンショット。

  3. [浅いフェッチ] 設定を構成します。 [浅いフェッチ] をオフにして浅いフェッチを無効にするか、ボックスをオンにし、[深さ] を入力して浅いフェッチを有効にします。

    オプションのスクリーンショット。

注意

checkout ステップで fetchDepth を明示的に設定した場合、その設定はパイプライン設定 UI で構成された設定よりも優先されます。 fetchDepth: 0 を設定すると、すべての履歴がフェッチされ、[浅いフェッチ] 設定はオーバーライドされます。

このような場合、このオプションは、ネットワークおよびストレージ リソースを節約するのに役立ちます。 また、時間を節約することもできます。 時間が常に節約されるとは限らない理由は、場合によっては、指定した深さのためにダウンロードするコミットの計算にサーバーが時間を費やす必要がある可能性があるためです。

注意

パイプラインが開始されると、ビルドするブランチがコミット ID に解決されます。 次に、エージェントがブランチをフェッチし、目的のコミットをチェックアウトします。 ブランチがコミット ID に解決されてから、エージェントがチェックアウトを実行するまで少し時間がかかります。 ブランチがすばやく更新され、浅いフェッチに非常に小さな値を設定した場合、エージェントがチェックアウトしようとしたときにコミットが存在しない可能性があります。その場合は、浅いフェッチの深さの設定を増やします。

ソースを同期しない

新しいコミットのフェッチをスキップすることもできます。 このオプションは、次の場合に役立ちます。

  • 独自のカスタム オプションを使って Git init、config、fetch を実行する。

  • ビルド パイプラインを使って、バージョン コントロールのコードに依存しない自動化 (一部のスクリプトなど) のみを実行する。

[ソースを同期しない] 設定は、パイプラインのチェックアウト ステップで、checkout: none を設定して構成できます。

steps:
- checkout: none  # Don't sync sources

注意

このオプションを使用すると、エージェントではリポジトリをクリーニングする Git コマンドの実行もスキップします。

クリーン ビルド

ビルドの実行前に、セルフホステッド エージェントの作業ディレクトリに対してさまざまな形式のクリーニングを実行できます。

一般に、セルフホステッド エージェントのパフォーマンスを向上させるには、リポジトリをクリーンしないでください。 このケースでは、最適なパフォーマンスを得るために、ビルドに使用するタスクまたはツールのクリーン オプションを無効にして、インクリメンタル ビルドを実行するようにもしてください。

(以前のビルドの残留ファイルによる問題を回避する目的などで) リポジトリをクリーンする必要がある場合は、以下のオプションを使用できます。

注意

Microsoft ホステッドエージェントを使用している場合は、新しいエージェントが毎回取得されるため、クリーニングは効果的ではありません。

clean 設定は、パイプラインのチェックアウト ステップで構成できます。

steps:
- checkout: self  # self represents the repo where the initial Pipelines YAML file was found
  clean: boolean  # whether to fetch clean each time
  fetchDepth: number  # the depth of commits to ask Git to fetch
  lfs: boolean  # whether to download Git-LFS files
  submodules: true | recursive  # set to 'true' for a single level of submodules or 'recursive' to get submodules of submodules
  path: string  # path to check out source code, relative to the agent's build directory (e.g. \_work\1)
  persistCredentials: boolean  # set to 'true' to leave the OAuth token in the Git config after the initial fetch

cleantrue に設定されている場合、ビルド パイプラインでは $(Build.SourcesDirectory) の変更を元に戻します。 具体的には、ソースをフェッチする前に、次の Git コマンドが実行されます。

git clean -ffdx
git reset --hard HEAD

その他のオプションについては、ジョブworkspace 設定を構成できます。

jobs:
- job: string  # name of the job, A-Z, a-z, 0-9, and underscore
  ...
  workspace:
    clean: outputs | resources | all # what to clean up before the job runs

これにより、次のクリーニング オプションが提供されます。

  • outputs: 前のチェックアウト タスクで説明したクリーニング設定と同じ操作に加えて、$(Build.BinariesDirectory) を削除して再作成します。 $(Build.ArtifactStagingDirectory)$(Common.TestResultsDirectory) は、これらの設定に関係なく、すべてのビルドの前に常に削除されて再作成されることに注意してください。

  • resources: $(Build.SourcesDirectory) を削除して再作成します。 これにより、ビルドごとに新しいローカル Git リポジトリが初期化されます。

  • all: $(Agent.BuildDirectory) を削除して再作成します。 これにより、ビルドごとに新しいローカル Git リポジトリが初期化されます。

ソースのラベル作成

完成したビルドに含まれる各ファイルのバージョンをチームが簡単に識別できるように、ソース コード ファイルにラベルを付ける必要がある場合があります。 また、すべてのビルドに対してソース コードにラベルを付けるか、成功したビルドでのみラベルを付けるかを指定することもできます。

現在、YAML でこの設定を構成することはできませんが、クラシック エディターでは構成できます。 YAML パイプラインを編集する場合は、YAML エディター メニューから [トリガー] を選択してクラシック エディターにアクセスできます。

Git オプションを構成します (YAML)。

クラシック エディターから [YAML] を選択し、[ソースの取得] タスクを選択して、そこで目的のプロパティを構成します。

クラシック エディターから [YAML] > [ソースの取得] を選択します。

[タグ形式] では、スコープが "すべて" であるユーザー定義変数と事前定義済み変数を使用できます。例:

$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)

最初の 4 つの変数は事前定義済みです。 My.Variable は、ユーザーが [変数] タブで定義できます。

ビルド パイプラインは、ソースに Git タグでラベルを付けます。

一部のビルド変数では、有効なラベルではない値が生成される場合があります。 たとえば、$(Build.RequestedFor)$(Build.DefinitionName) などの変数には空白を含めることができます。 値に空白が含まれている場合、タグは作成されません。

ソースがビルド パイプラインによってタグ付けされると、Git ref refs/tags/{tag} を含む成果物が完了したビルドに自動的に追加されます。 これにより、チームの追跡可能性が向上し、ビルドからビルドされたコードに簡単に移動できます。 タグはビルドによって生成されるため、ビルド成果物と見なされます。 ビルドが手動またはアイテム保持ポリシーによって削除されると、タグも削除されます。

事前定義済み変数

GitHub リポジトリをビルドする場合、ほとんどの事前定義済み変数はジョブで使用できます。 ただし、Azure Pipelines では GitHub で更新を行うユーザーの ID が認識されないため、次の変数はユーザーの ID ではなくシステム ID に設定されます。

  • Build.RequestedFor
  • Build.RequestedForId
  • Build.RequestedForEmail

ステータスの更新

Azure Pipelines が GitHub にポストバックする状態には、基本的な状態と GitHub Check Runs の 2 種類があります。 GitHub Checks 機能は、GitHub Apps でのみ使用できます。

パイプラインの状態は、GitHub UI のさまざまな場所に表示されます。

  • PR の場合は、PR の会話タブに表示されます。
  • 個々のコミットの場合は、リポジトリのコミット タブでコミット時間の後に状態マークにカーソルを合わせると表示されます。

PAT または OAuth GitHub 接続

PAT または OAuth GitHub 接続を使用するパイプラインの場合、実行をトリガーしたコミットまたは PR に状態がポストバックされます。 GitHub 状態 API は、このような更新をポストするために使われます。 これらの状態には、限られた情報が含まれています。たとえば、パイプラインの状態 (失敗、成功)、ビルド パイプラインにリンクされた URL、状態の簡単な説明などです。

PAT または OAuth GitHub 接続の状態は、実行レベルでのみ送信されます。 つまり、1 つの実行全体に対して 1 つの状態が更新されます。 1 つの実行に複数のジョブがある場合、ジョブごとに個別の状態をポストすることはできません。 ただし、複数のパイプラインで同じコミットに個別の状態をポストすることはできます。

GitHub Checks

Azure Pipelines GitHub アプリを使って設定されたパイプラインの場合、状態は GitHub Checks の形式でポストバックされます。 GitHub Checks により、パイプラインの状態とテスト、コード カバレッジ、エラーに関する詳細情報を送信できます。 GitHub Checks API は、こちらで確認できます。

GitHub App を使用するすべてのパイプラインで、実行全体とその実行内の各ジョブに関する Checks がポストバックされます。

GitHub では、PR またはコミットに対して 1 つ以上のチェック実行が失敗した場合に、3 つのオプションを使用できます。 個々のチェックを "再実行" するか、その PR またはコミットで失敗したすべてのチェックを再実行するか、すべてのチェックを最初に成功したかどうかに関係なく再実行するかを選択できます。

GitHub チェックの再実行

チェックの実行名の横にある [再実行] リンクをクリックすると、そのチェックの実行を生成した実行が Azure Pipelines によって再試行されます。 その結果の実行は同じ実行番号を持ち、最初のビルドと同じバージョンのソース コード、構成、YAML ファイルが使用されます。 最初の実行で失敗したジョブと、依存するダウンストリーム ジョブのみが再度実行されます。 [失敗したすべてのチェックを再実行する] リンクをクリックすると、同じ効果が得られます。 これは、Azure Pipelines の UI で [実行の再試行] をクリックした場合と同じ動作です。 [すべてのチェックを再実行する] をクリックすると、新しい実行番号で新しい実行が行われ、構成や YAML ファイルの変更が取得されます。

制限事項

  • 最高のパフォーマンスを実現するには、1 つのリポジトリに含めるパイプライン数を最大 50 個にすることをお勧めします。 許容できるパフォーマンスを実現するには、1 つのリポジトリに含めるパイプライン数を最大 100 個にすることをお勧めします。 リポジトリへのプッシュを処理するために必要な時間は、そのリポジトリ内のパイプラインの数に応じて増加します。 Azure Pipelines は、リポジトリへのプッシュがあるたびに、そのリポジトリ内のすべての YAML パイプラインを読み込んで、それらのいずれかを実行する必要があるかどうかを判断する必要があり、各パイプラインを読み込むとパフォーマンスが低下します。 パフォーマンスの問題に加えて、1 つのリポジトリにパイプラインが多すぎると、Azure Pipelines が短時間で多すぎる要求を行う可能性があるため、GitHub 側で調整が発生する可能性があります。

  • extendinclude テンプレートを使用すると、Azure Pipelines が GitHub API リクエストを行う速度に影響し、GitHub 側での調整につながる可能性があります。 パイプラインを実行する前に、Azure Pipelines は完全な YAML コードを生成する必要があるため、すべてのテンプレート ファイルをフェッチする必要があります。

  • Azure Pipelines は、リポジトリから Azure DevOps ポータルのドロップダウン リストに最大 2,000 個のブランチを読み込みます。たとえば、[手動のビルドとスケジュールされたビルドの既定のブランチ] 設定用の [ブランチの選択] ウィンドウに読み込んだり、パイプラインを手動で実行するときにブランチを選択したときです。

    一覧に目的のブランチが表示されない場合は、目的のブランチ名を [手動のビルドとスケジュールされたビルドの既定のブランチ] フィールドに手動で入力します。

    省略記号をクリックして [ブランチの選択] ダイアログを開き、ドロップダウン リストから有効なブランチを選択せずにダイアログを閉じると、[手動のビルドとスケジュールされたビルドの既定のブランチ] の下に "いくつかの設定を確認する必要がある" というメッセージと "この設定が必要" というメッセージが表示される場合があります。 このメッセージを回避するには、パイプラインを再度開き、[手動のビルドとスケジュールされたビルドの既定のブランチ] フィールドに、名前を直接入力します。

よく寄せられる質問

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

  • 接続の種類: パイプラインを GitHub に接続するために使用している接続の種類がわかりません。
  • トリガーの失敗: リポジトリに更新をプッシュしたときに、パイプラインがトリガーされません。
  • チェックアウトの失敗: パイプラインはトリガーされますが、チェックアウト ステップで失敗します。
  • 間違ったバージョン: パイプラインは実行されますが、ソース/YAML の予期しないバージョンが使用されています。
  • 状態の更新がない: Azure Pipelines によって状態の更新が報告されていないため、GitHub の PR がブロックされます。

接続の種類

トリガーのトラブルシューティングを行う場合、パイプラインで使っている GitHub 接続の種類を知るにはどうすればよいですか?

トリガーに関する問題のトラブルシューティングは、パイプラインで使用する GitHub 接続の種類に大きく依存します。 接続の種類を判断するには、GitHub から判断するか、Azure Pipelines から判断するかの 2 つの方法があります。

  • GitHub から: GitHub アプリを使うようにリポジトリが設定されている場合、PR とコミットの状態は [チェックの実行] になります。 リポジトリで OAuth または PAT 接続を使って Azure Pipelines が設定されている場合、状態は "古い" スタイルの状態になります。 状態が [チェックの実行] かシンプルな状態かを判断する簡単な方法は、GitHub PR の [会話] タブを確認することです。

    • [詳細] リンクが [チェック] タブにリダイレクトされる場合は、チェックの実行であり、リポジトリではアプリが使用されています。
    • [詳細] リンクが Azure DevOps パイプラインにリダイレクトされる場合、状態は "古いスタイル" の状態であり、リポジトリではアプリが使用されていません。
  • Azure Pipelines から: Azure Pipelines の UI でパイプラインを調べることで、接続の種類を判断することもできます。 パイプラインのエディターを開きます。 [トリガー] を選択し、パイプラインのクラシック エディターを開きます。 次に、[YAML] タブを選択し、[ソースの取得] ステップを選択します。 パイプラインを GitHub と統合するために使われたサービス接続を示す、[接続の使用を承認:] というバナーが表示されます。 サービス接続の名前はハイパーリンクになっています。 それを選択して、サービス接続のプロパティに移動します。 サービス接続のプロパティは、使用されている接続の種類を示します。

    • [Azure Pipelines アプリ] は GitHub アプリ接続を示します
    • [oauth] は OAuth 接続を示します
    • personalaccesstoken は PAT 認証を示します

OAuth ではなく GitHub アプリを使うようにパイプラインを切り替えるにはどうすればよいですか?

GitHub と Azure Pipelines 間の統合では、OAuth や PAT 接続の代わりに GitHub アプリを使うことが推奨されます。 GitHub アプリに切り替えるには、次の手順に従います。

  1. こちらに移動し、リポジトリの GitHub 組織にアプリをインストールします。
  2. インストール中に、Azure DevOps にリダイレクトされるので、Azure DevOps の組織とプロジェクトを選択します。 アプリを使いたいクラシック ビルド パイプラインを含む組織とプロジェクトを選択します。 この選択により、GitHub App のインストールが Azure DevOps 組織に関連付けられます。 間違って選択した場合は、こちらのページにアクセスして GitHub 組織から GitHub アプリをアンインストールし、もう一度やり直すことができます。
  3. 表示される次のページでは、新しいパイプラインの作成を始める必要はありません。
  4. [パイプライン] ページ (例: https://dev.azure.com/YOUR_ORG_NAME/YOUR_PROJECT_NAME/_build) にアクセスして、パイプラインを選択し、[編集] をクリックして、パイプラインを編集します。
  5. これが YAML パイプラインの場合は、[トリガー] メニューを選択してクラシック エディターを開きます。
  6. パイプラインの [ソースの取得] ステップを選択します。
  7. "接続の使用を承認" というテキストが表示された緑色のバーで、[変更] を選択し、アプリをインストールした GitHub 組織と同じ名前の GitHub App 接続を選択します。
  8. ツール バーで、[保存してキューに登録] を選択し、[保存してキューに登録] を選択します。 キューに登録されたパイプライン実行へのリンクを選択して、成功したことを確認します。
  9. GitHub リポジトリに pull request を作成して (または閉じて再度開いて)、ビルドがその "Checks" セクションで正常にキューに登録されていることを確認します。

Azure Pipelines で GitHub リポジトリが選択肢として表示されないのはなぜですか?

リポジトリの認証の種類と所有権によっては、特定のアクセス許可が必要になります。

パイプラインの作成時にリポジトリを選択すると、"リポジトリ {repo-name} は、他の Azure DevOps 組織で Azure Pipelines GitHub App とともに使用されています" というエラーが表示されます。

これは、リポジトリが別の組織内のパイプラインに既に関連付けられていることを意味します。 このリポジトリからの CI イベントと PR イベントは、その別の組織に配信されるため、機能しません。 パイプラインの作成に進む前に、別の組織へのマッピングを削除するために実行する必要がある手順を次に示します。

  1. GitHub リポジトリで pull request を開き、/azp where というコメントを作成します。 これにより、リポジトリがマップされている Azure DevOps 組織が報告されます。

  2. マッピングを変更するには、GitHub 組織からアプリをアンインストールして、再インストールします。 再インストールする際は、Azure DevOps にリダイレクトされるときに正しい組織を選択してください。

トリガーの失敗

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

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

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

    パイプライン設定の UI。

    リポジトリに使用できるトリガーの種類 ([継続的インテグレーション] または [Pull request 検証]) に対して、[Override the YAML trigger from here] (ここから YAML トリガーをオーバーライドする) 設定をオンにします。

    ここから YAML トリガーをオーバーライドする。

  • GitHub アプリ接続を使ってパイプラインを GitHub に接続していますか。 「接続の種類」を参照して、使用している接続の種類を判断してください。 GitHub アプリ接続を使用している場合は、次の手順に従います。

    • GitHub と Azure DevOps の間でマッピングが正しく設定されていますか。 GitHub リポジトリで pull request を開き、/azp where というコメントを作成します。 これにより、リポジトリがマップされている Azure DevOps 組織が報告されます。

      • アプリを使ってこのリポジトリをビルドするように設定されている組織がない場合は、https://github.com/<org_name>/<repo_name>/settings/installations に移動してアプリの構成を完了します。

      • 別の Azure DevOps 組織が報告された場合は、他のユーザーが別の組織でこのリポジトリのパイプラインを既に確立しています。 現時点では、GitHub リポジトリをマップできる DevOps 組織は 1 つのみという制限があります。自動的にトリガーできるのは最初の Azure DevOps 組織のパイプラインのみです。 マッピングを変更するには、GitHub 組織からアプリをアンインストールして、再インストールします。 再インストールする際は、Azure DevOps にリダイレクトされるときに正しい組織を選択してください。

  • OAuth または PAT を使ってパイプラインを GitHub に接続していますか。 「接続の種類」を参照して、使用している接続の種類を判断してください。 GitHub 接続を使用している場合は、次の手順に従います。

    1. OAuth 接続と PAT 接続では、Webhook を使って Azure Pipelines に更新を通信します。 GitHub で、リポジトリの設定に移動し、[Webhook] に移動します。 Webhook があることを確認します。 通常、3 つの Webhook (push、pull_request、issue_comment) があるはずです。 ない場合は、サービス接続を再作成し、新しいサービス接続を使用するようにパイプラインを更新する必要があります。

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

  • Azure DevOps からのトラフィックは、GitHub によって調整される可能性があります。 Azure Pipelines は GitHub から通知を受け取ると、GitHub へ通信し、リポジトリと YAML ファイルに関する詳細情報の取得を試みます。 多数の更新と pull request を含むリポジトリがある場合、このような調整が原因でこの呼び出しが失敗するおそれがあります。 その場合は、バッチ処理またはより厳密なパス/ブランチ フィルターを使ってビルドの頻度を減らすことができるかどうかを確認してください。

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

  • 正しいブランチの 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 パイプラインを読み込んで、実行する必要があるパイプラインがあるかどうかを判断する必要があり、新しいパイプラインごとにパフォーマンスのペナルティが発生します。

ユーザーが YAML ファイルを更新するときに、トリガーのブランチの一覧をオーバーライドしないようにする必要があります。 どうすればよいですか?

コードを投稿するアクセス許可を持つユーザーは、YAML ファイルを更新し、追加のブランチを含めたり除外したりできます。 そのため、ユーザーは YAML ファイルに独自の機能やユーザー ブランチを含め、その更新を機能またはユーザー ブランチにプッシュすることができます。 これにより、そのブランチに対するすべての更新に対してパイプラインがトリガーされる可能性があります。 この動作を防ぐ場合は、次の手順を実行できます。

  1. Azure Pipelines UI でパイプラインを編集します。
  2. [トリガー] メニューに移動します。
  3. [ここから YAML 継続的インテグレーション トリガーを上書きする] を選択します。
  4. トリガーに含めるブランチまたは除外するブランチを指定します。

これらの手順に従うと、YAML ファイルで指定された CI トリガーはすべて無視されます。

チェックアウトの失敗

チェックアウト ステップ中にログ ファイルに次のエラーが表示されます。 どのように修正すればよいですか

remote: Repository not found.
fatal: repository <repo> not found

これは、GitHub の停止が原因である可能性があります。 GitHub のリポジトリにアクセスしてみて、アクセスできることを確認してください。

バージョンが正しくない

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

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

状態の更新がない

Azure Pipelines によって状態が更新されていないため、GitHub の PR がブロックされます。

これは、Azure DevOps が GitHub と通信できなくなった一時的なエラーである可能性があります。 GitHub アプリを使用している場合は、チェックイン GitHub を再試行してください。 または、PR を簡単に更新して、問題を解決できるかどうかを確認してください。