Azure Repos Git または TFS Git リポジトリをビルドする

Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019

Azure Pipelines では、すべての pull request を自動的に構築して検証し、Azure Repos Git リポジトリに対してコミットできます。

デプロイするリポジトリを選択する

YAML

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

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

クラシック

パイプラインの作成時に、ビルドするリポジトリを選択するには、まずリポジトリが属するプロジェクトを選択します。 次に、リポジトリを選択します。

パイプラインの一部として追加のリポジトリを複製するには:

• リポジトリがパイプラインと同じプロジェクトにある場合、またはアクセス トークン (後述) が別のプロジェクトのリポジトリにアクセスできる場合は、次のコマンドを使用します。

  git clone -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" <clone URL>

  スクリプトで System.AccessToken を使用するには、まずスクリプトで使用できるようにする必要があります。 これを行うには、エディターの [タスク] タブでジョブを選択し、右側のパネルで [その他のオプション] を選択して、[スクリプトが OAuth トークンにアクセスできるようにする] オプションをチェックします。

• アクセス トークン (後述) がリポジトリにアクセスできない場合:

  1. Code (read) スコープを持つ個人用アクセス トークン (PAT) を取得し、PAT: のプレフィックスを付けます。
  2. 基本認証トークンを作成するには、この文字列を Base64 エンコードします。
  3. git clone -c http.extraheader="AUTHORIZATION: basic <BASIC_AUTH_TOKEN>" <clone URL> のコマンドを使用して、パイプラインにスクリプトを追加し、そのリポジトリを複製します。

ビルドをトリガーし、ビルド中にコードをフェッチするには、Azure Pipelines にリポジトリへのアクセス権を付与する必要があります。 通常、パイプラインでは同じプロジェクト内のリポジトリにアクセスできます。 ただし、別のプロジェクトのリポジトリにアクセスする場合は、ジョブ アクセス トークンに付与されたアクセス許可を更新する必要があります。

CI トリガー

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

YAML

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 実行のバッチ処理

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

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

注意

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

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

注意

パイプラインに複数のジョブとステージがある場合でも、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 実行を開始する必要があるかどうかを判断します。

クラシック

ユーザーがコードをチェックインするたびにビルドが実行されるようにする場合は、[トリガー] タブで [継続的インテグレーションを有効にする] を選択してこのトリガーを有効にします。

バッチ変更

多数のチーム メンバーが頻繁に変更をアップロードする場合に、実行するビルドの数を減らすには、このチェック ボックスをオンにします。 このオプションを選択した場合は、ビルドが実行されているとき、システムは実行が完了するまで待機し、まだビルドされていないすべての変更の別の実行をキューに入れます。

変更をバッチ処理し、まとめてビルドすることができます。

注意

複数ステージの YAML パイプラインでバッチ処理を使用する場合は、次の 1 つを開始する前に、実行が終了状態に達する必要があります。 多くの場合、これは、複数ステージのパイプラインが承認と実行時間の長いデプロイ ステージを通過する可能性があるため、望ましくありません。 このような場合は、次のいずれかの解決策に従うことをお勧めします。

• バッチ処理を使用しない
• パイプラインを CI 用と CD 用の 2 つの別個のパイプラインに分割する
• ステージに適切な条件を設定してそれらをスキップし、実行をすばやく終了させる

ブランチ フィルター

