Azure DevOps で UE5 プロジェクトを自動ビルド化してみる

はじめに

Azure DevOps を使用して Unreal Engine 5 (以下UE5) のプロジェクトのビルドを自動化してみようと思います。
内容は大きく分けると以下のようになります。

• Azure DevOps とは？
• 自動ビルドを行う端末をセットアップする
• Azure DevOps Pipelines でビルドを自動化する

事前準備

以下の内容については事前に準備していただいている前提で進めたいと思います。

1. 自動化に使用するビルドマシンの用意
   • Windows 10
   • Visual Studio or VS Code
   • UE4 もしくは UE5
2. Azure DevOps のアカウント
3. UE プロジェクト
   • UE4 または UE5 でビルドが通る前提のプログラム

※今回は Self-hosted という環境で自動ビルド環境を構築しますのでビルドマシンが必要となります。

Azure DevOps とは？

Azure DevOps とはマイクロソフトが提供する開発者向けのクラウドサービスです。
CI/CD の一連の流れを全て、一つのサービスとして統合されています。

Azure DevOps で使用可能なサービス一覧

• Boards (タスク)
• Repos (ソースコード管理)
• Pipelines (自動化)
• Test Plans (テスト)
• Artifacts (成果物)

CI/CD 環境の比較

サービス名	クラウド	費用	複雑さ	メンテナンス性	サービス詳細
Azure DevOps	◯	◯	△ (※1)	◯	タスク (Boards) ソースコード (Repose) 自動化 (Pipelines) テスト (Test Plans) 成果物 (Artifacts)
GitHub	◯	△ (※2)	◯	◯	ソースコード (Code) 課題 (Issues) 自動化 (Actions) 成果物 (Actions) テスト (Actions)
AWS CodePipeline	◯	？ (※3)	△ (※4)	◯	ソースコード (CodeCommit) 自動化 (CodeBuild) テスト (CodeBuild) 成果物 (CodeBuild/CodeDeploy)
Jenkins	△ (※5)	-	◯	✕ (※6)	自動化のみ

※1：設定項目が詳細に設定出来る反面、複雑さが出ている。
※2：無料枠が Azure DevOps に比べて低い・少ない。
※3：実際に調べたり触っていないため不明です。
※4：統合環境があるわけではなく、複数のサービスを自前で統合する必要がある。
※5：VM などを使用することでクラウドに設置することは可能だが、自前でホストする必要がある。
※6：オンプレでホストする場合、ハードウェア側のメンテナンスが含まれる。また、基本的には GUI による設定のみ。

Repos (ソースコード管理)

Azure DevOps の Repos は標準では Git

自動ビルドを行う端末をセットアップする

Azure DevOps ではプロジェクト単位で管理されます。
一つのプロジェクトに Repos や Pipelines のサービスが含まれています。
そのため Azure DevOps でははじめにプロジェクトを作成することから始めます。

プロジェクトの作成

Azure DevOps のアカウント画面の右上にある『New project』をクリックしてプロジェクトの作成の設定画面に移ります。

プロジェクトの設定画面では以下の設定が可能です。

設定名	説明
Project name	プロジェクトの名前
Description	プロジェクトの説明
Visibility	公開範囲。 Public: インターネット上に公開されます。一部の機能は制限されます。 Private: アクセス権を与えた人だけに公開されます。
Version control	バージョン管理に使用するアプリケーション。 Git または Team Foundatoin Version Control
Work item process	作業に使用するワークアイテムプロセスの種類。 Basic/Agile/Scrum/CMMI

※Work item process については今回は説明しませんのでデフォルトの Basic で問題ありません。

今回は以下の設定にしております。

• Project name：UE
• Description：Azure DevOps で UE5 プロジェクトを自動ビルド化してみる
• Visibility：Private
• Version control：Git
• Work item process：Basic

作成が完了すると以下のような画面になると思います。

