meta ファイル過不足問題

Unity プロジェクトを Git で管理している方なら一度体験されたことがあると思いますが，
Unity の meta ファイルの commit 忘れをしてしまうとつらいことになります．
個人開発だったらあんまり困らないと思いますが，チーム開発の場合は深刻な問題になりえます．
本記事では DeNA 様の unity-meta-check を用いた Unity の meta ファイル過不足を防止する方法について解説します．

詳細スライドはこちらになります．

speakerdeck.com

unity meta checker

github.com

Git リポジトリ上の Unity の meta ファイルに対する問題をチェックするツールです．
以下の問題をチェックできます．

meta ファイルの Missing

meta ファイルが本来あるはずなのに，その meta ファイルが commit されていない問題．
この問題によって，Asset の参照が壊れることに繋がります．

meta ファイルの Dangling

meta ファイルは存在するが，その Asset がコミットされている問題．
この問題によって，ワーニングメッセージが表示されることがあります．

導入方法

本記事では yml ファイルの記法に関して説明しません．提示する yml ファイル自体も例になります．
パラメタを変えたい場合などが発生した場合は各自調べて頂ければと思います．

GitHub Actions (github-hosted ubuntu-latest)

GitHub Actions の github-hosted ubuntu-latest の場合です．
.github/workflows ディレクトリ上に以下の yml ファイルを配置するだけでできます．

name: Meta File Check (github-hosted ubuntu-latest)

on:
  pull_request:
    branches:
      - main
    paths:
      - Assets/*

jobs:
  meta-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout This Repository
        uses: actions/checkout@v2
        with:
          submodules: false
          lfs: true

      - name: Meta File Check (github-hosted ubuntu-latest)
        uses: DeNA/unity-meta-check@v3

早速 meta ファイルを commit せずにアセットのみを commit して，PR を出してみます．

すると，以上のエラーが発生して，チェックにエラーが発生しています．
さて，漏れていた meta ファイルを commit してみると…．

f:id:xrdnk:20220228005220p:plain

エラーがなくなり，✅ successful check が表示されました．

GitHub Actions (self-hosted windows-amd64 通常版)

public リポジトリなら無料なので github-hosted でもガンガン使えるのですが，
private リポジトリの場合は話が別です．無料枠を使い切った場合は従量課金が必要になります．

blog.beachside.dev

ならば private リポジトリでも無料で利用できるように self-hosted で使えるようにしてみましょう．
今回は windows-amd64 (x64) の環境の例で説明します．

self-hosted runner の設定方法・環境構築について公式ドキュメントを参照してください．

docs.github.com

準備として下記のページから unity-meta-check-windows-amd64.exe のバイナリを self hosted 用のビルドマシンに落としてきます．

github.com

解凍後，適当なディレクトリに配置しておきます．
バイナリをそのまま直接叩けばよいので，yml ファイルの例は以下のようになります．

name: Meta File Check (self-hosted windows-amd64 normal)

on:
  pull_request:
    branches:
      - main
    paths:
      - Assets/*

jobs:
  meta-check:
    runs-on: self-hosted
    steps:
      - name: Checkout This Repository
        uses: actions/checkout@v2
        with:
          submodules: false
          lfs: true

      - name: Meta File Check (self-hosted windows-amd64 normal)
        shell: cmd
        run: |
          "C:\Users\xrdnk\Desktop\Actions\unity-meta-check-windows-amd64.exe"

試しにまた meta ファイルをコミットせずにアセットだけコミットしてみます．

f:id:xrdnk:20220228014333p:plain

2つのチェックにエラーが発生してマージができなくなりました．
ちなみに Branch protection rule は以下のようにしています．
Status checks には yml にある meta-check の job を設定しています．

f:id:xrdnk:20220228014644p:plain

GitHub Actions (self-hosted windows-amd64 binary-checkout 版)

最低限のやり方としては先ほど紹介したもので十分ではありますが，
仮にビルドマシンが壊れた場合，また新しいビルドマシンにバイナリを落とすという手間が発生します．
その場合の対策として，action 時に checkout でバイナリをダウンロードする方式にして実行する方法でやってみます．
こちらの方法は同僚のすぎしーさんにご教授いただきました．本当にありがとうございます．

やり方としては以下のようになります．

private リポジトリを作成して，そのリポジトリにバイナリを配置する (プライベートアクションを作成する)
1. で作成したリポジトリを checkout して，プライベートアクションを実行する

まずは private リポジトリを作成して，バイナリを配置します．
以下は private リポジトリの配置例になります．action.yml は簡易のためにこのような配置にしました．

f:id:xrdnk:20220228015537p:plain

action.yml は例として以下のようにします．

name: unity-meta-check-windows-amd64

runs:
  using: "composite"
  steps:
    - run: ${{ github.action_path }}/checker/unity-meta-check-windows-amd64.exe
      shell: cmd

これで 1. の手順は完了です．
次に meta-check を実行したい側に追加する yml ファイルの例は以下のようになります．

name: Meta File Check (self-hosted windows-amd64 binary-checkout)

on:
  pull_request:
    branches:
      - main
    paths:
      - Assets/*

jobs:
  meta-check:
    runs-on: self-hosted

    steps:
      - name: Checkout This Repo
        uses: actions/checkout@v2
        with:
          submodules: false
          lfs: true

      - name: Checkout unity-meta-check-windows-amd64
        uses: actions/checkout@v2
        with:
          # 下記のリポジトリはプライベートリポジトリとする
          repository: xrdnk/unity-meta-check-windows-amd64
          token: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
          path: .github/private-actions/unity-meta-check-windows-amd64

      - name: Execute unity-meta-check-windows-amd64
        uses: ./.github/private-actions/unity-meta-check-windows-amd64

これで再度 meta-check が実行されているか確認してみます．
3つすべて失敗に終わりました．

f:id:xrdnk:20220228021142p:plain

binary-checkout 方式の Jobs を覗いてエラーを見てみましょう．

f:id:xrdnk:20220228021319p:plain

missing Assets/Scenes/SampleSceneSelfHosted.unity.meta missing Assets/Scenes/SampleSceneSelfHostedCheckout.unity.meta

meta が Missing していますね．無事に想定通りのワークフローが利用できました．
最後にきちんと meta ファイルを commit してみましょう．

f:id:xrdnk:20220228021720p:plain

全ての meta-check が通ったのでこれでマージができるようになりました．めでたしめでたし．

終わりに

本記事では紹介しきれませんでしたが，meta-check は豊富なオプション設定があるので，
カスタマイズしたい場合は利用しましょう．下記は README.md からの抜粋です．

$ unity-meta-check -help
usage: unity-meta-check [<options>] [<path>]

Check missing or dangling .meta files.

  <path>
        root directory of your Unity project or UPM package to check (default "$(git rev-parse --show-toplevel)")

OPTIONS
  -debug
        set log level to DEBUG (default INFO)
  -ignore-file string
        path to .meta-check-ignore
  -ignore-dangling
        ignore dangling .meta
  -ignore-submodules
        ignore git submodules and nesting repositories (this is RECOMMENDED but not enabled by default because it can cause to miss problems in submodules or nesting repositories)
  -no-ignore-case
        treat case of file paths
  -silent
        set log level to WARN (default INFO)
  -unity-project
        check as Unity project
  -unity-project-sub-dir
        check as sub directory of Unity project
  -upm-package
        check as UPM package (same meaning of -unity-project-sub-dir)
  -version
        print version

unity-meta-check だけでなく，以下のバイナリも提供されているので，それぞれ興味があれば利用してみるとよいでしょう．