GitHub ActionsのセルフホストランナーでUnityビルドする

GitHub ActionsはGitHubのリポジトリでビルド等を自動化するサービスです。

通常GitHub側でコンテナを立ち上げて実行しますが、自分で用意したPCにセルフホストランナーをインストールしてGitHub Actionsから呼び出して実行することもできます。Meta Questのプロジェクトのためにセルフホストランナーを導入してみたので、Unityのビルドとテストを走らせる基本的な方法をメモ書きです。

セルフホストランナーを使う理由ですが、Unityの大きなプロジェクトでCIビルドする場合、毎回まっさらなコンテナイメージでチェックアウトしてLibraryフォルダのない初期状態からインポート・ビルドし直すとつらいです。セルフホストすれば差分のみをチェックアウトして繰り返しビルドできます。

またこのページでは触れませんが、iOSビルドする場合、GitHub ActionsのmacOSの料金が高い（Linuxの10倍！）のでセルフホストがほぼ必須になると思います。

• GitHub Actionsの支払いについて - GitHub Docs

セルフホストランナーを使用する手順

GitHub ActionsのセルフホストランナーでUnityビルドする手順を簡単に説明します。ビルド用PCとしてここではWindowsを使用しています。

Unityのプロジェクトを用意する

Unityのプロジェクトを作成してコマンドラインからビルドできるようにしておきます。Editorという名前のフォルダに下記のようなビルドスクリプトを作っておきます。

using System.Linq;
using UnityEditor;

public class CI
{
    [MenuItem("CI/Build")]
    public static void Build()
    {
        BuildPipeline.BuildPlayer(ScenePaths, "Build/Application.apk", BuildTarget.Android, BuildOptions.CompressWithLz4);
    }

    static string[] ScenePaths => EditorBuildSettings.scenes.Select(scene => scene.path).ToArray();
}

コンソールから以下のようなコマンドを実行します。Unityのパスは適宜変更してください。

"C:\Program Files\Unity\Hub\Editor\2022.1.22f1\Editor\Unity.exe" -quit -batchmode -projectPath . -executeMethod CI.Build -buildTarget Android -setDefaultPlatformTextureFormat astc -nographics -logFile output.txt

しばらく待ってBuildフォルダに.apkファイルがビルドされることを確認してください。確認したらGitHubでリポジトリを作り（適宜.gitignoreを設定して）pushします。

セルフホストランナーをセットアップする

次にセルフホストランナーを使用できるように準備しましょう。

GitHubでリポジトリのSetings > Actions > Runnersを開いて、New self-hosted runnerをクリックします。PowerShellを開き、ドライブのルートに移動して（ドライブはどこでも大丈夫のようです）ページに表示されているコマンドを上から順番にコピペ実行してください。

configure.cmdでランナーの名前やディレクトリ等を設定して、run.cmdを実行するとセルフホストランナーがジョブ待機状態になります。

なお、WindowsでGitHub Actionsのセルフホストランナーを実行する場合、デフォルトのシェルとしてPowerShellを使用するのですが、外部からダウンロードしたPowerShellスクリプトを実行できるように、管理者モードのPowerShellで下記を実行しておきます。

Set-ExecutionPolicy RemoteSigned

GitHub Actionsでビルドする

GitHubのリポジトリにGitHub Actionsのworkflowファイルを作成します。リポジトリのActionsタブでテンプレートを選択できるのですが、「set up a workflow yourself」をクリックして以下を参考に書き換えてください（最後の行の Copy-Item でビルドされた .apk ファイルを確保しています。コピー先フォルダを適当に変更してください）。

name: Build

on:
  push:
    branches: [ main ]

jobs:
  build:
    runs-on: self-hosted

    steps:
    - name: Checkout
      uses: actions/checkout@v3
      with:
        lfs: true
        clean: false

    - name: Unity Build
      shell: cmd
      run: |
        "C:\Program Files\Unity\Hub\Editor\2021.3.4f1\Editor\Unity.exe" -quit -batchmode -projectPath . -executeMethod CI.Build -buildTarget Android -setDefaultPlatformTextureFormat astc -nographics -logFile -

    - name: Release
      run: Copy-Item Build\Application.apk D:\Builds\Application${{ github.run_number }}.apk

右上のStart commitボタンでコミットすると、すぐ手元のPCが動き出してビルドが開始されるはずです。リポジトリのActionsのページでビルドの進行をリアルタイムで確認できます。

runs-on: self-hostedによりセルフホストランナーで実行されるようになっています。下の記述により、mainブランチにコミットがpushされるたびにビルドが実行されます。

on:
  push:
    branches: [ main ]

actions/checkoutの「clean: false」がミソで、リポジトリのチェックアウト時にLibraryフォルダ等を消さないようにします。また、Git LFSを使用している場合は 「lfs: true」が必要 です。

Unityはcmdから実行し-logfile -（「-」が必要）でログを標準出力していて、GitHub上で閲覧できます。PowerShellで実行する場合は以下のようにすれば標準出力からログを出力できます（が、ビルドが終了してもActionsが次のステップに行かなかったりする？　たまたまかもしれませんが……）。

      run: |
        & "C:\Program Files\Unity\Hub\Editor\2021.3.4f1\Editor\Unity.exe" -quit -batchmode -projectPath . -executeMethod CI.Build -logFile - -buildTarget Win64 -nographics | Out-Host

ビルドして生成された.apkファイルについて、ここでは ${{ github.run_number }} でビルド番号をつけてコピーしています。

プルリクエストでテストを走らせる

ビルドができるようになったら次はテストです。

JenkinsだとGitHub Branch Source Pluginあたりを使用して、正直かなりセットアップが面倒くさいのですが、GitHub Actionsだとずっと簡単で、最低限以下のようなworkflowファイルを追加するだけです。