サイドバーでは Overview が選択されおり、プロジェクトの概要が表示されていると思います。

リポジトリの初期化

次にサイドバーから Repos を選択すると以下のような画面になります。

この状態では Repos には何もコミットされていない状態ですので初期化を行います。
画面下部にある『Initialize main branch with a README or gitignore』で README.md と .gitignore をコミットするかの選択が出来ますので、今回は『Add a README』にチェックを入れ、『Add a .gitignore: None』のプルダウンから『Unreal Engine』を選択し『Initialize』をクリックします。

処理が完了すると README.md と .gitignore がコミットされた状態で main ブランチが初期化されます。

これでリポジトリが使える状態になりました。

ビルドを実行する環境構築

ビルドを実行する環境を構築する上で以下の手順が必要となります。

• ホスト環境の用意 (ビルドするハードウェア)
• Personal Access Tokens (PAT) の取得
• エージェントの登録 (ビルドマシンを認識させる)

ホスト環境の種類

ビルドを実行するホスト環境は大きく分けて二種類あります。

• Microsoft-hosted
• Self-hosted

それぞれの機能や比較はこの後に記載しますが、今回は Self-hosted 環境で構築します。

機能

	Microsoft-hosted	Self-hosted
ハードウェアの提供	Microsoft	自前
ハードウェアのメンテナンス	Microsoft	自前
ハードウェアのスペック	固定	自由
ソフトウェア	スクリプトでインストールなどのセットアップが必要	予めインストールしておくなどが可能

比較

	Microsoft-hosted	Self-hosted
メリット	ビルドを実行するハードウェアは Microsoft が予め用意しているものを利用するため、自前でハードウェアを用意しなくてもよいため、購入費用や管理コストが下がる。常にクリーンな環境でビルドする事が出来るため環境依存の設定などを把握しやすい。	ビルドを実行するハードウェアを自前で用意するため、好きなソフトウェアや設定などを予めセットアップしておくことが可能ため、セットアップ時間の短縮が出来る。
デメリット	ビルドを実行するハードウェアが用意されているものを利用するため、必要なソフトウェアなどのセットアップをスクリプトで行う必要がある。予め用意されているハードウェアのスペックが固定ため、より早くビルドを回したいなどの融通がきかない。	自前でハードウェアを用意する必要があるため、そのハードウェアの管理・メンテナンスを行う必要がある。

Microsoft-hosted はハードウェアを用意しなくても良いのでメンテナンスなどの手間が少なくて良いのですが、スペックの融通が利かないやセットアップの手間などがあります。

Personal Access Tokens (PAT) の取得

Personal Access Tokens (PAT) とは Azure DevOps へのアクセスを行う際に必要なトークンです。
トークンはユーザーごとに生成しますので、プロジェクト管理者などのアカウントで発行するのが良いです。

トークンの種類

トークンには一つのトークンで様々なアクセス権を付加することが可能です。

例えば…

• ソースコード管理 (Repos) の閲覧のみが可能なトークン
• タスク管理 (Boards) の読み書きが可能なトークン
• 全権限があるトークン

などがあります。

今回の Self-hosted ではエージェント登録に必要なアクセス権である『Agent Pools』という権限を付与したトークンを生成します。

PAT の生成方法

トークン生成には Azure DevOps の管理画面の右上にあるアカウントアイコンを選択し『Personal access tokens』をクリックします。

画面が遷移すると以下のような画面になると思います。

画面左上にある『New Token』を選択することで『Create a new personal access token』というウィンドウが開きますので、必要項目を入力してトークンを生成します。

トークン生成で必要な権限は前述しましたが『Agent Pools』の権限なのですが、デフォルトでは表示されていません。
画面下部に『Show all scopes』を選択することで『Agent Pools』の項目が表示されます。

今回の設定は以下となります。

設定項目	設定値
Name	UE_Build_Agent
Organization	デフォルトで設定されている値
Expiration (UTC)	30days
Scopes	Custom defined
Agent Pools	Read & manage

