Git リポジトリのパイプライン オプション
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Azure DevOps プロジェクト、GitHub、GitHub Enterprise Server、Bitbucket Cloud、または別の Git リポジトリで、Git リポジトリを使うパイプラインを編集するときは、次のオプションを使用できます。
| 機能 | Azure Pipelines | Azure DevOps Server 2019 以降 | TFS 2018 |
|---|---|---|---|
| [Branch]\(ブランチ) | はい | イエス | はい |
| Clean | はい | イエス | はい |
| タグまたはラベル ソース | プロジェクト (クラシックのみ) | チーム プロジェクト | チーム プロジェクト |
| ビルド状態を報告する | はい | イエス | はい |
| サブモジュールをチェックアウトする | はい | イエス | はい |
| LFS からファイルをチェックアウトする | はい | イエス | はい |
| 第 2 のリポジトリをクローンする | はい | イエス | はい |
| ソースを同期しない | はい | イエス | はい |
| 浅いフェッチ | はい | イエス | はい |
注意
上記のオプションの一部を表示するには、[ソースの取得] タスクで [詳細設定] をクリックします。
[Branch]\(ブランチ)
これは、このビルドを手動でキューに入れるときに既定値にするブランチです。 ビルドにスケジュールされたトリガーを設定する場合、これはビルドが最新のソースを取得するブランチです。 既定のブランチは、継続的インテグレーション (CI) によってビルドがトリガーされるときは何の影響もありません。 通常は、これをリポジトリの既定のブランチと同じに設定します (例: "master")。
エージェントのローカル リポジトリをクリーンする
ビルドの実行前に、セルフホステッド エージェントの作業ディレクトリに対してさまざまな形式のクリーニングを実行できます。
一般に、セルフホステッド エージェントのパフォーマンスを向上させるには、リポジトリをクリーンしないでください。 このケースでは、最適なパフォーマンスを得るために、ビルドに使用するタスクまたはツールのクリーン オプションを無効にして、インクリメンタル ビルドを実行するようにもしてください。
(以前のビルドの残留ファイルによる問題を回避する目的などで) リポジトリをクリーンする必要がある場合は、以下のオプションを使用できます。
注意
Microsoft ホステッド エージェントを使用している場合、新しいエージェントが毎回取得されるため、クリーニングは有効ではありません。 セルフホステッド エージェントを使うと、エージェント プールの構成方法によっては、後続のパイプラインの実行 (または同じパイプラインのステージやジョブ) に新しいエージェントが使われる可能性があります。そのため、クリーンしなくても、後続の実行、ジョブ、ステージが以前の実行、ジョブ、ステージの出力にアクセスできることは保証されません。
注意
セルフホステッド エージェントを使うと、エージェント プールの構成方法によっては、後続のパイプラインの実行 (または同じパイプラインのステージやジョブ) に新しいエージェントが使われる可能性があります。そのため、クリーンしなくても、後続の実行、ジョブ、ステージが以前の実行、ジョブ、ステージの出力にアクセスできることは保証されません。 ビルド成果物を使って、パイプライン実行、ステージ、またはジョブの出力を、後続の実行、ステージ、またはジョブと共有できます。
Azure Pipelines、Azure DevOps Server 2019 以降
YAML パイプラインに使用できるクリーン オプションがいくつかあります。
checkoutステップにはcleanオプションがあります。trueに設定すると、パイプラインはリポジトリをフェッチする前にexecute git clean -ffdx && git reset --hard HEADを実行します。 詳しくは、チェックアウトに関する記事をご覧ください。jobに対するworkspaceの設定には、複数のクリーン オプション (出力、リソース、すべて) があります。 詳しくは、ワークスペースに関する記事をご覧ください。- パイプライン設定 UI には [クリーン] の設定があり、true に設定すると、パイプラインのすべての
checkoutステップでclean: trueを指定するのと同じになります。 クリーン 設定を構成するには:パイプラインを編集し、[...] を選び、[トリガー] を選びます。
[YAML]、[ソースの取得] を選び、任意の [クリーン] 設定を構成します。 既定値は trueです。
![[クリーン] 設定。](../process/media/clean-setting.png?view=azure-devops)
パイプラインを手動で実行するときにクリーン設定をオーバーライドするには、ランタイム パラメーターを使用できます。 次の例では、ランタイム パラメーターを使ってチェックアウトのクリーン設定を構成します。
parameters:
- name: clean
displayName: Checkout clean
type: boolean
default: true
values:
- false
- true
trigger:
- main
pool: FabrikamPool
# vmImage: 'ubuntu-latest'
steps:
- checkout: self
clean: ${{ parameters.clean }}
既定では、clean は true に設定されていますが、ランタイム パラメーターに対して追加された [Checkout clean] チェック ボックスをオフにすることで、パイプラインの手動実行時にオーバーライドできます。
ソースのラベル作成
完成したビルドに含まれる各ファイルのバージョンをチームが簡単に識別できるように、ソース コード ファイルにラベルを付ける必要がある場合があります。 また、すべてのビルドに対してソース コードにラベルを付けるか、成功したビルドにのみラベルを付けるかを指定することもできます。
注意
この機能は、ビルドのソース リポジトリが GitHub リポジトリの場合、またはプロジェクトの Git または TFVC リポジトリである場合にのみ使用できます。
ラベル形式では、"すべて" のスコープを持つユーザー定義および定義済み変数を使用できます。次に例を示します。
$(Build.DefinitionName)_$(Build.DefinitionVersion)_$(Build.BuildId)_$(Build.BuildNumber)_$(My.Variable)
最初の 4 つの変数は定義済みです。 My.Variable は、ユーザーが [変数] タブで定義できます。
ビルド パイプラインは、ソースに Git タグでラベルを付けます。
一部のビルド変数では、有効なラベルではない値が生成される場合があります。 たとえば、$(Build.RequestedFor) や $(Build.DefinitionName) などの変数には空白を含めることができます。 値に空白が含まれている場合、タグは作成されません。
ソースがビルド パイプラインによってタグ付けされると、Git ref refs/tags/{tag} を含む成果物が完了したビルドに自動的に追加されます。 これにより、チームの追跡可能性が向上し、ビルドからビルドされたコードに簡単に移動できます。 タグはビルドによって生成されるため、ビルド成果物と見なされます。 ビルドが手動またはアイテム保持ポリシーによって削除されると、タグも削除されます。
ビルドの状態を報告する (Azure Pipelines、TFS 2018 以降)
リモート ソース リポジトリからビルド状態をチームに表示するオプションがあります。
ソースがプロジェクトの Azure Repos Git リポジトリ内にある場合、このオプションは [コード] ページにビルドが成功か失敗かを示すバッジを表示します。 ビルドの状態は、次のタブに表示されます。
- [ファイル]: 選択されたブランチの最新のビルドの状態を示します。
- [コミット]: 各コミットのビルド状態を示します (ビルドで継続的インテグレーション (CI) トリガーが有効になっている必要があります)。
- [ブランチ]: 各ブランチの最新のビルドの状態を示します。
プロジェクトの同じリポジトリに複数のビルド パイプラインを使用する場合は、1 つ以上のパイプラインでこのオプションを有効にできます。 複数のパイプラインでこのオプションを有効にすると、[コード] ページのバッジは、すべてのパイプラインで最新のビルドの状態を示します。 チーム メンバーは、ビルド状態バッジをクリックして、ビルド パイプラインごとに最新のビルド状態を見ることができます。
GitHub
ソースが GitHub にある場合、このオプションは、GitHub の Checks または Status API を使って、ビルドの状態を GitHub に公開します。 ビルドが GitHub の pull request からトリガーされた場合は、GitHub の pull request ページで状態を見ることができます。 これにより、GitHub 内で状態ポリシーを設定したり、マージを自動化したりすることもできます。 ビルドが継続的インテグレーション (CI) によってトリガーされる場合は、GitHub のコミットまたはブランチでのビルド状態を見ることができます。
その他の種類の Git リモート リポジトリ
ソースが他の種類のリモート リポジトリにある場合は、Azure Pipelines または TFS を使ってそのリポジトリにビルド状態を自動的に公開することはできません。 ただし、バージョン管理エクスペリエンス内のビルド状態を統合して表示する方法として、ビルド バッジを使用できます。
チェックアウト パス
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)。
複数の checkout ステップを使って、複数のリポジトリをチェックアウトしている場合に、path を使ってフォルダーを明示的に指定したいときは、別のチェックアウト ステップのパスのサブフォルダーになるようなパスの設定は避けることを検討してください (つまり、C:\agent\_work\1\s\repo1 と C:\agent\_work\1\s\repo1\repo2)。そうしないと、チェックアウト ステップのサブフォルダーは、別のリポジトリのクリーニングによってクリアされます。 repo1 のクリーン オプションが true の場合、このケースは有効であることに注意してください。
チェックアウト サブモジュール
サブモジュールからファイルをダウンロードしたい場合に選択します。 すぐ下のサブモジュールだけ取得するか、再帰的に任意の深さまで入れ子になったすべてのサブモジュールを取得するかを選ぶことができます。 サブモジュールで LFS を使う場合は、サブモジュールでの LFS の使用に関する注意を確認してください。
注意
サブモジュールをチェックアウトするための YAML 構文について詳しくは、YAML スキーマでのチェックアウトに関する記事をご覧ください。
ビルド パイプラインは、次の場合に限り、Git サブモジュールをチェックアウトします。
未認証: クローンまたはフェッチに必要な資格情報を持たない、認証されていないパブリック リポジトリ。
認証済み:
上で指定されている Git リポジトリと同じプロジェクト、GitHub 組織、または Bitbucket Cloud アカウントに含まれています。
メイン リポジトリに対する相対 URL を使用して追加されました。 たとえば、これはチェックアウトされます:
git submodule add /../../submodule.git mymoduleこれはチェックアウトされません:git submodule add https://dev.azure.com/fabrikamfiber/_git/ConsoleApp mymodule
認証済みサブモジュール
注意
HTTPS を使ってサブモジュールを登録しており、SSH を使っていないことを確認してください。
メイン リポジトリからソースを取得するためにエージェントによって使用されるのと同じ資格情報を使用して、サブモジュールのソースを取得することもできます。
メイン リポジトリとサブモジュールが Azure DevOps プロジェクトの Azure Repos Git リポジトリにある場合は、ソースへのアクセスに使われるアカウントを選択できます。 [オプション] タブの [ビルド ジョブの承認スコープ] メニューで、次のいずれかを選びます。
[プロジェクト コレクション]: プロジェクト コレクション ビルド サービス アカウントを使う場合
[現在のプロジェクト]: プロジェクト ビルド サービス アカウントを使う場合。
使うアカウントが、メイン リポジトリとサブモジュールの両方にアクセスできることを確認します。
メイン リポジトリとサブモジュールが同じ GitHub 組織にある場合は、GitHub サービス接続に格納されているトークンを使ってソースにアクセスします。
[サブモジュールをチェックアウト] オプションの代わりに使う方法
[サブモジュールをチェックアウト] オプションを使用できない場合があります。 サブモジュールにアクセスするために別の資格情報のセットが必要な場合があります。 これは、たとえば、メイン リポジトリとサブモジュール リポジトリが同じ Azure DevOps 組織または Git サービスに格納されていない場合に発生する可能性があります。
[サブモジュールをチェックアウト] オプションを使用できない場合は、代わりにカスタム スクリプト ステップを使用してサブモジュールをフェッチできます。
まず、個人用アクセス トークン (PAT) を取得し、pat: のプレフィックスを付けます。
次に、このプレフィックス付き文字列を base64 でエンコードして、基本認証トークンを作成します。
最後に、次のスクリプトをパイプラインに追加します。
git -c http.https://<url of submodule repository>.extraheader="AUTHORIZATION: basic <BASE64_ENCODED_TOKEN_DESCRIBED_ABOVE>" submodule update --init --recursive
"<BASIC_AUTH_TOKEN>" は、必ず Base64 でエンコードされたトークンに置き換えてください。
プロジェクトまたはビルド パイプラインでシークレット変数を使用して、生成した基本認証トークンを格納します。 その変数を使用して、上記の Git コマンドでシークレットを設定します。
Note
Q: エージェントで Git 資格情報マネージャーを使用できないのはなぜですか? A: プライベート ビルド エージェントにインストールされている Git 資格情報マネージャーにサブモジュールの資格情報を格納することは、通常は有効ではありません。これは、サブモジュールが更新されるたびに資格情報を再入力するように資格情報マネージャーから求められる場合があるためです。 これは、ユーザーが操作できない自動ビルドの間は望ましくありません。
LFS からファイルをチェックアウトする
大きなファイル ストレージ (LFS) からファイルをダウンロードする場合に選択します。
クラシック エディターでは、チェック ボックスをオンにして、このオプションを有効にします。
YAML ビルドでは、lfs が true に設定されたチェックアウト ステップを追加します。
steps:
- checkout: self
lfs: true
TFS を使っている場合、またはセルフホステッド エージェントで Azure Pipelines を使っている場合に、このオプションを機能させるには、エージェントに git-lfs をインストールする必要があります。 ホステッド エージェントで Windows を使用する場合は、System.PreferGitFromPath 変数を使って、マシンにインストールした git と git-lfs のバージョンがパイプラインで確実に使われるようにすることを検討します。 詳しくは、「エージェントで実行される Git のバージョンは何ですか?」をご覧ください。
サブモジュールで Git LFS を使用する
サブモジュールに LFS ファイルが含まれる場合は、サブモジュールをチェックアウトする前に、Git LFS を構成する必要があります。 Microsoft ホステッドの macOS と Linux のエージェントは、この方法で事前に構成されます。 Windows エージェントとセルフホステッドの macOS と Linux のエージェントは、そうでない場合があります。
回避策として、YAML を使っている場合は、checkout の前に次のステップを追加できます。
steps:
- script: |
git config --global --add filter.lfs.required true
git config --global --add filter.lfs.smudge "git-lfs smudge -- %%f"
git config --global --add filter.lfs.process "git-lfs filter-process"
git config --global --add filter.lfs.clean "git-lfs clean -- %%f"
displayName: Configure LFS for use with submodules
- checkout: self
lfs: true
submodules: true
# ... rest of steps ...
第 2 のリポジトリをクローンする
既定では、パイプラインは、Azure Repos または外部プロバイダーの 1 つのリポジトリに関連付けられます。 これは、コミットと pull request でビルドをトリガーできるリポジトリです。
パイプラインに 2 つ目のリポジトリからのソースを含めたいことがあります。 これは、スクリプトを書くことで実現できます。
git clone https://github.com/Microsoft/TypeScript.git
リポジトリがパブリックでない場合は、Git コマンドに認証を渡す必要があります。
Azure Repos
パイプラインは既にプロジェクト内の他のリポジトリにアクセスでき、次の例に示すようにスクリプト コマンドを使って、それらをパイプラインでクローンできます。
- script: |
git clone -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" https://organization@dev.azure.com/project/FabrikamFiber/_git/reponame
複数リポジトリのチェックアウトを使って、パイプラインと同じプロジェクトで複数のリポジトリをクローンできます。
パブリックではない別のプロジェクトからリポジトリをクローンする必要がある場合は、そのプロジェクトにアクセスできるユーザーとして認証を行う必要があります。
注意
資格情報を安全に格納するには、シークレット変数を使います。
シークレット変数を環境変数としてスクリプトで自動的に使うことはできません。 それらをマップする方法については、シークレット変数に関する記事をご覧ください。
Azure Repos の場合は、コード (読み取り) アクセス許可で個人用アクセス トークンを使用できます。
これを、ユーザー名を含めずに "基本" 承認ヘッダーのパスワード フィールドとして送信します。
(つまり、コロンを含む :<PAT> の値を base64 でエンコードします)。
AUTH=$(echo -n ":$REPO_PAT" | openssl base64 | tr -d '\n')
git -c http.<repo URL>.extraheader="AUTHORIZATION: basic $AUTH" clone <repo URL> --no-checkout --branch master
ソースを同期しない
デプロイ以外のジョブは、ソースを自動的にフェッチします。 その動作をスキップする場合は、このオプションを使います。 このオプションは、次の場合に役立ちます。
独自のカスタム オプションを使って、git init、config、fetch を実行します。
ビルド パイプラインを使って、バージョン コントロールのコードに依存しない自動化 (一部のスクリプトなど) を実行します。
ソースのダウンロードを無効にする場合:
- Azure Pipelines、TFS 2018 以降:[詳細設定] をクリックして、[ソースを同期しない] を選びます。
注意
このオプションを使うと、エージェントはリポジトリをクリーンする Git コマンドの実行もスキップします。
浅いフェッチ
ダウンロードのために履歴を遡る範囲を制限したい場合に選びます。 実質的に、この結果は git fetch --depth=n になります。 リポジトリが大きい場合、このオプションを使用すると、ビルド パイプラインの効率が高まる可能性があります。 リポジトリが長い間使用されており、サイズの大きい履歴がある場合は、リポジトリが大きくなる可能性があります。 また、大きなファイルを追加して後で削除した場合も大きくなる可能性があります。
このような場合、このオプションは、ネットワークおよびストレージ リソースを節約するのに役立ちます。 また、時間を節約することもできます。 時間が常に節約されるとは限らない理由は、場合によっては、指定した深さのためにダウンロードするコミットの計算にサーバーが時間を費やす必要がある可能性があるためです。
注意
ビルドがキューに入れられると、ビルドするブランチはコミット IDに解決されます。 次に、エージェントがブランチをフェッチし、目的のコミットをチェックアウトします。 ブランチがコミット ID に解決されてから、エージェントがチェックアウトを実行するまで少し時間がかかります。 ブランチがすばやく更新され、浅いフェッチに非常に小さな値を設定した場合、エージェントがチェックアウトしようとしたときにコミットが存在しない可能性があります。その場合は、浅いフェッチの深さの設定を増やします。
チェック ボックスをオンにしてこのオプションを有効にした後、[深さ] ボックスでコミットの数を指定します。
ヒント
以下で説明する Agent.Source.Git.ShallowFetchDepth 変数も機能し、チェック ボックスの制御をオーバーライドします。 これにより、ビルドをキューに入れるときに設定を変更できます。
パスからの Git を優先する
既定では、エージェント ソフトウェアにバンドルされている Git のバージョンが Windows エージェントで使われます。 Microsoft は、エージェントにバンドルされている Git のバージョンを使うことをお勧めしますが、この既定の動作をオーバーライドし、エージェント コンピューターのパスにインストールされている Git のバージョンを使うためのオプションがいくつかあります。
- パイプラインで
System.PreferGitFromPathという名前のパイプライン変数をtrueに設定します。 - セルフホステッド エージェントでは、エージェントのルート ディレクトリに .env という名前のファイルを作成し、そのファイルに
System.PreferGitFromPath=trueという行を追加できます。 詳しくは、「エージェントごとに異なる環境変数を設定するにはどうすればよいですか?」をご覧ください。
パイプラインで使われている Git のバージョンは、次の例で示すように、パイプラインのログの checkout ステップで確認できます。
Syncing repository: PathFilter (Git)
Prepending Path environment variable with directory containing 'git.exe'.
git version
git version 2.26.2.windows.1
この設定は、Windows 以外のエージェントでは常に true です。
その他の Git のトリガー オプション
他の外部 Git リポジトリが指定されている場合、CI ビルドでは、リポジトリにインターネットからアクセスできる必要があります。 リポジトリがファイアウォールまたはプロキシの内側にある場合は、スケジュールされたビルドと手動ビルドのみが機能します。
よく寄せられる質問
ビルド エージェントが Git で使用できるプロトコルは何ですか?
エージェントは HTTPS をサポートしています。
SSH は、エージェントではまだサポートされていません。 「「Git サブモジュールのチェックアウト中にビルドで SSH 認証を使用できるようにする」をご覧ください。
TFS をオンプレミスで使用していますが、これらの機能の一部が表示されません。 なぜでしょうか。
これらの機能の一部は Azure Pipelines でのみ使用でき、オンプレミスではまだ使用できません。 TFS の最新バージョンにアップグレードした場合は、一部の機能をオンプレミスで使用できます。