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

最終更新日：2022年06月19日

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

通常 GitHub 側でコンテナを立ち上げて実行しますが、自分で用意した PC にセルフホストランナーをインストールして GitHub Actions から呼び出して実行することもできます。Oculus 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\2021.3.4f1\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 を開いて、Self-hosted runners で Add Runner をクリックします。PowerShell を開き、ドライブのルートに移動して（ドライブはどこでも大丈夫のようです）ページに表示されているコマンドを上から順番にコピペ実行してください。

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

なお、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: [ master ]

jobs:
  build:
    runs-on: self-hosted

    steps:
    - name: Checkout
      uses: actions/checkout@v2
      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 が動き出してビルドが開始されるはずです。GitHub の Actions のページでビルドの進行をリアルタイムで確認できます。

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

on:
  push:
    branches: [ master ]

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: [ master ]
    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 -

プルリクエストすると、master にマージ後のコミットがチェックアウトされ、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 を設定します。

shell: cmd

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

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

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

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

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