Name はトークン一覧で表示されるもので、何に使用しているトークンか分かりやすい名前を付けるのが良いと思います。

上記の設定が完了したら『Create』でトークンが生成されます。

このウィンドウにも表示されていますが、このトークンは同じ値のものは作成や保存はされません。
紛失した分からなくなった場合は再生成が必要になりますので、一時的にどこかにコピーしておくのが良いです。

エージェントの登録

Azure DevOps ではホスト環境の事を『エージェント』と呼び、Self-hosted 環境のビルドマシンを自動ビルドが行えるホスト環境としてエージェント登録を行います。

エージェントプールの作成

エージェントはエージェントプールというグループで管理されます。
エージェント単体では使用することはなく、エージェントプールにエージェント登録をすることで自動ビルドの対象として扱われますので、そのエージェントプールを作成します。
エージェントプールは組織ごとやプロジェクトごとに分けて使用するなどが良いです。

プロジェクト管理画面の左下にある『Project settings』を選択します。

この画面ではプロジェクトの設定を行いますが、今回はサイドバーにある『Agent pools』を選択します。

そうするとデフォルトでは『Azure Pipelines』と書かれた『Azure Pipelines』や『Default』が存在しているかもしれません。
デフォルトのエージェントプールは無視して、新しくエージェントプールを作成しますので『Add Pool』を選択します。

ウィンドウが立ち上がりエージェントプールの種類が選択できると思いますが、今回は『Self-hosted』を選択してください。

そうすると選択項目が新しく表示されます。

今回の設定は以下となります。

設定項目	設定値
Pool type	Self-hosted
Name	UE_Build_Agent
Description	空欄
Grant access permission to all pipelines	true

社内で使うだけであれば全てのパイプラインに対してアクセス権限を付与するで良いかと思いますが、細かくアクセス制御をしたい場合はチェックボックスは適時変更してください。

エージェントプールが作成されると先程入力した『UE_Build_Agent』と言うエージェントプールが一覧に表示されます。

エージェントをエージェントプールに登録

エージェントプールが作成できましたので、次はエージェントプールにエージェントを登録します。
先程作成した『UE_Build_Agent』を選択すると登録されているエージェント管理画面が表示されますので、上部のタブから『Agents』を選択してエージェント一覧を表示します。

そこではまだエージェントが登録されていませんので『Add your first agent』と表示されており、『New agent』が選択できる状態ですので選択をしてください。

以下のウィンドウが表示されますので『Download』を選択します。

これはビルドマシンをエージェントとして動作させるためのエージェントプログラムです。
ダウンロードが終われば、次は PowerShell を起動します。

※PowerShell 起動の際には管理者権限を持っているユーザーで起動してください。

ここからはコマンドラインによるセットアップですが基本的には上記の画像にある通りに進めるだけでセットアップは完了します。

PowerShell ではエージェントをインストールしたいドライブに移動します。
今回はデータディスクとして F: を使用しておりますので F: で進めますが C: ドライブでも各自の好きな環境で実行していただいて問題ありません。

PS C:\> mkdir agent ; cd agent

と表示されていますが、作業ディレクトリのルートに移動する必要があります。
今回は以下のような作業ディレクトリで設定します。

F:\DevOps\agent

エージェントプログラムは上記のディレクトリに展開されます。

PS F:\> mkdir DevOps ; cd DevOps
PS F:\DevOps> mkdir agent ; cd agent

次に先程ダウンロードしたエージェントプログラムを展開します。
とは言え、表示されている内容をそのままコピペするだけで構いません。

PS F:\DevOps\agent> Add-Type -AssemblyName System.IO.Compression.FileSystem ; [System.IO.Compression.ZipFile]::ExtractToDirectory("$HOME\Downloads\vsts-agent-win-x64-2.204.0.zip", "$PWD")

しばらく待つとファイルが展開されますので次の指示を実行します。