ビルドをトリガーするブランチを指定できます。 ワイルドカード文字を使用する場合は、ブランチ仕様 (例: features/modules/*) を入力し、Enter キーを押します。

パス フィルター

Git リポジトリが Azure Repos または TFS にある場合は、パス フィルターを指定して、ビルドをトリガーするファイルのセットを減らすこともできます。

ヒント:

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

例

たとえば、すべてではないが、機能ブランチのほとんどと main の変更によってビルドをトリガーするとします。 また、ツール フォルダー内のファイルに対する変更によってビルドがトリガーされないようにする必要もあります。

個々のプッシュの 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 (PR) トリガーを使用すると、pull request を開くとき、または変更をプッシュするたびにパイプラインが実行されます。 Azure Repos Git では、この機能はブランチ ポリシーを使用して実装されます。 PR 検証を有効にするには、目的のブランチのブランチ ポリシーに移動し、そのブランチのビルド検証ポリシーを構成します。 詳細については、ブランチ ポリシーの構成に関する記事を参照してください。

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

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

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

注意

Azure Repos Git リポジトリの検証ビルドを構成するには、そのプロジェクトのプロジェクト管理者である必要があります。

注意

ドラフトの pull requestでは、ブランチ ポリシーを構成してもパイプラインはトリガーされません。

フォークからコントリビューションを検証する

Azure Repos フォークからの pull request のビルドは、同じリポジトリまたはプロジェクト内で pull request をビルドするのと変わりません。 フォークは、プロジェクトが含まれる同じ組織内でのみ作成できます。

ジョブの承認スコープを制限する

Azure Pipelines には、パイプラインで実行されるジョブの承認スコープを構成するためのセキュリティ設定がいくつか用意されています。

• ジョブの承認スコープを現在のプロジェクトに制限する
• YAML パイプライン内のリポジトリへのアクセスを保護する

ジョブの承認スコープを現在のプロジェクトに制限する

Azure Pipelines には、ジョブの承認のスコープを現在のプロジェクトに制限する設定が 2 つ 用意されています。

• ジョブの承認スコープを非リリース パイプラインの現在のプロジェクトに制限する - この設定は、YAML パイプラインとクラシック ビルド パイプラインに適用されます。 この設定は、クラシック リリース パイプラインには適用されません。
• ジョブの承認スコープをリリース パイプラインの現在のプロジェクトに制限する - この設定は、クラシック リリース パイプラインのみに適用されます。

パイプラインの種類に関連する設定が有効になっていない限り、パイプラインはコレクション スコープのアクセス トークンで実行されます。 [ジョブの承認スコープを制限する] 設定を使用すると、現在のプロジェクトに対するすべてのパイプラインのアクセスのスコープを減らすことができます。 これは、組織内の別のプロジェクトの Azure Repos Git リポジトリにアクセスする場合、パイプラインに影響を与える可能性があります。

Azure Repos Git リポジトリがパイプラインとは異なるプロジェクトにあり、パイプラインの種類の [ジョブの承認スコープを制限する] 設定が有効になっている場合は、パイプラインのビルド サービス ID に対するアクセス許可を 2 番目のプロジェクトに付与する必要があります。 詳細については、「ビルド サービス アカウントのアクセス許可を管理する」を参照してください。

ジョブの承認スコープの制限の詳細については、「ジョブ アクセス トークンについて」を参照してください。

YAML パイプライン内のリポジトリへのアクセスを保護する

パイプラインでは、前述の「ジョブの承認スコープを現在のプロジェクトに制限する」セクションで説明されているように、[YAML パイプライン内のリポジトリへのアクセスを保護する] が有効になっていない限り、承認されたプロジェクト内のすべての Azure DevOps リポジトリにアクセスできます。 このオプションを有効にすると、すべてのパイプラインのアクセスのスコープを、そのリポジトリを使用するパイプライン ジョブの checkoutステップまたは uses ステートメントによって明示的に参照される Azure DevOps リポジトリのみに減らすことができます。

この設定を構成するには、[パイプライン]、[設定] ([組織の設定] または [プロジェクトの設定] のいずれか) に移動します。 組織レベルで有効にすると、設定は淡色表示され、プロジェクト設定レベルでは使用できません。

重要

[YAML パイプライン内のリポジトリへのアクセスを保護する] は、2020 年 5 月以降に作成された新しい組織とプロジェクトに対して既定で有効になっています。 [YAML パイプライン内のリポジトリへのアクセスを保護する] が有効になっている場合、YAML パイプラインでは、リポジトリを使用するジョブのチェックアウト ステップとして、パイプラインで使用する Azure Repos Git リポジトリを明示的に参照する必要があります。 そのリポジトリが最初に明示的に参照されていない限り、Azure Repos Git リポジトリのスクリプト タスクと Git コマンドを使用してコードをフェッチすることはできません。

[YAML パイプライン内のリポジトリへのアクセスを保護する] が有効になっている場合、パイプラインで使用する前に、Azure Repos Git リポジトリを明示的に参照する必要がない例外がいくつかあります。

• パイプラインに明示的なチェックアウト ステップがない場合は、checkout: self ステップがあるかのように、self リポジトリがチェックアウトされます。
• スクリプトを使用してパブリック プロジェクトのリポジトリに対して読み取り専用操作を実行する場合、checkout ステップでパブリック プロジェクト リポジトリを参照する必要はありません。
• PAT など、リポジトリに独自の認証を提供するスクリプトを使用している場合は、そのリポジトリを checkout ステップで参照する必要はありません。

たとえば、[YAML パイプライン内のリポジトリへのアクセスを保護する] が有効になっている場合、パイプラインが組織の FabrikamProject/Fabrikam リポジトリ内にあり、スクリプトを使用して FabrikamProject/FabrikamTools リポジトリをチェックアウトする場合は、checkout ステップまたは uses ステートメントでこのリポジトリを参照する必要があります。

チェックアウト ステップを使用してパイプライン内の FabrikamTools リポジトリを既にチェックアウトしている場合は、その後スクリプトを使用してそのリポジトリを操作できます。

steps:
- checkout: git://FabrikamFiber/FabrikamTools # Azure Repos Git repository in the same organization
- script: # Do something with that repo
# Or you can reference it with a uses statement in the job
uses:
  repositories: # List of referenced repositories
  - FabrikamTools # Repository reference to FabrikamTools
steps:
- script: # Do something with that repo like clone it

注意

多くのシナリオでは、複数のリポジトリのチェックアウトを利用できるため、スクリプトを使用してパイプライン内の追加のリポジトリをチェックアウトする必要はありません。 詳細については、「パイプライン内の複数のリポジトリをチェックアウトする」を参照してください。

チェックアウト

パイプラインがトリガーされると、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.PreferGitFromPath を true に設定します 。 この設定は、Windows 以外のエージェントでは常に true です。

チェックアウト パス

YAML

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

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

クラシック

この設定は、クラシック エディターでは構成できません。 ソース コードは、s という名前のディレクトリにチェックアウトされます。これは、$(Agent.BuildDirectory) に対する相対パスです。 たとえば、$(Agent.BuildDirectory) が C:\agent\_work\1 の場合、ソース コードは C:\agent\_work\1\mycustompath にチェックアウトされます。

サブモジュール

YAML

サブモジュールからファイルをダウンロードする場合は、パイプラインのチェックアウト ステップで 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 コマンドでシークレットを設定します。

注意

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

タグを同期する

重要

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

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

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

YAML

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 で [浅いフェッチ] 設定を表示します。

YAML

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 を実行する。

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

YAML

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

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

クラシック

パイプラインの [ソースの取得] タスクのプロパティから [ソースを同期しない] 設定を選択します。

注意

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

クリーン ビルド

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

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

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

注意

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

YAML

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

clean が true に設定されている場合、ビルド パイプラインでは $(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 リポジトリが初期化されます。

クラシック

パイプラインの [ソースの取得] タスクのプロパティから [クリーン] 設定を選択し、次のいずれかのオプションを選択します。

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

  git clean -ffdx
  git reset --hard HEAD
  

• ソースと出力ディレクトリ: 上記のソース オプションと同じ操作に加えて、$(Build.BinariesDirectory) を削除して再作成します。 $(Build.ArtifactStagingDirectory) と $(Common.TestResultsDirectory) は、これらの設定に関係なく、すべてのビルドの前に常に削除および再作成されることに注意してください。

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

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

ソースのラベル作成

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

YAML

現在、YAML でこの設定を構成することはできませんが、クラシック エディターでは構成できます。 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} を含む成果物が完了したビルドに自動的に追加されます。 これにより、チームの追跡可能性が向上し、ビルドからビルドされたコードに簡単に移動できます。 タグはビルドによって生成されるため、ビルド成果物と見なされます。 ビルドが手動またはアイテム保持ポリシーによって削除されると、タグも削除されます。

よく寄せられる質問

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

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

トリガーの失敗

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

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

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

  

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

  

• リポジトリの YAML ファイルまたはブランチ ポリシーで PR トリガーを構成していますか? Azure Repos Git リポジトリの場合、YAML ファイルで PR トリガーを構成することはできません。 ブランチ ポリシーを使用する必要があります。

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

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

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

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

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

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

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

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

まず、前の質問のトラブルシューティング手順を実行します。 その後、次の追加手順に従います。

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

• プッシュ イベントまたは PR イベントの処理に遅延が発生していますか? これは通常、問題が 1 つのパイプラインだけで発生しているか、またはプロジェクト内のすべてのパイプラインもしくはリポジトリで発生しているかを確認することで、見分けることができます。 いずれかのリポジトリへのプッシュまたは PR 更新でこの現象が発生している場合は、更新イベントの処理に遅延が発生している可能性があります。 ステータス ページでサービスの停止が発生しているかどうかを確認してください。 ステータス ページに問題が表示される場合は、Microsoft のチームが既に作業を開始しているはずです。 この問題に関する最新情報をこまめに確認してください。

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

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

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

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

YAML パイプラインに複数のリポジトリがあります。 各リポジトリにトリガーを設定する方法を教えてください。

複数のリポジトリを使用でトリガーを参照してください。

チェックアウトの失敗

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

remote: TF401019: The Git repository with name or identifier XYZ does not exist or you do not have permissions for the operation you are attempting.
fatal: repository 'XYZ' not found
##[error] Git fetch failed with exit code: 128

次の各手順を実行して、チェックアウトの失敗をトラブルシューティングしてください。

• リポジトリはまだ存在しますか? 最初に、[リポジトリ] ページで開くことを確認します。

• スクリプトを使用してリポジトリにアクセスしていますか? その場合は、[ジョブの承認スコープを参照先の Azure DevOps リポジトリに制限する] 設定をチェックします。 [ジョブの承認スコープを参照先の Azure DevOps リポジトリに制限する] が有効になっている場合、パイプラインで最初に明示的に参照されていない限り、スクリプトを使用して Azure Repos Git リポジトリチェックアウトすることはできません。

• パイプラインのジョブ承認スコープは何ですか?

  • スコープがコレクションの場合:

    • これは断続的なエラーである可能性があります。 パイプラインを再実行します。
    • 誰かがプロジェクト コレクション ビルド サービス アカウントへのアクセスを削除した可能性があります。
      • リポジトリが存在するプロジェクトの [プロジェクトの設定] に移動します。 [リポジトリ]> [リポジトリ] > [特定のリポジトリ] を選択し、[セキュリティ] を選択します。
      • ユーザーの一覧にプロジェクト コレクション ビルド サービス (コレクション名) が存在するかどうかを確認します。
      • そのアカウントに [タグの作成] と [読み取り] アクセス権があるかどうかを確認します。

  • スコープがプロジェクトの場合:

    • リポジトリはパイプラインと同じプロジェクトにありますか?
      • はい:
        • これは断続的なエラーである可能性があります。 パイプラインを再実行します。
        • 誰かがプロジェクト ビルド サービス アカウントへのアクセスを削除した可能性があります。
          • リポジトリが存在するプロジェクトの [プロジェクトの設定] に移動します。 [リポジトリ]> [リポジトリ] > [特定のリポジトリ] を選択し、[セキュリティ] を選択します。
          • ユーザーの一覧にプロジェクト名ビルド サービス (コレクション名) が存在するかどうかを確認します。
          • そのアカウントに [タグの作成] と [読み取り] アクセス権があるかどうかを確認します。
      • いいえ:
        • パイプラインはパブリック プロジェクトに含まれますか?
          • はい: パブリック プロジェクトの外部のリソースにアクセスすることはできません。 プロジェクトを非公開にします。
          • いいえ: 同じプロジェクト コレクション内の別のリポジトリにアクセスするためのアクセス許可を構成する必要があります。

バージョンが正しくない

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

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

関連記事

• スケジュールされたトリガー
• パイプライン完了トリガー