しばやん雑記

Azure とメイドさんが大好きなフリーランスのプログラマーのブログ

Azure Pipelines のディレクトリを指す変数はどれを使うべきなのか調べた

Azure DevOps

Azure Pipelines を使っていて地味に悩むのがディレクトリの扱いです。一般的な CI SaaS だとソースがチェックアウトされたディレクトリを基準に、ビルドなり発行を行っていきますが、Azure Pipelines はディレクトリが複数用意されています。

Predefined variables に一通りまとまっていますが、実体は同じディレクトリを指しているのに別名で用意されている変数が多いので、タスクのリファレンスを読むだけでは混乱します。

そろそろちゃんと理解しておこうと思ったので、各 VM Image での値を確認してどの変数を使うのがベストなのか調べました。将来的にパスは変わる可能性がありますが、変数名は変わらないはずです。

重要な定義済み変数

以下の 4 つだけ覚えておけば、大体困らないでしょう。ドキュメントにあるデフォルト値は無視して、相対パスの扱いにだけ気を付ければスムーズに扱えるようになります。

  • Build.SourcesDirectory
    • ソースコードがチェックアウトされたディレクトリ
    • Pipeline Artifacts へ Publish する際の基準となるディレクトリでもある
  • Build.ArtifactStagingDirectory / Build.StagingDirectory
    • ビルド成果物を置いておくのに向いているディレクトリ
    • 向いているだけで、自動での Publish はされないので注意。使わなくても問題ない
  • Pipeline.Workspace
    • Pipeline Artifacts をダウンロードする際の基準となるディレクトリ

変数は Build と Pipeline から始まるものを使うように統一すると混乱しないので良いです。

たまにドキュメントなどで見る Build.BinariesDirectory は形骸化したディレクトリという印象です。これから使う必要性は特に感じませんでした。

変数の読み替え表

Azure Pipelines のドキュメントでは System から始まる変数をよく使っていますが、タスクによってバラバラだったりするので、同じ値を指す変数に置き換えた方が良いです。

  • Agent.BuildDirectory
    • → Pipeline.Workspace
  • Build.RepositoryLocalPath
  • System.DefaultWorkingDirectory
    • → Build.SourcesDirectory
  • System.ArtifactsDirectory
    • → Build.ArtifactStagingDirectory / Build.StagingDirectory

特に System.DefaultWorkingDirectory は至る所に出てきますが、実体はソースがチェックアウトされたディレクトリなので、分かりやすい名前の変数にしておいた方が理解が楽です。

この中だと System.ArtifactsDirectory と Build.ArtifactStagingDirectory が同じというのが罪深いと思います。変数名からは全く別物のように取れるので最悪ですね。

使わないと思いますが Agent.RootDirectory / Agent.WorkFolder / System.WorkFolder は同じ値です。

各 VM Image での変数例

Windows (windows-2019)

AGENT_BUILDDIRECTORY           d:\a\1
AGENT_HOMEDIRECTORY            C:\agents\2.155.1
AGENT_ROOTDIRECTORY            d:\a
AGENT_TEMPDIRECTORY            d:\a\_temp
AGENT_WORKFOLDER               d:\a

BUILD_ARTIFACTSTAGINGDIRECTORY d:\a\1\a
BUILD_BINARIESDIRECTORY        d:\a\1\b
BUILD_REPOSITORY_LOCALPATH     d:\a\1\s
BUILD_SOURCESDIRECTORY         d:\a\1\s
BUILD_STAGINGDIRECTORY         d:\a\1\a

COMMON_TESTRESULTSDIRECTORY    d:\a\1\TestResults

PIPELINE_WORKSPACE             d:\a\1

SYSTEM_ARTIFACTSDIRECTORY      d:\a\1\a
SYSTEM_DEFAULTWORKINGDIRECTORY d:\a\1\s
SYSTEM_WORKFOLDER              d:\a

Linux (ubuntu-16.04)

AGENT_BUILDDIRECTORY           /home/vsts/work/1
AGENT_HOMEDIRECTORY            /home/vsts/agents/2.155.1
AGENT_ROOTDIRECTORY            /home/vsts/work
AGENT_TEMPDIRECTORY            /home/vsts/work/_temp
AGENT_WORKFOLDER               /home/vsts/work

BUILD_ARTIFACTSTAGINGDIRECTORY /home/vsts/work/1/a
BUILD_BINARIESDIRECTORY        /home/vsts/work/1/b
BUILD_REPOSITORY_LOCALPATH     /home/vsts/work/1/s
BUILD_SOURCESDIRECTORY         /home/vsts/work/1/s
BUILD_STAGINGDIRECTORY         /home/vsts/work/1/a

COMMON_TESTRESULTSDIRECTORY    /home/vsts/work/1/TestResults

PIPELINE_WORKSPACE             /home/vsts/work/1

SYSTEM_ARTIFACTSDIRECTORY      /home/vsts/work/1/a
SYSTEM_DEFAULTWORKINGDIRECTORY /home/vsts/work/1/s
SYSTEM_WORKFOLDER              /home/vsts/work

macOS (macos-10.14)

AGENT_BUILDDIRECTORY           /Users/vsts/agent/2.155.1/work/1
AGENT_HOMEDIRECTORY            /Users/vsts/agent/2.155.1
AGENT_ROOTDIRECTORY            /Users/vsts/agent/2.155.1/work
AGENT_TEMPDIRECTORY            /Users/vsts/agent/2.155.1/work/_temp
AGENT_WORKFOLDER               /Users/vsts/agent/2.155.1/work

BUILD_ARTIFACTSTAGINGDIRECTORY /Users/vsts/agent/2.155.1/work/1/a
BUILD_BINARIESDIRECTORY        /Users/vsts/agent/2.155.1/work/1/b
BUILD_REPOSITORY_LOCALPATH     /Users/vsts/agent/2.155.1/work/1/s
BUILD_SOURCESDIRECTORY         /Users/vsts/agent/2.155.1/work/1/s
BUILD_STAGINGDIRECTORY         /Users/vsts/agent/2.155.1/work/1/a

COMMON_TESTRESULTSDIRECTORY    /Users/vsts/agent/2.155.1/work/1/TestResults

PIPELINE_WORKSPACE             /Users/vsts/agent/2.155.1/work/1

SYSTEM_ARTIFACTSDIRECTORY      /Users/vsts/agent/2.155.1/work/1/a
SYSTEM_DEFAULTWORKINGDIRECTORY /Users/vsts/agent/2.155.1/work/1/s
SYSTEM_WORKFOLDER              /Users/vsts/agent/2.155.1/work

環境によって、上の値は変わる可能性があります。今後のアップデートで変わることもあります。