name: Pull Request Test

on:
  pull_request:
    branches: [ main ]
    types: [ opened, synchronize ]

jobs:
  test:
    runs-on: self-hosted

    steps:
    - name: Checkout
      uses: actions/checkout@v2
      with:
        fetch-depth: 0
        lfs: true
        clean: false

    - name: Unity Play Mode Test
      shell: cmd
      run: |
        "C:\Program Files\Unity\Hub\Editor\2021.3.4f1\Editor\Unity.exe" -batchmode -projectPath . -runTests -testPlatform PlayMode -testResults TestResult-PlayMode.xml -logFile -
    
    - name : Unity Edit Mode Test
      shell: cmd
      run: |
        "C:\Program Files\Unity\Hub\Editor\2021.3.4f1\Editor\Unity.exe" -batchmode -projectPath . -runTests -testPlatform EditMode -testResults TestResult-EditMode.xml -logFile -

プルリクエストすると、mainブランチにマージ後のコミットがチェックアウトされ、UnityのPlay ModeおよびEdit Modeテストが実行されてGitHub上に結果が表示されます（Unityのテストの作り方についてはここでは説明しません）。

テスト結果を見やすく表示する方法についてはまだ検討中……（まだ試していませんが、下記のジョブサマリー機能を使うとよさそうです）。

• Publishing Test Results - GitHub Actions - GitHub Support Community

以下、Tips です。

GitHub ActionsのTips

特定のタグでビルドを走らせるには

on:
  push:
    tags:
      - 'release-*'

シェルを選択するには

WindowsではrunステップはデフォルトでPowerShellを使用するようになっています。cmdを使用するにはshell: cmdを、Git Bashを使用する場合はshell: bashを設定します。

shell: cmd

• GitHub Actions default shell on Windows runners is changing to PowerShell - GitHub Changelog

デフォルトのシェルやディレクトリを設定するには

defaults:
  run:
    shell: cmd
    working-directory: UnityProject

ジョブ結果の概要を出力するには

ジョブ中で環境変数GITHUB_STEP_SUMMARYにMarkdownを出力すると、GitHub ActionsのSummary画面に表示されます。URLを出力すると自動的にリンクになります。

• Supercharging GitHub Actions with Job Summaries | The GitHub Blog

WindowsではシェルにGit for Windowsのbashを指定すると動作しました。下記のようにジョブ中でファイルにレポート等を出力して、catで渡すやり方が便利そうです。

steps:
  - name: Adding markdown
    shell: bash
    run: |
      echo 'Hello, GitHub Actions!' >> $GITHUB_STEP_SUMMARY
      cat report.txt >> $GITHUB_STEP_SUMMARY

ビルド番号を取得するには

github.run_numberでworkflowを実行した回数を取得できます。コマンド引数に使用したり、下のように環境変数に設定してEnvironment.GetEnvironmentVariableメソッドで参照します。

set BUILD_NUMBER=${{ github.run_number }}

ビルド番号はActionsの各workflowの実行結果のページのタイトル欄で確認できます（#のあとに番号がついています）。数値をリセットするにはworkflowファイルの名前を変更するしかないようです。

複数のリポジトリでセルフホストランナーを使用するには

セルフホストランナーはリポジトリまたはOrganizationごとにセットアップできます。複数のリポジトリで共通のセルフホストランナーを使用するには、Organizationに対してセットアップするしかないようです。

セルフホストランナーは同時実行できるの？

こちらのスレッドに回答がありました。

• Do jobs in self-hosted runners run in parallel? - GitHub Actions - GitHub Support Community

Git for Windowsでworkflowをpushするとリジェクトされる

(refusing to allow an OAuth App to create or update workflow `.github/workflows/build.yml` without `workflow` scope)

というエラーが出る場合、Windows の 資格情報マネージャー > Windows 資格情報 で git:https://github.com の項目を削除して git コマンドで再ログインしてください。

しばらく使用していなかったセルフホストランナーを復旧するには

GitHub Actionsに30日以上接続されていないセルフホストランナーはGitHubから自動的に削除されます。

A self-hosted runner is automatically removed from GitHub if it has not connected to GitHub Actions for more than 30 days.

復旧するには、actions-runnerフォルダを削除してセルフホストランナーのインストールからやり直します。面倒くさいので、セルフホストランナーはできれば落とさないようにしましょう。

「This check failed」と出て動かない

セルフホストランナーを削除して再登録すると動くようになったことがありました。

GitHubの設定のActions > Runnersの画面でRemoveボタンをクリックして「config.com remove --token [トークン]」を実行して削除し、RunnersでNew Runnerをクリックして「config.cmd --url [リポジトリ] --token [トークン]」で再登録します。

Unity関連のTips

コンテナでビルドする場合

セルフホストランナーを使わない場合の参考ページです。

UnityがインストールされたDockerイメージとしてgableroux/unity3dを使用するのが一般的なようです。Unityのライセンス認証で苦労するとの噂。

• neue cc - GitHub ActionsでUnityでunitypackage生成とビルド＆実機(Linux)ユニットテストを実行する
• UnityをGitHub Actionsで動かす際にライセンス認証周りで注意するべき点 - Qiita

macOS で試行錯誤されている例。料金の問題から、結論としてセルフホストがおすすめとのことです。

• 「GitHub ActionsでUnityビルドしてipa吐き出すActions作ろ」と思ったら大苦戦した話 - yukiarrr開発月誌

.unitypackageを作るには

.unitypackageはUnityがなくても作れるようです。参考ページ：

• GitHub ActionsでUnityのライブラリのリリースが捗る話 - Qiita

参考リンク

• awesome-actions
• GitHub ActionsでUnityのAndroid, iOSビルドをやってみる - Qiita