PS F:\DevOps\agent> .\config.cmd

そうすると設定プログラムが起動します。

ここでは必要項目を入力します。

今回の設定は以下となります。

設定項目	設定値
Enter server URL	https://dev.azure.com/[Organization]
Enter authentication type	PAT (そのままエンターで空行)
Enter agent pool	UE_Build_Agent
Enter agent name	端末名 (そのままエンターで空行)
Enter work folder	_work (そのままエンターで空行)
Enter run agent as service? (Y/N)	Y
Enter User account to use for the service	そのままエンターで空行
Enter whether to prevent service starting immediately after configuration is finished?	N (そのままエンターで空行)

今回は Windows のサービスとして自動実行を有効にしています。
サービスとして実行しない設定にした場合、自前で .\run.cmd を実行する必要があります。

無事に起動すると先程のエージェント一覧画面では以下のようになっています。

設定直後は『Online』と表示されている箇所が『Offline』の可能性もありますが、しばらく経つと『Online』に切り替わります。
もし、切り替わらない場合はビルドマシンを再起動してみてください。

以上で自動ビルドを行う端末をセットアップするが完了です。

Azure DevOps Pipelines でビルドを自動化する

では、次は UE プロジェクトをリポジトリにインポートしたいと思います。

Repos からクローン

Repos からのクローンはサイドバーから『Repos』を選択するとデフォルトブランチの main が選択されていますので、右上の『Clone』から URL を取得します。

Clone Repository ウィンドウが開きますので、URL をコピーするかクローンする IDE を選択することが出来ます。
今回は『Visual Studio』を選択します。

インストール済みの Visual Studio でクローンの画面が表示されます。
以下のような認証画面が開く場合があるかもしれませんが、必要な認証を行います。

無事にクローンが出来ました。

UE プロジェクトをインポートします。
インポートの方法はディレクトリ配下にあるファイルやディレクトリ一式をコピーするだけです。
Azure DevOps 側の Repos で UE プロジェクトが正常にインポートされていることが確認できます。

自動化を試してみる

Azure DevOps の自動化のロジックは YAML ファイルによって記述します。
この YAML ファイルはプロジェクトを同じディレクトリに配置 (ルートディレクトリ) し、必要な処理を書いていくことになります。
まずは簡単な自動化をしてみたいと思います。

YAML ファイルを追加する

Visual Studio のソリューションエクスプローラー上で新しく『azure-pipelines.yml』を追加します。

作成した YAML ファイルを開いてまずは以下の内容を記載してください。

trigger:
- main
pool: 'UE_Build_Agent'
jobs:
  - job: UE

    steps:
    - checkout: self
      clean: true

上記のファイルを保存し、ファイルをコミット＆プッシュします。

YAML ファイルを Pipelines で実行させる

次は Azure DevOps の Pipelines を開きます。
サイドバーから『Pipelines』を選択すると以下のような画面になりますので、中央にある『Create Pipeline』をクリックします。

以下のような画面が表示されますので、今回は一番上の『Azure Repos Git』を選択します。
画像からも分かる通り、Azure Repos Git 以外でもソースコード管理では利用することが可能です。

次はリポジトリ選択です。
一つしか作成していませんので『UE』を選択します。

そうすると次の画面では自動的に先程コミットした『azure-pipelines.yml』が表示されます。
画面の右上にあるボタン『Run』を実行すると自動化のプログラムを手動で動かすことが出来ます。

実行すると以下のような画面になります。

ただ、この画面では下の方で『Azure DevOps for UE』の左側に青色時計が表示されているはずです。
これはパイプラインが待機状態となっています。
画面更新すると以下のような画面になると思います。

この状態はパイプラインのパーミッションの設定が出来ていない状態ですので右側にある『View』ボタンをクリックして設定を行います。

『Waiting for review』というウィンドウが開くと思いますが、これは事前に設定しているエージェントプールをこのパイプラインで使用してもよいかの確認待ち状態になっていますので『Permit』をクリックして許可します。

と表示された後、先程は青色時計だった部分が緑のチェックに変わっていると思います。

これで自動化のための事前設定が完了している状態です。

パイプラインの中身の説明をしていませんでしたので説明をしたいと思います。
今回の内容は簡単に言うと『リポジトリにコミットされるとチェックアウトする』だけのパイプラインです。

# Repos の main ブランチにファイルがコミットされた時にトリガーする
trigger:
- main

# パイプラインを走らせるエージェントプールは『UE_Build_Agent』を利用する
pool: 'UE_Build_Agent'

# ジョブを定義しジョブの名前は『Auzre DevOps for UE』とする
jobs:
  - job: 'UE'
    displayName: 'Azure DevOps for UE'

    # ジョブのステップ
    steps:
    # 自分自身のリポジトリからチェックアウトする
    - checkout: self
      clean: true

pool の name にはエージェントプール名を指定しています。
jobs には複数のジョブのグループを記述しますが、今回は一つのジョブで全てが完了するため一つのジョブを記載します。
job に名前をつけますが、

UE のビルド

では、ここから UE によるビルドを行いたいと思います。

AutomationTool

UE のビルドは AutonationTool を利用します。

AutomationTool は以下のフォルダに配置されています。

<UE Path>\Engine\Build\BatchFiles\

<UE Path> は各自のインストールしたディレクトリやドライブによって変わります。

AutomationTool を YAML で記述する

それでは AutomationTool を YAML で呼び出すコードを追加した内容を記述します。

trigger:
- main
pool: 'UE_Build_Agent'
jobs:
  - job: UE
    displayName: 'Azure DevOps for UE'

    steps:
    - checkout: self
      clean: true

    # 以下、追記したコード
    - script: |
        "E:\Epic Games\UE_5.0\Engine\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="$(Build.SourcesDirectory)\UE.uproject" -platform=Win64 -clientconfig=Development -noP4 -cook -allmap -build -pak -partialgc -stage -staginddirectory="$(Build.BinariesDirectory)" -archive archivedirectory="$(Build.ArtifactStagingDirectory"

上記が AutomationTool を呼び出すコードです。
はい、ものすごく長いコマンドですね…。

では、この状態でとりあえずコミットします。
そうすると Pipelines がコミットをトリガーにして走り出していると思いますが、今回は AutomationTool の起動が確認できると思います。
CmdLine というのが追加されていると思いますが、こちらが AutomationTool が走っている状態です。

環境変数を設定する

前章では AutomationTool を使うコードを書きましたが、パスを直書きしていましたので、環境によって変わるパスなどに対応できませんでしたので、その部分を環境変数に置き換えたいと思います。

Azure DevOps では端末に割り当てられている環境変数とは別に Pipelines 内でのみ有効な環境変数を variables で定義することが可能です。
環境変数を使用する理由は…

• 同じパラメーターを変数にすることで使いまわしが出来るようにする
• ハードウェアごとに違う設定を吸収する（パスなど）

が上げられます。

それではコードを以下のように書き換えてください。

trigger:
- main
variables:
  PROJECT_NAME: UE
  TARGET: Win64
  CONFIGURATION: Development
pool: 'UE_Build_Agent'
jobs:
  - job: UE
    displayName: 'Azure DevOps for UE'

    steps:
    - checkout: self
      clean: true

    - script: |
        "E:\Epic Games\UE_5.0\Engine\Build\BatchFiles\RunUAT.bat" BuildCookRun -project="$(Build.SourcesDirectory)\$(PROJECT_NAME).uproject" -platform=$(TARGET) -clientconfig=$(CONFIGURATION) -noP4 -cook -allmap -build -pak -partialgc -stage -staginddirectory="$(Build.BinariesDirectory)" -archive archivedirectory="$(Build.ArtifactStagingDirectory"

今回の修正では特に前回の内容と結果は変わらないと思いますが以下の環境変数が追加されています。
それと前回も実は出ていた環境変数の説明も合わせてしたいと思います。

定義済み変数

環境変数とは少し違うのですが Pipelines では『定義済みの変数』があります。
先の例で出てきていましたが $(Build.SourcesDirectory) などです。
Build には様々なパラメーターがありますが、今回は Build.SourcesDirectory、Build.BinariesDirectory、Build.ArtifactStagingDirectory を使用しています。

それぞれの変数の説明を以下に記載します。

変数名	説明
Build.SourcesDirectory	ソース コード ファイルがダウンロードされるエージェントのローカルフルパス。例: c:\agent_work\1\s
Build.BinariesDirectory	コンパイル済みバイナリの出力フォルダーとして使用できるエージェントのローカルフルパス。例: c:\agent_workd\1\b
Build.ArtifactStagingDirectory	成果物がコピー先にプッシュされる前にコピーされるエージェントのローカルフルパス。例: c:\agent_work\1\a

他のパラメーターは以下を参照してください。

環境変数

これは事前にシステムに設定しておくか variables によって定義します。
今回の説明では『プロジェクト名』『ビルドターゲット』『構成』を環境変数化して、切り替えを行えるようにしています。

ただ、今回の内容は YAML ファイルに直接記載していますので、コミットし直しが必要になります。
コミットせずに変更したい場合がありますが、その場合は Pipelines で設定を行うことが可能です。

『Edit』を選択することで右上に『Variables』という項目がありますが、こちらから設定が可能になります。

順に進んでいくと環境変数名とその値を指定可能です。
今回は TARGET に Win64 を設定しました。

これで TARGET は Pipelines の設定に含まれましたので YAML ファイルから削除できますので、削除してコミットしてみます。

無事に設定されているのが確認できると思います。

システム環境変数

では、次に『システム環境変数』を設定します。
今回は UE を使用していますが、UE のインストールディレクトリは端末ごとに違う可能性がありますので、それを端末側で設定したいと思います。

とは言え、これはこれまでに環境変数を使ったことがある人がいれば、全くそれです。
システム環境変数の設定に設定するだけです。

システム環境変数に UE_PATH と UE_BATCH_FILES_PATH を設定しています。
私の環境では UE は E:\Epic Games\UE_5.0 にインストールされていますので、そのパスを設定しています。
UE_BATCH_FILES_PATH には UE のルートディレクトリからの相対パスを指定します。

これを YAML に適用します。

trigger:
- main

variables:
  PROJECT_NAME: UE
  CONFIGURATION: Development

pool: 'UE_Build_Agent'

jobs:
  - job: 'UE'
    displayName: 'Azure DevOps for UE'

    steps:
    - checkout: self
      clean: true
    
    - script: |
        "$(UE_BATCH_FILES_PATH)\RunUAT.bat" BuildCookRun -project="$(Build.SourcesDirectory)\$(PROJECT_NAME).uproject" -platform=$(TARGET) -clientconfig=$(CONFIGURATION) -noP4 -cook -allmap -build -pak -partialgc -stage -staginddirectory="$(Build.BinariesDirectory)" -archive archivedirectory="$(Build.ArtifactStagingDirectory"

RunUAT.bat の部分が置き換わりました。
これをコミットします。

※システム環境変数の変更はシステムの再起動が必要になりますので注意してください。

これで複数のエージェントを登録した場合でも環境変数に UE_BATCH_FILES_PATH を設定しておけば、YAML ファイルの更新の必要がなくパスの切り替えが行われます。

以上で UE5 のビルドの自動化が完了となります。

まとめ

Azure DevOps では Self-hosted で完了を作ってしまえば、あとは YAML スクリプトでターミナルを実行するのと同じような簡単さで自動化をカスタマイズできますので、自動化を検討されている方は Azure DevOps を選択肢に入れて見てはいかがでしょうか？