この手法は一般にテスト影響分析（test impact analysis）と呼ばれ、testmonはそれをPythonで無料で使える、オープンソースの手段です。gitにはまったく依存しません。比べる相手は前回の実行で見たコードで、コミット済みかどうかは関係ありません。

今週、私が作っているマーケットプレイスアプリのPythonのテストにこれを入れました。理由は、速さそのものではありません。

なぜ入れたのか

#

機能のリクエストは、たいてい小さなものです。画面が一つ、エンドポイントが一つ、挙動を変えたいルールが一つ。ところがテストスイートを丸ごと実行すると、そのどれもが実際より大きくなっていました。スイートはDjangoのテストが2,248件で、4プロセスで約3分半、1プロセスだと11分かかります。編集のたびにその全部を実行していましたが、そのほとんどはリクエストが一切触れていない部分を確認するものです。関係のないテストが落ちたり、単に実行に時間がかかったりするたびに、その機能は待たされました。機能リクエストとは関係のない事情で足止めされていて、足止めしていたのは自分のテストスイートだったわけです。

かといって、別のやり方がましだったわけでもありません。全体の実行は飛ばして、変更をカバーしていそうなテストファイルを当て推量で選び、ときどき外す。速くはありますが、正確ではありません。テストしていない変更をリリースすれば、その機能リクエストをもう一度やり直すことになります。

待つテストは、変更の届きうるテストとぴったり同じであるべきで、多すぎても少なすぎてもいけません。testmonはその集合を、推測ではなく記録から出してくれます。スイート全体は今もCIで実行していて、そこなら次に取りかかっている作業を止めることはありません。

何を実行するかの決め方

#

testmonは各Pythonファイルをブロックに分けます。モジュールのトップレベル、各クラス、各関数がそれぞれ一つのブロックで、ネストした関数の本体はそれを囲むブロックから切り離されます。保存するのは各ブロックのチェックサムだけで、コードそのものは保存しません。テストの実行中にcoverage.pyが実行された行を記録し、testmonはそれらの行がどのブロックに属するかを書き留めます。静的解析も、importからの推測もありません。テストが依存するのは、そのテストが実際に実行したブロックだけです。

たとえば、こんなモジュールがあるとします。

# pricing.py
def subtotal(items):
    return sum(item.price * item.quantity for item in items)

def discount(total, code):
    if code == "WELCOME10":
        return total * 0.9
    return total

subtotal()だけを呼ぶテストは、モジュールのトップレベルとsubtotalの本体に依存します。discount()をどう書き換えても、testmonはそのテストを再実行しません。そのテストはdiscountの行を一行も実行していないからです。逆にsubtotalの中を一文字でも変えれば、結果が変わりようのない変更でも再実行されます。testmonは副作用について賢く立ち回ろうとはしません。実行したブロックが変わったら、実行する。それだけです。

コードの周りにあるものも追跡します。記録にはPythonのバージョンと、インストール済みのパッケージとそのバージョンが含まれます。環境変数は見ていません。同じコードを二つの設定モジュールで動かすなら、--testmon-env（手順8）で名前を付けないと、一つの記録を共有してしまいます。Djangoをアップグレードすれば、Djangoに触れたものはすべてまた影響を受けます。Djangoアプリなら、それはつまり全部です。

見えないもの

#

testmonが追跡するのは、テストが実行するPythonのコードです。テストが読むそれ以外のファイル、つまりテンプレートやJSON、テキストなど、ディスク上にあるほかのものは追跡しません。ネットワーク越しに呼び出すサービスも追跡しません。そして、テストが始まる前に一度だけ実行されるものを、特定のテストに結びつけることもできません。

Djangoのプロジェクトでいえば、まずマイグレーションです。テスト用データベースを作るときに一度だけ実行されるので、どのテストの記録にも含まれません（後で紹介するラッパーは、新しいマイグレーションがあるとテスト用データベースを作り直します）。次に設定と起動時のコードで、pytestの起動中に実行されるので、どのテストにも属しません。そしてテンプレートとデータファイルです。テンプレートはPythonではないので、編集しても、それを描画するテストは一つも再実行されません。

私のスイートには、ほかにもいくつかあります。モバイルアプリのテストと共有しているフィクスチャのJSONファイルを読むテスト。ビルドしたWebのバンドルを確認するテスト。同じリポジトリで生成している静的サイトの出力を確認するテスト。どれを変えても、testmonは「何も実行する必要はありません」と平然と答えます。だから以下の手順では、testmonをスクリプトで包んで、こうしたファイルに気づき、どれかが変わっていたら全部を実行するようにしています。

Djangoのプロジェクトに入れる方法

#

ここではpytestとpytest-djangoを使い、依存関係はuvで管理している前提で書きます。pipを使っているなら、uv add --devをpip installに置き換え、uv runを外してください。

1. インストールする。

uv add --dev pytest-testmon

2. pytestでスイートを実行できるようにする。 testmonはpytestのプラグインなので、python manage.py testでは何もしません。pytest-djangoには、settingsモジュールと、テストが使っているファイル名のパターンを教える必要があります。

# pytest.ini
[pytest]
DJANGO_SETTINGS_MODULE = myproject.settings
python_files = tests.py test_*.py *_tests.py
python_classes = Test* *Tests *TestCase

これまでDjangoのランナーでしかスイートを実行したことがないなら、testmonを入れる前に一度pytestで実行し、違いが出たところを直しておきましょう。そうしないと、二つの問題を同時にデバッグする羽目になります。

3. 記録をgitに入れない。 testmonはpytestのルートディレクトリに.testmondataを書き出します。中身はSQLiteのデータベースなので、隣に-shmと-walのファイルもでき、さらに後で出てくるスクリプトがスタンプファイルを足します。パターン一つで全部まとめて除外できます。

# .gitignore
.testmondata*

4. 一度スイート全体を記録する。 testmonは、すべてのテストの実行を一度見るまで何も選べません。

uv run pytest --testmon

まっさらなチェックアウトでは、この最初の実行は1プロセスでのスイート全体の実行になります。私の環境では、2,248件のテストに約12分かかります。それ以降は、同じコマンドで影響を受けるテストだけが実行されます。何も変えていなければ、何も実行されません。

落とし穴が二つあります。一つ目に、testmon 2.2.0以前ではpytestのcacheプラグインが必要です。最初に試したときは-p no:cacheproviderを付けて実行していて、KeyError: 'lf'で落ちました（2.3.0では--lfがなければ未指定として扱われます）。二つ目に、Python 3.14以降では、記録する前にCOVERAGE_CORE=ctraceを設定してください。理由は、この後の「成功に見えたバグ」で説明します。以下のスクリプトで、いちばん大事な一行です。

追記（11月7日）：11月2日にリリースされたtestmon 2.3.0は、coverageのCトレーサーを自分で強制するようになったので、このバージョンではこのexportは念のためのものになります。2.2.0以前なら残してください。そして、わざと壊して確かめるチェックは、バージョンにかかわらず続けてください。

5. 見えないファイルのためにラップする。 毎日安心して使えるのは、この部分があるからです。スクリプトは、前回の実行が始まった時点のスタンプファイルを持っています。testmonが追跡できないファイルのどれかがスタンプより新しければ、全部を実行して記録し直します。新しいマイグレーションなら、テスト用データベースを作り直すだけです。そうでなければ、選ぶのはtestmonに任せます。削って例にしたものがこちらです。

#!/usr/bin/env bash
# scripts/test-changed.sh: the tests a change can affect, or all when in doubt.
#   scripts/test-changed.sh            # affected tests
#   scripts/test-changed.sh --all      # everything, re-recorded
#   scripts/test-changed.sh -k orders  # anything else goes to pytest
set -euo pipefail
cd "$(dirname "$0")/.."

# coverage's C tracer: from Python 3.14 coverage defaults to sys.monitoring,
# which reports a line only the first time a process runs it, so testmon
# would credit each line to one test. Changing this means --all.
export COVERAGE_CORE=ctrace

STAMP=.testmondata.started
full=false
rebuild=false
if [ "${1:-}" = "--all" ]; then
    full=true; shift
elif [ ! -f .testmondata ] || [ ! -f "$STAMP" ]; then
    echo "No record yet: running everything once."
    full=true
else
    # Changed since the last run started, and not traceable per test:
    # anything that isn't Python, plus settings and conftest.
    newer="$(find myapp myproject fixtures pytest.ini \
        -type f -newer "$STAMP" ! -path '*/migrations/*' \
        \( ! -name '*.py' -o -path 'myproject/settings*' -o -name 'conftest.py' \) \
        ! -path '*/__pycache__/*' | head -5)"
    if [ -n "$newer" ]; then
        echo "Changed, and not traceable per test:"; printf '  %s\n' $newer
        full=true
    fi
    # A new migration needs a fresh test database, not a full run.
    [ -n "$(find myapp -path '*/migrations/*.py' -newer "$STAMP" | head -1)" ] && rebuild=true
fi

# Stamp the start, so an edit made while the tests run counts next time.
started="$(mktemp .testmondata.run.XXXXXX)"
args=(--testmon --reuse-db)
# --create-db alone deletes the database when the run ends; with
# --reuse-db as well, the rebuilt one is kept for next time.
[ "$rebuild" = true ] && args=(--testmon --reuse-db --create-db)
[ "$full" = true ] && args=(--testmon-noselect --reuse-db --create-db)

status=0
uv run pytest "${args[@]}" -q "$@" || status=$?
# 0: passed, or nothing selected. 1: some failed (still recorded).
# 5: nothing collected at all.
case "$status" in 0|1|5) mv "$started" "$STAMP" ;; *) rm -f "$started" ;; esac
[ "$status" = 5 ] && exit 0
exit "$status"

この中で説明しておきたい点が二つあります。--reuse-dbは、テスト用データベースを実行の間で使い回すためのpytest-djangoのフラグです。一回の実行が数秒で済むようになると、これが効いてきます。毎回作り直していると、テストそのものより時間がかかることもあるからです。全体の実行や、新しいマイグレーションの後の実行では、データベースが現在のスキーマになるよう--create-dbを足します。そのときも--reuse-dbは外さないでください。--create-dbだけだと、pytest-djangoは実行の終わりにデータベースを削除してしまい、次の実行でまた一から作ることになります。

もう一つは終了コードです。testmonがすべてのテストを選択から外したとき、実行は0で終わるので、「何も変わっていない」は成功として扱われます。終了コード5はpytestの「テストが一つも収集されなかった」という意味で、スクリプトはこれも問題なしとして扱います。

リストに入っていないものにも注目してください。pyproject.tomlとロックファイルです。最初のバージョンはロックファイルが変わるたびに全部を実行していて、そのせいで遅いフォールバックがほぼ毎日発動し、入れる前より悪くなっていました。testmonはインストール済みのパッケージのバージョンを自分で追跡しているので、手助けはいりません。

6. 専用のデータベースとキャッシュを持たせる。 同じマシンでほかにもテストを実行するもの、たとえば二つ目のターミナルやコーディングエージェント、manage.py testなどがあるなら、スクリプトには専用のテスト用データベースと専用のキャッシュ番号を指定しておきます。そうすれば、使い回しているデータベースが他の誰かの実行と鉢合わせすることはありません。

export DATABASE_URL="postgresql://myapp:myapp@localhost:5432/myapp_changed"
export REDIS_URL="redis://localhost:6379/8"

7. 実行のたびにそのキャッシュを空にする。 これは痛い目を見て覚えました。一部だけを実行したときに、全体の実行では出ないKeyErrorが出るようになったのです。カテゴリのラベルの一部が有効期限なしでキャッシュされていて、ある実行から使い回したテスト用データベースが、それより前の実行で温まったままのキャッシュと出会っていました。スクリプトの冒頭でキャッシュをクリアしたら直りました。

uv run python -c "import os, redis; redis.Redis.from_url(os.environ['REDIS_URL']).flushdb()"

これはtestmonが、ドキュメントに書いてあるとおりのことをしているだけです。毎回違うサブセットを実行すると、前に何が実行されたかのおかげで通っていたにすぎないテストがあぶり出されます。直すべきはテストのセットアップで、testmonではありません。

8. 選択が間違っているときのためのフラグを知っておく。

• --testmon-noselectはすべてのテストを実行しますが、落ちそうなものを先に回します。-k、-m、--lfやテストのnode IDを一緒に渡すと、testmonは自動的にこれに切り替えます。
• --testmon-forceselectは、影響を受けるテストのうち、-kや-mにも一致するものだけを実行します。
• --testmon-nocollectは既存の記録を使いますが、記録には何も追加しません。デバッガの下で動かしているときや、coverageがすでに動いているときは、強制的にこれになります。
• --no-testmonは、一回の実行だけtestmonを無効にします。addoptsに入れているときに使います。
• --testmon-env=<name>は、一つのファイルの中に記録を別々に持ちます。二つのsettingsモジュールで実行するスイート向けです。

プロジェクトにJavaScriptの側もあるなら、Jestには同じような機能が最初から入っています。jest --changedSince=mainは、main以降に変わったものをimportしているテストを実行します。たどるのはcoverageではなくimportです。私はアプリのpackage.jsonにnpm run test:changedとして追加して、両側で同じ習慣が使えるようにしました。ユーティリティモジュールを一つ編集したときは、アプリの121個のテストファイルのうち7個が選ばれました。

どれだけ節約できるか

#

ラッパーを入れた後、次のセクションで書くバグを直してから、起動時間込みで計ってみました。

ふだんの編集なら並列実行のスイートより約25倍速く、何も変わっていなければ約200倍速くなります。

記録も、もっと広い範囲で同じことを示しています。スイートが実行する、テスト以外のPythonファイル307個のうち、中央値にあたるファイルを変えたときに届くのはテスト22件、テスト時間にして約8秒です。反対の端にはいくつかのコアモジュールがあります。ほぼすべてのテストがこれらを実行するので、変更すると約1,500件のテストに届き、testmonはスイートの大半を再実行します。これは失敗ではなく、正しい答えです。これらの数字はファイルごとの上限です。testmonはブロック単位で動くので、関数を一つ変えれば、その関数を実行したテストだけが選ばれます。

コストが表に出るのは、ラッパーがフォールバックしたときです。全体の実行は最初と同じ1プロセスでの記録なので約12分かかり、置き換える前の並列実行のスイートより遅くなります。1プロセスなのは、testmonをpytest-xdistと組み合わせてまだ試していないからです。xdistは1.4から対応しているので、次に測るべきはそこでしょう。だからこそ、フォールバックのきっかけになるファイルのリストは、正直でいられる範囲でできるだけ短くしておくべきです。

成功に見えたバグ

#

最初に出た数字は、これよりも良いものでした。一か所の編集でテスト6件、3.3秒。でもそれは間違っていて、画面のどこにもそうは書いてありませんでした。

Python 3.14から、coverage.pyはデフォルトで新しいコアを使います。インタプリタのsys.monitoringの上に作られたものです。このコアがある行を報告するのは、プロセスがその行を初めて実行したときだけです。testmonはどのテストがどの行を実行したかの記録をcoverageから作るので、各行は、たまたま最初にそれを実行したテスト一つだけのものとして記録され、ほかのどのテストにも結びつきませんでした。8件のテストが共有している行を編集しても、testmonはそのうち1件しか選びません。

気づいたのは、この仕組みをそのまま真似した、私の別の小さなプロジェクトでした。そちらに導入する作業の一環として、わざと一行を壊して結果を比べたところ、数字が合わなかったのです。こちらのスイートに戻って、同じ確認をしました。ホーム画面のバナーのコードで、スライドのタイトルの一行を壊します。素のpytestでは8件のテストが失敗しました。testmonが選んだのは4件です。壊れた残りの4件は一度も実行されず、出力のどこにも、それらが外されたことは書いてありませんでした。

直すのは一行で、export COVERAGE_CORE=ctraceです。これでcoverageは昔ながらのCトレーサーに戻ります。トレーサーが違えば記録も違うので、記録し直しました。2,248件のテストで12分3秒です。その後、同じように壊す編集をしたら、壊れた11件のテストがすべて実行されました。

追記（11月7日）：11月2日リリースのtestmon 2.3.0は、プロセス内でもサブプロセスでもCトレーサーを自分で設定するようになったので、新規に入れる場合はこのexportはもう要りません。次の段落のチェックは、今でも要ります。

この記事で何よりも先に伝えたい教訓はこれです。選ぶテストが少なすぎるテストセレクタは、成功とまったく同じに見えます。テストは少なく、実行は速く、すべて緑。だから導入するときは、共有されている何かをわざと壊し、素のスイートとセレクタの両方を実行して、同じテストが失敗するかを確かめてください。そして、Pythonやcoverage.pyのバージョンが変わるたびに、もう一度やってください。

コーディングエージェントの出番

#

そのリポジトリの変更を、もう全部自分でしているわけではありません。小さな変更の多くはコーディングエージェント（私の場合はClaude Code）がしていて、良いエージェントは編集のたびにテストを実行します。11分かかるスイートを前にすると、エージェントにも私と同じ二つの悪い選択肢しかありません。待つか、どのテストファイルが関係するかを当て推量するかです。

そこで、リポジトリのエージェント向けの指示に、作業中のテストはこのラッパースクリプトで実行するのを基本とし、全体を実行するときは--allを付ける、と書きました。エージェントも私と同じ正確なテストの集合を、編集のたびに数秒で得られます。ステップ6でスクリプトに専用のデータベースとキャッシュを持たせているのも、これが理由です。忙しい日には同じマシンで複数のセッションがテストを実行していて、使い回しているデータベースが他の誰かの実行と鉢合わせすることは、絶対にあってはなりません。

どれも、testmonにAI固有の何かを求めているわけではありません。同じ記録、同じ選択です。ただ、変更を加えているのが何であれ、その変更の数がとても多いと、それだけ効き目も大きくなります。

CIにはもっと粗いものを入れた理由

#

testmonにはCIモードがありません。ランナーの上でもノートPCの上と同じように動きます。作者は、CIのランナー間で.testmondataを共有したりキャッシュしたりするのは、自分たちのホスティングサービスであるtestmon.netに比べてずっと効果が薄いと書いています。キャッシュした記録は上で挙げた点でどれも見えないままですし、私のCIはDjangoのランナーを4プロセスで動かしてスイートを実行しています。なので、testmonは入れませんでした。

代わりにCIに入れたのは、同じ考え方をファイル単位にしたものです。チェックのワークフローはまず小さなジョブでpushの差分を取り、リポジトリのどちら側に触れたかを判断します。PythonのAPIか、モバイルアプリか、両方か、どちらでもないか。これまでCIは、ドキュメントだけのものも含めて、pushのたびにPythonとアプリの両方のジョブを実行していました。今は、ドキュメントだけのpushなら何も実行せず、アプリだけへのpushならDjangoのスイートを飛ばします。実際のコミット5件に対してこのジョブを試しに走らせてみたところ、ドキュメントだけのコミットでは何も実行されず、アプリだけのコミットではPythonのジョブが、バックエンドだけのコミットではアプリのジョブが飛ばされました。削って例にしたものがこちらです。

jobs:
  changes:
    runs-on: ubuntu-latest
    outputs:
      python: ${{ steps.diff.outputs.python }}
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - id: diff
        env:
          BEFORE: ${{ github.event.before }}
          HEAD: ${{ github.sha }}
        run: |
          FILES="$(git diff --name-only "$BEFORE" "$HEAD")"
          # Python's inputs include the non-Python files its tests read.
          PY='^(myapp/|myproject/|fixtures/shared\.json$|web/dist/|pyproject\.toml$|uv\.lock$)'
          if printf '%s\n' "$FILES" | grep -qE "$PY"; then
            echo "python=true" >> "$GITHUB_OUTPUT"
          else
            echo "python=false" >> "$GITHUB_OUTPUT"
          fi

  python:
    needs: changes
    if: needs.changes.outputs.python == 'true'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - run: uv run python manage.py test --parallel 4 --noinput

実際のワークフローでは、比べる範囲がないとき、つまり新しいブランチやforce push、手動実行のときにも全部を実行します。

盲点は、形を変えただけで同じものです。testmonにはJSONファイルが見えませんが、パスのフィルタも、リストに書かない限り見えません。そこでパターンには共有のフィクスチャ、ビルドしたバンドル、生成したサイトを明示的に書き、編集する人にはリストを実態に合わせておくよう頼むコメントを添えています。ファイル単位のやり方は大雑把ですが、失敗するときは安全な方向に失敗します。Python側で何かが変わっていれば、スイート全体が実行されます。

入れる価値はあるか

#

実行に数分かかるスイートなら、あります。本当のコストは見えないものの方で、ラッパースクリプトはそのためにあります。それでも、testmonが活きるのはノートPCでの開発ループです。CIはPython側が変わるたびに今もスイート全体を実行していて、デプロイの前に私が信頼しているのはその実行です。

GitHub ActionsでDocker Composeを動かす方法を探してここに来たなら、先に結論を。私はそれを2年やって、やめました。いまのCIは同じPostgresとValkeyのイメージをservices:として宣言し、同じuv run …とnpm run …をランナー上で直接実行します。Composeは開発者が手元で動かすものに戻りました。以下はその理由と、実際のファイルです。

2024年にCI/CDのロジックはプラットフォーム固有のYAMLではなくDocker Composeにという記事を書きました。ビルドのロジックはComposeに置き、CIツールにはそれを呼ぶことだけをさせる、という内容です。2年たって、実際にリリースに使っているリポジトリを全部見直しました。ワークフローがあるのは4つで、コミッターはどれも私一人です。そして、そのワークフローのうちdocker composeを呼んでいるものは、もう一つもありません。原則は残り、やり方は残りませんでした。以下はその代わりに入ったものです。ファイルを削って例にしたもの、GitHubが記録したステップごとの所要時間、そしてCI/CDの図が期待するほどには自動化されていない部分も書いています。

動かしているパイプラインを一つの表に

#

教科書の言葉でいえば、二つのHugoサイトは継続的デプロイメントで、アプリ（私が作っているマーケットプレイス兼コミュニティアプリ）は継続的インテグレーションにコマンド一つのリリースを足した継続的デリバリーです。チェックは何かがおかしいと教えてくれるだけで、デプロイを止めはしません。これは意図してそうしています。OTAアップデートは対象のバイナリバージョンを使っているすべての端末に届くので、マージの副作用ではなく判断であるべきです。そしてAPIはデータベースのマイグレーションが走る場所です。残り二つのDjangoアプリには、ワークフローがそもそもありません。

CIの側：ワークフロー一つ、ジョブ二つ

#

アプリのCIは.github/workflows/checks.ymlというファイル一つです。10月11日までは、これすらありませんでした。以下はその形を削って例にしたものです。

# Lint, types and tests on every push and pull request to main.
# Nothing here deploys.
name: Checks

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

concurrency:
  group: checks-${{ github.ref }}
  cancel-in-progress: true

jobs:
  python:
    runs-on: ubuntu-latest
    timeout-minutes: 30
    services:
      postgres:
        image: postgres:17
        env:
          POSTGRES_USER: myapp
          POSTGRES_PASSWORD: myapp
          POSTGRES_DB: myapp
        ports: ["5432:5432"]
        options: >-
          --health-cmd "pg_isready -U myapp"
          --health-interval 5s --health-timeout 5s --health-retries 20
      valkey:
        image: valkey/valkey:8-alpine
        ports: ["6379:6379"]
    env:
      DEBUG: "True"
      DATABASE_URL: postgresql://myapp:myapp@localhost:5432/myapp
      REDIS_URL: redis://localhost:6379
      PYTHON_JIT: "0"   # match production
    steps:
      - uses: actions/checkout@v7
      - uses: astral-sh/setup-uv@v10
        with:
          enable-cache: true
          prune-cache: true
      - run: uv sync --locked
      - run: uv run ruff check .
      - run: uv run mypy myapp/
      - run: uv run python manage.py test --parallel 4 --noinput

  app:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    defaults:
      run:
        working-directory: frontend
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v7
        with:
          node-version: 24
          cache: npm
          cache-dependency-path: frontend/package-lock.json
      - run: npm ci
      # Expo writes this on `expo start` and it is gitignored,
      # so a fresh checkout doesn't have it.
      - run: printf '/// <reference types="expo/types" />\n' > expo-env.d.ts
      - run: npm run typecheck
      - run: npx jest --ci

二つのジョブは並行して走ります。これまでに成功した35回の実行で、アプリのジョブの中央値は約7分、Pythonのジョブは約12分半です。

services:ブロックが、Composeファイルの移った先です。これは次の節で書きます。環境変数はいくつかとフラグ一つだけです。ほかはすべて開発者がdocker compose upで得る開発用のデフォルトに落ちるので、テストにシークレットは一つも要りません。本当にそうか確かめるために、まさにその環境だけで、ほかに何もない状態でテストの一部を走らせました。

CIは手元のノートPCや本番イメージと同じインタープリタ、つまりuv自身がビルドしたPython 3.15.0で動きます。uv syncが.python-versionを読み、まさにそのビルドをダウンロードするからです。（実際のファイルではsetup-uvにpython-version-fileという入力も渡していますが、これは何もしていません。setup-uv v6にはそんな入力がなく、毎回の実行にそういう警告が付いています。この記事を書いていて初めて気づきました。）

インタープリタを揃えた甲斐は、ワークフローを入れて8日後に出ました。10月19日に3.15のJITコンパイラを有効にしたところ、有効にして最初の実行でテストが一つ落ちたのです。アプリが保存のたびに通るコードパスのごく普通のyield fromが、AttributeError: 'list' object has no attribute 'send'を投げていました。同じコミットをJITなしで走らせると通ります。私のMacはarm64で一度もこれに当たらず、ランナーは本番マシンと同じx86_64です。JITはCIでもDockerfileでも再び無効にしてあり、このバグが本番に届くことはありませんでした。これはpython/cpython#155823で、3.15.0のリリース後の10月13日に上流で修正されています。

実は最初の実行も落ちていて、こちらの理由はもっと地味です。Expoはexpo startのときにexpo-env.d.tsを書き出し、このファイルはgitignoreされています。なので私が使ってきた作業コピーにはどれもあり、まっさらなチェックアウトにはありませんでした。TypeScriptは、ローカルでは一度も出たことのないエラーを五つ出しました。そのファイルを書き出すステップが対処です。

concurrencyは、同じブランチに新しいpushが来ると前の実行を取り消します。これまでに取り消された12回は、すべてこれによるものです。コミット前のフック（pre-commit）がリンターを走らせ、PythonかTypeScriptがステージされていれば型チェッカーも走らせるので、ミスの大半はpushまで行きません。

Docker Composeファイルはどこへ行ったか

#

アプリのdocker-compose.ymlのうち、CIに関係する部分を例にしたものです。実物にはもっと多くのサービスと、ずっと多くの環境変数があります。

services:
  valkey:
    image: valkey/valkey:8-alpine
    ports:
      - "6379:6379"

  # Host port 55432, not 5432, so it can't collide with a local Postgres.
  postgres:
    image: postgres:17-alpine
    environment:
      - POSTGRES_USER=myapp
      - POSTGRES_PASSWORD=myapp
      - POSTGRES_DB=myapp
    ports:
      - "55432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U myapp -d myapp"]
      interval: 5s
      retries: 10

  api:
    build: .
    command: python manage.py runserver 0.0.0.0:8000
    volumes:
      - .:/app
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://myapp:myapp@postgres:5432/myapp
      - REDIS_URL=redis://valkey:6379
    depends_on:
      postgres:
        condition: service_healthy
      valkey:
        condition: service_started

volumes:
  postgres_data:

checks.ymlのservices:ブロックと並べると、同じイメージが二つです。Postgres 17（こちらはAlpine版、CIはDebian版）とvalkey/valkey:8-alpine。いまの関係はこうです。Composeファイルは開発者が動かすもの。CIは同じイメージをサービスコンテナとして宣言し、開発者が打つのと同じコマンド、uv run …とnpm run …をランナー上で直接実行します。

2024年の記事と比べると、いちばん大事にしていた部分は残りました。CIツールは薄く、チェックもデプロイも自分で実行できるコマンドです。残らなかったのは、CIからComposeを呼ぶやり方です。

アプリのCIはDockerイメージをまったくビルドしません。イメージはデプロイのときにFlyのビルダーが一度だけビルドし、CIはコードが大丈夫かどうかだけ答えればよく、ツールチェーンがキャッシュされていればそれは6秒のインストールで済みます。それにComposeファイルは作業コピーをバインドマウントし、データを投入しますが、それはテストの実行がすることではありません。CI用に別のComposeファイルが必要になっていたはずで、それは同じサービスの二つ目の定義を手で揃え続けるということです。

そして2024年の例には、当時気づかなかったバグがありました。docker compose buildはイメージをビルドするだけで、サービスのcommandは実行しません。なので、あのファイルのnpm testはCIで一度も走っておらず、ワークフローはテストが通ろうが落ちようが緑でした。

あの記事がいちばん心配していたリスク、つまりCIベンダーの乗り換えは、結局起きませんでした。実際に起きた移行は反対側でした。このブログとクライアントのサイトがホスティング先をCloudflare Pagesに移し、ブログのほうは45行のワークフローを一つ新しく書くだけで済みました。ビルドがもともとコマンド一つだったからです。それから、私が警告していた300行のワークフロー。一つあります。pyhtml2textのものです。wheelをLinux、macOS、Windowsのランナーで、それぞれ複数のアーキテクチャ向けにビルドしなければならないので長いのですが、だからこそプラットフォーム固有のYAMLが正しい道具になる唯一の仕事でもあります。

キャッシュ：まずステップの所要時間を読む

#

GitHubはすべてのステップの所要時間を記録していて、gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobsで取り出せます。以下は10月20日の、アプリで最新の成功した実行です。

依存関係のキャッシュは二つとも有効で、どちらも安い部分です。GitHubがこのリポジトリ用に保持しているuvのキャッシュは200KBほどで、setup-uvがダウンロードし直せば済むものを整理してしまうからです。npmのほうは400MB近くあります。時間がかかっているのはテストで、テストはすでに4並列で走っています。実行を速くしたいなら、キャッシュではなくテストスイートに手を入れます。

ブログは正反対です。Hugoが処理した画像はgitignoreされたresources/_genにあるので、新しいランナーのたびにカバー、本文の画像、プレースホルダーを全部エンコードし直していました。後で載せるワークフローはactions/cacheでこれを復元します。キーは画像そのもののハッシュで、合わなければいちばん新しい古いキャッシュで代用します。Hugoは足りない分しか処理しないからです。キャッシュ導入前の最後の8回では、ビルドのステップに33〜76秒かかっていました。導入後の26回は6〜20秒で、例外は94秒の一回だけ。しかも同じコミットでプレースホルダーと二つ目のカードサイズを追加したうえでの数字です。

アプリのイメージはFlyのビルダーでビルドされ、依存関係のファイルをコードより先にコピーし、uvのダウンロードキャッシュはBuildKitのキャッシュマウント（RUN --mount=type=cache,target=/root/.cache/uv）に置いています。ただ、もっと大きな改善はキャッシュではありませんでした。以前の.dockerignoreはブロックリストで、追加のgit worktreeを置いたフォルダーを漏らしていました。それぞれが自分の依存関係とビルド成果物を抱えています。そのせいで27万7千ファイル、7.7GBが、デプロイのたびにビルダーへ送られていました。許可リストに書き直したいま、ビルドコンテキストは40MBほどです。パターンの例はこうです。

# Exclude everything, then let back in only what the Dockerfile COPYs.
*

!pyproject.toml
!uv.lock
!manage.py
!myapp
!static

# Rules match the whole relative path and the last match wins,
# so these re-excludes apply inside the allowed directories too.
**/__pycache__/
**/*.pyc
**/.DS_Store
**/*.log

シークレットはできるだけ少ない場所に

#

シークレットは三か所にあります。GitHub Actionsのシークレットはワークフローがすることのためのもので、二つのHugoリポジトリにはそれぞれCLOUDFLARE_API_TOKENが一つあるだけです。Flyのシークレットはアプリの実行時設定で、flyctl secrets setで入れ、Actionsを経由することはありません。そしてノートPCのgitignoreされた.envに、デプロイスクリプトがCloudflareのキャッシュを消すときに使うトークンがあります。

PyPIにはシークレットがそもそも要りません。pyhtml2textはトラステッドパブリッシングを使っています。GitHubがワークフローに発行する短命のOIDCトークンをPyPIが受け付けるので、リリースのジョブはid-token: writeを求めるだけで、リポジトリのシークレットのページは空です。漏れるものも、ローテーションするものもありません。

トークンには必要な分だけを与えます。GitHubにあるアプリのFlyトークンは、マシンの一覧を取るだけの定期チェック用なので、fly tokens create readonlyで作っています。Pagesのデプロイが求めるのはcontents: readとdeployments: writeだけで、それ以上はありません。

入力は直接スクリプトに入れず、必ずenv:を通します。OTAのワークフローは自由記述のリリースノートを受け取ります。これをrun:の中に${{ inputs.notes }}と書くと、bashが読む前にテキストがスクリプトにそのまま貼り込まれるので、引用符とセミコロンを含むノートはコードになってしまいます。環境変数として渡せば、データのままです。パターンの例です。

      - name: Publish
        env:
          OTA_API_TOKEN: ${{ secrets.OTA_API_TOKEN }}
          INPUT_PLATFORM: ${{ inputs.platform }}
          INPUT_ROLLOUT: ${{ inputs.rollout }}
          INPUT_NOTES: ${{ inputs.notes }}
        run: |
          args=("$INPUT_PLATFORM")
          [ -n "$INPUT_ROLLOUT" ] && args+=(--rollout "$INPUT_ROLLOUT")
          [ -n "$INPUT_NOTES" ] && args+=(--notes "$INPUT_NOTES")
          ./scripts/publish-ota.sh "${args[@]}"

GitHubの外に置いたままのキーもあります。ある定期レポートには、アプリのサインイン基盤に対する管理者権限を持つキーが必要です。なのでそのレポートは定期ワークフローから、Mac上の定期ジョブに移しました。ワークフローは手動の予備として残してあり、そのキーが要るセクションを除いて投稿します。

デプロイ：pushごとに、スクリプトで、タグで

#

Hugoサイトはpushのたびにデプロイ

#

ブログのワークフローを例にしたものです。初回だけPagesのプロジェクトを作るステップは省いています。

name: Deploy to Cloudflare Pages

on:
  push:
  workflow_dispatch:

env:
  HUGO_VERSION: "0.165.0"
  PAGES_PROJECT: my-site

concurrency:
  group: deploy-${{ github.ref }}
  cancel-in-progress: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v7
        with:
          submodules: true

      - uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: ${{ env.HUGO_VERSION }}
          extended: true

      # Processed images are gitignored; restore them so Hugo only
      # re-encodes what is new. An older cache still helps.
      - uses: actions/cache@v6
        with:
          path: resources/_gen
          key: hugo-resources-${{ hashFiles('content/**/*.jpg', 'content/**/*.png', 'assets/img/**') }}
          restore-keys: |
            hugo-resources-

      # A multilingual site has no root 404.html; without one, Pages
      # answers unknown paths with index.html and a 200.
      - name: Build
        run: |
          hugo --gc
          cp public/en/404.html public/404.html

      # ...

      - name: Deploy
        uses: cloudflare/wrangler-action@v4
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy public --project-name=${{ env.PAGES_PROJECT }} --branch=${{ github.ref_name }}

--branch=${{ github.ref_name }}によってmainが本番になり、ほかのブランチはどれもプレビューURLを得ます。クライアントのサイトのワークフローはこれと同じ形で、ビルドの前にrm -rf publicが一行加わっています。あちらはpublic/がコミットされているので、そうしないと削除したページがアップロードに残り続けるからです。

Hugoのバージョンはここでだけ固定しています。10月にパッケージマネージャーのアップグレードでノートPCのHugoが0.168に上がりましたが、これはテーマが対応する最新版より一つ新しいものです。デプロイは0.165のままで、何も起きませんでした。

そして、ビルドそのものがテストです。9月14日、あるブランチのプレビューデプロイが3回続けて失敗しました。そのブランチの記事が、Hugoのrefでまだ下書きの記事を指していたのです。CIは本番と同じように下書きを除いてビルドするので、リンク先は存在せず、HugoはREF_NOT_FOUNDで止まりました。その間もmainは普通にデプロイされ続けていました。

アプリのAPIはスクリプトでデプロイ

#

デプロイスクリプトの中心部分を例にしたものです。

IMAGE_LABEL="deploy-$(git rev-parse --short HEAD)-$(date +%Y%m%d%H%M%S)"

# Build first, then wake a spare machine, then roll out exactly that image.
flyctl deploy --config fly.toml --build-only --push --image-label "$IMAGE_LABEL"
curl -fsS --retry 5 https://myapp.fly.dev/health > /dev/null
flyctl deploy --config fly.toml --image "registry.fly.io/myapp:$IMAGE_LABEL"

そしてfly.tomlの対応する部分です。

[deploy]
  # max_unavailable only counts machines that are running,
  # which is why the script wakes one first.
  strategy = "rolling"
  max_unavailable = 1

イメージは一度だけビルドし、コミットと時刻からなるラベルを付けてFlyのレジストリに送り、そのラベルでデプロイします。なので、ロールアウトされるのはビルドしたものそのものです。

ゼロダウンタイムを実現しているのは、先に予備のマシンを起こしておくことです。max_unavailable = 1が数えるのは動いているマシンだけですが、アプリは暇なときに動いているマシンを一台も置きません（サスペンドしたマシンは1秒ほどで復帰します）。そのため、起きていた一台が寝ているマシンと同じバッチで置き換えられ、後ろに温まったマシンが一台もない、ということが起きていました。9月28日にオリジンへプローブを送り続けて測ったところ、素のflyctl deployではタイムアウトが7回と7.3秒の空白があり、先にビルドしてロールアウト開始時にはマシンを一台起こしておくスクリプトのデプロイでは、2,514リクエストで失敗はゼロでした。

スクリプトの残りは、エラーの通知が届くチームのチャットチャンネルにデプロイの印を残します。エラーが固まって出たとき、直前に何が変わったかと照らし合わせられるようにです。それからCloudflareのキャッシュを消し、マシンを温めておきます。Webフロントエンドはイメージをまったく通りません。それはフロントエンドとバックエンドを別々にデプロイするに書きました。

マイグレーションはパイプラインのステップではありません。Flyのrelease_commandが私の環境では固まってしまったので、新しいイメージで最初に起動したマシンがロックを取ってマイグレーションし、ほかのマシンは待ちます。そのため、どのマイグレーションもまだ動いているコードと両立しなければなりません。カラムはあるデプロイで追加し、次のデプロイで使うのをやめ、三回目のデプロイで削除します。

このスクリプトに、私のノートPCでなければならない部分は特にありません。ただ、ノートPCにしかないファイルがいくつかあって、それが縛りになっています。Cloudflareの認証情報と、最後に何をデプロイしたかの記録で、まっさらなランナーにはこれがありません。コミットしていない変更もデプロイしてしまい、チャットでそう知らせますが、Webのリリース用スクリプトは汚れた作業ツリーを拒否します。

ブランチごとのプレビュー環境で私は、これを手でやるのは自分一人なら構わないが、二人目の開発者からはgitで何かが起きたから起きるようにしなければならない、と書きました。アプリの開発者はまだ一人です。あの記事のブランチ環境のワークフローは、作ったときのブランチにそのまま置いてあります。

OTAのワークフローは手動専用です。公開は判断であるべきですし、アップデートのサービスは部分ロールアウトが開いている間は新しいリリースを拒むので、pushトリガーではカナリアのたびに引っかかってしまいます。このワークフローは一度も実行されたことがありません。これまでのOTAアップデートはすべてノートPCから、ワークフローが呼ぶのと同じスクリプトで出しています。薄いワークフローにする理由は一言でこれです。リリースをどう始めても、同じスクリプトです。

pyhtml2textはタグでリリース

#

リリースのジョブです。パッケージ名は一般的なものにしてあります。

  release:
    runs-on: ubuntu-latest
    if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
    needs: [linux, macos, windows, sdist]
    environment:
      name: pypi
      url: https://pypi.org/p/mypackage
    permissions:
      id-token: write       # trusted publishing and signing
      contents: write
      attestations: write
    steps:
      - uses: actions/download-artifact@v8
      - uses: actions/attest@v4
        with:
          subject-path: 'wheels-*/*'
      - uses: astral-sh/setup-uv@v10
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        with:
          prune-cache: true
      - name: Publish to PyPI
        if: ${{ startsWith(github.ref, 'refs/tags/') }}
        run: uv publish --trusted-publishing always 'wheels-*/*'

リリースのジョブはすべてのビルドジョブを待ち、実際に公開するのはタグのときだけです。手動実行はビルドとアテステーションまではしますが、何もアップロードしません。actions/attestはどのワークフローが各wheelをビルドしたかを記録し、uv publish --trusted-publishing alwaysはパスワードの代わりにOIDCトークンでアップロードします。パッケージそのものについては閉じられたプルリクエスト、フォーク、そしてPyPIパッケージに書きました。

定期ワークフローはベストエフォート

#

アプリには定期ワークフローが一つあります。Flyがベースラインより多くのマシンを起動していないかを見るチェックで、放っておけば請求書で初めて気づくことです。通知はわざと失敗することで行います。定期実行が失敗すると、GitHubが所有者にメールを送るからです。

設定はcron: '*/15 * * * *'、1日96回です。ところがこの2週間は1日3〜8回しか動いておらず、実行間隔の中央値は3時間40分ほどでした。GitHubのドキュメントが挙げる理由は負荷だけです。Actionsが混んでいると定期実行は遅れることがあり、混み具合によっては落とされることもある、と。持続的なスケールアウトを見るなら数時間で十分です。数分以内に鳴らなければならないものにとって、GitHubのcronは監視ではありません。

パイプラインに投げかけたい質問

#

これから作る人も、すでにあるものを見直している人も：

1. GitHub Actionsが丸一日止まったら、それでもリリースできますか？ できないなら、リリースのロジックがYAMLの中にあるということで、2024年の記事がまだ当てはまります。
2. CIは本番と同じインタープリタ、同じCPUアーキテクチャ、同じデータベースのメジャーバージョンで動いていますか？ 私のCIがコンパイラのバグを捕まえられたのは、ランナーと本番がどちらもx86_64で、ノートPCがそうではなかったからです。
3. まっさらなチェックアウトで通りますか？ 通らないとしたら、たいていは生成されてgitignoreされたファイルのせいです。
4. 実行時間は実際どこに使われていますか？ キャッシュを足す前に、ステップの所要時間を読んでください。
5. シークレットはそれぞれ何か所にありますか？ そして本当にGitHubに置く必要がありますか？

ひとつのアプリを作る小さなチームを思い浮かべてください。開発者は二人でも五人でも構いません。分野ごとの専門家ではなく、それぞれが自分のブランチで、データベースのマイグレーションから API を経てモバイルアプリの画面まで、機能をひとつ端から端まで受け持つ人たちです。チームの回し方としては良いやり方で、二人目の開発者が加わった瞬間から繰り返し起きる失敗がひとつあります。「今ステージング使ってる人いる?」というメッセージです。

そのメッセージの裏には、機能を作り終えてテスターやデザイナーに見せたいのに見せられない開発者がいます。ステージングには二人目の開発者のブランチが載っていて、dev には三人目のブランチが載っていて、そちらは二日前にログインを壊してから再デプロイされていません。数人、共有環境が二つ、そしてスケジュール調整を引き受けているチャットのスレッド。

これは人の問題ではありません。トポロジーの問題です。全員が環境を「自分のブランチが本物になる場所」として扱っているので、環境がマージのやるべき仕事をブランチひとつずつ順番に肩代わりし、残りの全員が列に並んでいるのです。

自分のスタックの本番の形は My Current Stack に書きました。Fly.io の最安マシン上の Django、コネクションプーラーの背後の Postgres、キャッシュと Channels レイヤー用の Redis、別立ての WebSocket アプリ、バックグラウンドワーカー、ファイル用の S3 互換バケット、ホスティング型の認証プロバイダー、前段の Cloudflare、そしてそれら全部と話すモバイルアプリです。この記事は、そのスタックを、どのブランチでも開発者が PR にラベルをひとつ付ければ数分のうちに HTTPS 付きの公開コピーを丸ごと手に入れられるものに変えた話です。他の誰かに頼むことも、誰かが用意してやることもありません。Postgres クラスタも Redis もバケットも、二つ目は用意しません。インフラは共有のままです。変わるのは、共有リソースのすべてが名前で切り分けられるようになることで、その名前はブランチから来ます。ここにチームの規模を前提にしたものはありません。開発者が二人でも二十人でも設計は同じで、増えるのはアプリの一覧だけ、それはスイーパーが面倒を見ます。作って、ブランチを三つ同時に動かして、予想していなかった二か所で壊して、片付けるまでを午後のうちに済ませました。以下の出力はその実行から取ったものです。

共有環境ひとつが開発者一人分より先に伸びない理由

#

共有 dev 環境には前提がひとつ焼き込まれています。全員が見たがる「現在のコードのバージョン」がひとつだという前提です。開発者が一人のとき、あるいはチームが変更の流れをひとつ歩調を合わせて進めているときは正しい。二人目の開発者が別のスケジュールで機能に着手した瞬間に正しくなくなり、端から端までのオーナーシップではそれがすべての機能で起きます。それ以降、環境が抱えるものはすべて取り合いになります。

• デプロイされたコード。 最後にデプロイした人が勝ちます。残りの人の作業は再デプロイするまで見えず、再デプロイすれば前の人のものが消えます。
• データベースのスキーマ。 各開発者が自分の機能のデータモデルを持つとき、いちばん強く噛みつく部分です。最初のブランチがカラムを足す。一時間後にデプロイされた二つ目のブランチはそれを知らず、ORM が insert で失敗し始める。あるいは両方のブランチが 0042_* マイグレーションを持っていて、共有データベースが誰のマイグレーション履歴とも一致しない状態になり、誰かがリセットして、三人目が午後いっぱいかけて用意したテストデータを消す。
• キャッシュ。 あるブランチのシリアライザ変更が、別のブランチのコードが読むのと同じ Redis キーの下にキャッシュされる。そこから出てくるバグ報告は不可解で、一件ごとに午前中がつぶれます。
• サードパーティ連携。 OAuth コールバックがひとつ、Webhook URL がひとつ、プッシュ証明書がひとつ。誰のブランチがデプロイされていようと、そのブランチがイベントを受け取ります。
• テスター。 デプロイされているものしかテストできないので、機能が準備できた順ではなく、環境がたまたま確保された順に一度にひとつずつテストします。

チームは予約システムで応じます。チャットのスレッド、ピン留めメッセージ、/claim staging ボット。それはロックです。作業を見せられる唯一の場所にかかったロックは、デリバリー速度にかかったロックです。開発者二人なら苛立つ程度です。三人なら良い週には耐えられます。四人目が加わるか、機能ひとつがデザイナーとの三日間のやり取りでステージングを握り続ければ、耐えられなくなります。

人が最初に手を伸ばす対処は三つ目の共有環境、「dev2」や「uat」です。数週間は稼げます。列が二車線になっただけです。

本当の対処は、dev もステージングもそもそも環境ではなかったと気づくことです。あれは 誰かのブランチの現在の状態に URL が付いたもの でした。それがそうなら、あるべき数は今チームが気にしているブランチの数で、あるべき寿命はブランチの寿命です。

モデル: ブランチが環境である

#

目標の状態はこうです。

この表の、誰が作り誰が壊すかをもう一度見てください。どれも git のイベントか時計です。git がコントロールプレーンです。存在すべき環境の集合は存在するブランチの集合からそのまま決まり、自動化の仕事は現実をそれに合わせておくことだけです。PR のラベルが作り、その後の push のたびに更新し、PR を閉じるかマージすると壊し、毎晩のジョブが前の三つの取りこぼしを片付けます。すべてのブランチが環境を得るわけでもありません。ラベルがゲートで、開発者のクリックひとつなので、バックアップの push やボットの依存関係更新は費用ゼロです。誰も環境を用意しません。チケットを受けた DevOps エンジニアでも、チャットで呼ぶボットでも、毎回プロンプトを打つ AI エージェントでもありません。十人目の開発者の最初のブランチも、一人目のブランチとまったく同じやり方で、PR にラベルが付いたという理由で環境を得ます。人に頼まなければならないなら、それはスケールしたのではなく、行列の場所が変わっただけです。

そしてこれを成り立たせる規則はひとつです。環境が触れるすべてのリソースは、ブランチにちなんで決定論的に名付ける。 開発者名でもチケット番号でもなく、誰かが開くまで存在しない PR 番号でもありません。ブランチです。開発者が実際に扱うのがブランチだから、そして名前が決定論的なら、同じブランチで ./scripts/env up を二度目に実行したとき、新しい環境を作る代わりに既に作った環境を見つけられるからです。

名前は人のためのスラッグと、一意性のための短いハッシュです。

branch=$(git rev-parse --abbrev-ref HEAD)              # feature/payments-retry
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20)
hash=$(printf '%s' "$branch" | sha256sum | cut -c1-6)
ENV="${slug%-}-${hash}"                                 # feature-payments-retr-3f9a1c

feature-payments-retr-3f9a1c が環境です。この文字列が Fly アプリ名、Postgres データベース名(ハイフンはアンダースコアに)、Redis のキー接頭辞、バケットのオブジェクト接頭辞、エラートラッカーの environment、そしてホスト名の左端のラベルになります。ブランチ名を知っている人なら誰でも計算できます。どこかを引く必要はありません。

その最後の一文が設計です。環境の台帳もコーディネーターもありません。env up、env down、ホスト名をルーティングする Cloudflare Worker、毎晩のスイーパーが、それぞれ独立にブランチから名前を計算し直し、構造的に一致します。特に Cloudflare は何も調整していません。Worker はホスト名から Fly アプリへの純粋関数で、環境が作られたことも消されたことも知りません。アプリがあればリクエストは届き、なければ Fly が自分のエラーで答えます。

ここから三つのことが出てきます。

第一に、「ステージング誰が使ってる」が問いでなくなります。feature-payments-retr-3f9a1c-dev.example.com があり、fix-login-redirect-8b21e0-dev.example.com があり、それぞれそのブランチにいる人のものです。

第二に、ステージングがゴミ捨て場ではなく本番の正直なリハーサルになります。本番に行くまさにそのイメージで、数分前に本番の形のスナップショットから複製したデータベースを相手に組まれます。そこで動けば、本番に残る変数は本番のデータだけです。

第三に、各開発者が共有リソースの root を持たずに力を得ます。ブランチ環境の爆発半径はそのブランチ環境です。四人目の新人が初日に自分のブランチに何をデプロイしようと、最悪の結果は自分のブランチが壊れることです。

fly.io/dashboard/my-org

物理的には共有、論理的には分離

#

「ブランチごとに環境」の魅力的な版は丸ごとコピーです。Postgres クラスタをひとつずつ、Redis をひとつずつ、バケットをひとつずつ。きれいですが、悪い取引です。Fly Postgres クラスタはマシンひとつにボリュームひとつにリストア一回で、Redis はもうひとつのマシン。環境ごとに数分待ち、遊んでいるデータベース十数個分を払うことになります。スイーパーが片付ける種類も一つではなく四つになります。

代わりに、各共有サービスはプレビュー組織全体で一度だけ、小さな本番くらいのサイズで用意し、すべての環境が $ENV をキーにその一切れを受け取ります。壁に貼っておきたい表です。

このうち二つには一言添えておきます。

Postgres: スキーマではなくデータベース。 クラスタひとつを切り分けるもうひとつの方法は、環境ごとにスキーマを持ち、接続ごとに search_path を設定することです。接続の options に -c search_path=... を押し込めば Django もやってくれますが、トランザクションモードのコネクションプーラーは指示しない限り起動時オプションを捨てますし、そうすると結局プール内のすべての接続がひとつの環境に属さなければなりません。「なぜ自分のクエリが違うテーブルに当たるのか」系のバグの温床で、環境ごとにデータベースならそもそも存在しない問題です。データベースは固い境界で、CREATE DATABASE ... TEMPLATE は数秒でひとつ作り、DROP DATABASE は何も残さず消します。ブランチ環境はプーラーを通さず 5433 番ポートで Postgres に直接つなぎます。本番のバックグラウンドワーカーと同じやり方です。プーラーは本番の同時実行数で元を取るもので、ブランチ環境がそれを見ることはありません。

シークレット: 共有ではなく生成。 dev 用シークレット一式を作って全環境にコピーすれば楽でしょう。やめましょう。env up スクリプトは環境ごとに新しい SECRET_KEY(セッション署名)、ENCRYPTION_KEY(保存時に暗号化するもの全部)、ENV_TOKEN(モバイルアプリが提示する bearer トークン、後述)を生成し、その Fly アプリのシークレットストアにだけ保存します。あるブランチのセッションクッキーは別のブランチでは無価値で、漏れたプレビュー用トークンが開くのはプレビューひとつだけで、開発者はわざわざ探さない限り値を見ることがありません。Fly だけでなく別のシークレットマネージャーにシークレットを置くなら、同じ規則が当てはまります。パスは myapp/preview/$ENV/ で、スイーパーが環境と一緒にそのパスを消します。環境をまたいで本当に共有されるシークレットは共有インフラ自体の認証情報(Postgres の管理者 URL、Redis の URL、バケットのキー)だけで、それらはどの環境でもなく CI に住んでいます。

Redis の行がいちばん疑いやすいので、試しました。ひとつの環境の中からキャッシュキーを入れ、もうひとつから読み、共有 Redis のすべてのキーを列挙します。

$ fly ssh console -a myapp-feature-profile-tagl-fa8832 -C "python manage.py shell -c \"from django.core.cache import cache; cache.set('who-am-i', 'tagline-branch', 600)\""
$ fly ssh console -a myapp-feature-profile-webs-dcb2e7 -C "python manage.py shell -c \"from django.core.cache import cache; print(cache.get('who-am-i'))\""
None

$ # every key in the shared Redis
  feature-profile-tagl-fa8832:1:who-am-i
  ...

同じ Redis、同じキー名で、もう一方の環境からは何も見えません。

この記事の残りは、あの八行に $ENV を刻印するスクリプトと、それを正直に保つ規則です。

./scripts/env up

#

開発者が自分のブランチから実行するスクリプトにすると、考え方の全体はこうなります。CI も同じスクリプトを実行します。勝手にずれていく CI 専用の経路はありません。ラップトップに必要なのは fly と git だけ。SQL は fly ssh 経由で Postgres アプリへ行き、環境の Redis キーとバケットのオブジェクトは消す前に環境自身のマシンが削除するので、ラップトップは gitignore された env ファイル以外に共有 Redis やバケットの認証情報を持ちません。要点になる行だけに絞ると、次のとおりです。

#!/usr/bin/env bash
# scripts/env up|down|name|url: one environment per branch on shared preview infrastructure
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; PG_APP=${PREVIEW_PG_APP:-myapp-preview-pg}; DOMAIN=${BASE_DOMAIN:-example.com}

branch=${BRANCH:-$(git rev-parse --abbrev-ref HEAD)}
[[ "$branch" == "main" ]] && { echo "main has staging, not a branch environment" >&2; exit 1; }
slug=$(printf '%s' "$branch" | tr '[:upper:]/_ ' '[:lower:]---' | tr -cd 'a-z0-9-' | cut -c1-20); slug=${slug%-}
ENV=${ENV_OVERRIDE:-${slug}-$(printf '%s' "$branch" | shasum -a 256 | cut -c1-6)}   # the sweeper passes the name
APP="myapp-${ENV}"; DB="env_${ENV//-/_}"; HOST="${ENV}-dev.${DOMAIN}"

pg() { fly ssh console -a "$PG_APP" -q -C "psql postgres://postgres:${PG_PASSWORD}@localhost:5433/postgres -At -c \"$1\""; }
exists() { fly apps list --org "$ORG" --json | grep -q "\"Name\": *\"$APP\""; }

up() {
  echo "== $branch -> $ENV"
  exists || fly apps create "$APP" --org "$ORG"                         # idempotent
  [[ "$(pg "SELECT 1 FROM pg_database WHERE datname='$DB'")" == "1" ]] || pg "CREATE DATABASE $DB TEMPLATE seed_template"

  have=$(fly secrets list -a "$APP" --json | grep -o '"Name": *"[^"]*"' | cut -d'"' -f4 || true)
  gen() { grep -qx "$1" <<<"$have" || echo "$1=$(openssl rand -hex 32)"; }   # generated once, never rotated by a later `up`
  { gen SECRET_KEY; gen ENCRYPTION_KEY; gen ENV_TOKEN
    echo "ENV_NAME=$ENV"; echo "ALLOWED_HOSTS=$HOST,$APP.fly.dev"
    echo "DATABASE_URL=postgres://postgres:${PG_PASSWORD}@${PG_APP}.flycast:5432/${DB}"
    # ... plus the shared Redis URL and bucket credentials
  } | fly secrets import -a "$APP" --stage

  fly deploy -a "$APP" --config fly.preview.toml --remote-only --ha=false \
    --build-arg GIT_SHA="$(git rev-parse --short HEAD)" --build-arg GIT_BRANCH="$branch"
  echo "https://$HOST"
}

down() {
  [[ "$APP" =~ ^myapp-[a-z0-9-]+-[0-9a-f]{6}$ ]] || { echo "refusing to destroy $APP" >&2; exit 1; }
  if exists; then
    fly machine start -a "$APP" >/dev/null 2>&1 || true                 # it may be suspended
    fly ssh console -a "$APP" -q -C "python manage.py teardown_env" || echo "warning: cleanup failed; the sweeper will catch it" >&2
    fly apps destroy "$APP" --yes
  fi
  pg "DROP DATABASE IF EXISTS $DB WITH (FORCE)" || true
}

case "${1:-}" in up) up ;; down) down ;; name) echo "$ENV" ;; url) echo "https://$HOST" ;; esac

デモでは push する代わりに自分のラップトップから走らせました。三つのブランチはリポジトリの履歴に残したくない使い捨てで、出力が流れるのを見ていたかったからです。チームで使うときは誰もこれを打ちません。後で出てくるラベルのワークフローがまさにこのスクリプトを走らせ、ここから先の出力は Actions のログに残るはずのものです。ツール自体を載せたブランチで最初に実行したときの出力です。

$ ./scripts/env up
== feature/branch-environments -> feature-branch-envir-c65cb4
New app created: myapp-feature-branch-envir-c65cb4
CREATE DATABASE
Secrets have been staged, but not set on VMs. Deploy or update machines in this app for the secrets to take effect.
==> Building image
image size: 139 MB
✔ Machine 1a2b3c4d5e6f78 [app] update finished: success
https://feature-branch-envir-c65cb4-dev.example.com

$ curl -s https://feature-branch-envir-c65cb4-dev.example.com/api/version/
{"environment": "feature-branch-envir-c65cb4", "branch": "feature/branch-environments", "commit": "a1b2c3d4", "region": "syd"}

コマンドから URL まで二分半ほどで、大半はイメージのビルドです。コミットをもうひとつ積んで同じブランチで二度目の up をすると、「New app created」も「CREATE DATABASE」も出ず、同じシークレット名をステージしつつ生成したものは作り直さず、リビルドしました。同じ URL、新しいコミット。

中の選択のいくつかは一文ずつ値します。

fly.preview.toml は fly.toml ではない。 本番は API、WebSocket サーバー、バックグラウンドワーカーを別々の Fly アプリとプロセスグループで動かし、それぞれが自分の指標でスケールするようにしていて、それがスタックの記事の主張のすべてです。ブランチ環境はスケールする必要がありません。マシンひとつであるべきです。だからプレビュー設定はプロセスがひとつです。コンテナのエントリーポイントにプレビュー用のモードを足し、マイグレーションを走らせてから WebSocket を有効にした ASGI サーバーをひとつ起動します。Channels はもともとひとつの ASGI アプリケーションの中で HTTP と WebSocket の両方をルーティングするので、プロセスひとつでアプリ全体を配信します。そのモードでは同期ビューが thread-sensitive で、だいたい一度にリクエストひとつずつ動きます。本番で自分が捨てたまさにその取引ですが、ここでは正確に正しい取引です。ブランチをテストする人は誰も気づかないからです。

# fly.preview.toml (the app name comes from `fly deploy -a`)
app = 'placeholder'
primary_region = 'syd'

[processes]
  app = "/app/entrypoint.sh preview"   # migrate, then one ASGI server for HTTP and WebSockets

[env]
  DJANGO_SETTINGS_MODULE = 'myapp.settings'
  DEBUG = 'False'

[http_service]
  internal_port = 8000
  force_https = true
  auto_stop_machines = 'suspend'
  auto_start_machines = true
  min_machines_running = 0
  [[http_service.checks]]
    path = '/healthz'
    [http_service.checks.headers]
      Host = '127.0.0.1'               # the app's own hostname isn't known to a static file

[[vm]]
  size = 'shared-cpu-1x'
  memory = '1gb'

auto_stop_machines = "suspend"、min_machines_running = 0。 昼食以降誰も開いていないブランチ環境の費用はゼロであるべきです。stop でなく suspend なら、30 秒のコールドスタートの代わりに 504 を追いかけて たどり着いた 3 秒ほどの再開が得られ、ここでは 30 秒でも許容できます。デモ環境三つのうち二つは、デプロイ完了の一分後には fly apps list で既に suspended でした。

fly.io/apps/myapp-feature-profile-tagl-fa8832

DEBUG = False、本番と同じ settings モジュール。 ブランチ環境は公開 URL です。テストに関わるすべての面(本物の HTTPS、本物のクッキー、同じヘルスチェック)で本番のように振る舞い、誰かを傷つけうるすべての面で本番と違うべきです。プレビュー用の設定ファイルを別に用意する代わりに、差分は env up が設定するシークレットが運びます。サンドボックスの決済キー、認証プロバイダーの管理者認証情報なし、そして以下のすべての接頭辞を有効にする ENV_NAME。

設定ひとつがすべてを切り分ける。 ENV_NAME は設定に新しく入った唯一のつまみで、四か所に適用されます。

ENV_NAME = os.getenv("ENV_NAME", "")
_prefix = f"{ENV_NAME}/" if ENV_NAME else ""

CACHES["default"]["KEY_PREFIX"] = ENV_NAME                           # every cache key
CHANNEL_LAYERS["default"]["CONFIG"]["prefix"] = f"{ENV_NAME}:asgi"  # Channels group and channel names
STORAGES["default"]["OPTIONS"]["location"] = f"{_prefix}media"      # uploads
STORAGES["staticfiles"]["OPTIONS"]["location"] = f"{_prefix}static"

channels の分を忘れると、二つのブランチの WebSocket サーバーがグループ名を共有し、ある環境で送ったメッセージが別の環境に現れます。一日を食う種類のバグです。

五か所目は、後から共有 Redis を読んで初めて見つけました。504 の記事の起動時ロック、つまりイメージごとにマシン一台がマイグレーションを走らせる間ほかが待つ仕組みは、イメージ参照をキーにしていました。同じコミットから組まれたブランチ環境二つは同じイメージを持ちます。二つ目は一つ目の「done」マーカーを見つけて、マイグレーションされていない自分のデータベースへの自分のマイグレーションを飛ばしていたでしょう。今は環境名がキーに含まれ、そのキーは接頭辞の下に住んでいます。共有インフラの設計が生み続ける種類の問題です。暗黙のうちに「デプロイごと」だったものはすべて明示的に環境ごとにしなければならず、何が暗黙だったかは見るまで分かりません。

データベースは空からマイグレーションするのではなく複製する。 次の節です。

データベース: 数秒で複製されるテンプレート

#

ブランチ環境のデータベースは三つのうちのどれかです。全員と共有。ここまで我々を連れてきたやり方です。空からマイグレーションしてフィクスチャでシード。決定論的ですが、フィクスチャが実物の形をしたデータに敵ったことはなく、いつも十八か月は古い。あるいは本番の形のスナップショットの複製。現実的な行数、フィクスチャが常に埋まっていると仮定していたカラムの現実的な null、空のテーブルでは一瞬で終わるが実物では四十分かかるマイグレーションが姿を現します。

三つ目を採り、二つ目は CI 専用のチェックとして残します。そして三つ目をブランチごとにやれるほど速くするのは、多くの人が存在を忘れている Postgres の機能です。

-- Nightly, on the preview cluster. Restore last night's prod backup into seed_raw,
-- run the anonymiser, then freeze it as a template nobody can connect to.
ALTER DATABASE seed_raw RENAME TO seed_template;
UPDATE pg_database SET datistemplate = true, datallowconn = false WHERE datname = 'seed_template';

-- Per branch, in the time it takes to copy the files:
CREATE DATABASE env_feature_payments_retr_3f9a1c TEMPLATE seed_template;

CREATE DATABASE ... TEMPLATE はクラスタ内のファイルレベルのコピーです。数ギガバイトなら pg_restore にかかる数分ではなく数秒です。複製中のテンプレートには開いた接続があってはならず、datallowconn = false がそれを強制します。夜間ジョブが生きているテンプレートの上にリストアするのではなく seed_raw に組んで最後にリネームするのもそのためです。

デモではテンプレートを本番ダンプからではなく手で作りました。fly proxy でプレビュークラスタにトンネルを掘り、manage.py migrate、それからリポジトリ自前のシードコマンドで、小さいながら現実的なデータ一式を入れました。十九メガバイト。ブランチが三つ上がるにつれてクラスタにその複製が三つ現れ、それぞれ 19 MB、それぞれ一秒未満でした。

$ fly ssh console -a myapp-preview-pg -C "psql ... -c '\l'"
             datname             | template | size
---------------------------------+----------+-------
 env_feature_branch_envir_c65cb4 | f        | 19 MB
 env_feature_profile_tagl_fa8832 | f        | 19 MB
 env_feature_profile_webs_dcb2e7 | f        | 19 MB
 seed_template                   | t        | 19 MB

プレビュークラスタは非マネージドの Fly Postgres ノードひとつ、1 GB ボリューム付きの shared-cpu-1x で、月に二ドルほどです。ブランチ環境はプライベートネットワークの .flycast 経由でつなぎます。公開されているものは何もありません。

匿名化は省略できません。本番データが -dev ホスト名で届く瞬間、それは本番データであってはなりません。名前、メール、電話番号、住所、自由記述、決済参照、トークン、すべてリネームの前に上書きします。匿名化が失敗したら前夜のテンプレートが残り、誰かにメッセージが飛びます。小さな仕事で、このアプローチ全体をプライバシー質問票に答える人が受け入れられるものにする、まさにその仕事です。

エントリーポイントがすべてのイメージの初回起動で migrate を走らせるので、ブランチ自身のマイグレーションがテンプレートの上に適用されます。「自分のマイグレーションは本番の形のデータで動くか」の最初の正直なテストで、誰かが URL を開く前に起きます。

ホスト名: ワイルドカードひとつ、Worker ひとつ、そしてドキュメントが教えてくれなかった二つのこと

#

すべての環境には公開の HTTPS ホスト名が必要で、「公開」が要点です。スマホを持ったテスター、別のネットワークのデザイナー、VPN を入れないプロダクトマネージャー。Fly はアプリごとに myapp-$ENV.fly.dev を無料でくれて、それだけでも動きます。ただ *.fly.dev ホスト名には問題が三つあります。送るには不格好で、前に Cloudflare がいないので本番にかけている保護がひとつも効かず、自分のドメインに置きたければ環境ごとに DNS レコードひとつと証明書ひとつを作ることになり、スイーパーの片付けものがひとつ増えます。

それを全部なくす版が、ワイルドカードひとつと Cloudflare Worker ひとつです。計画は *.dev.example.com でした。二つのことに止められ、どちらも同じ計画を立てる前に知っておく価値があります。

Universal SSL が覆うワイルドカードは一段だけ。 Cloudflare の無料証明書は example.com と *.example.com に発行されます。*.dev.example.com は覆いません。二段目のワイルドカードには月 10 ドルの Advanced Certificate Manager が要ります。feature-branch-envir-c65cb4.dev.example.com への最初のリクエストは、自分のものが何ひとつ動く前に SSL ハンドシェイク失敗で死にました。対処は環境を最初のラベルに置くことです。feature-branch-envir-c65cb4-dev.example.com。既にある証明書が覆い、既にあるプロキシ済みの *.example.com レコードが覆います。でっち上げのサブドメインを歩き回るスキャナー向けのシンクホールとして自分が置いたあのレコードです。だから環境に DNS は一切要りません。

Redirect Rules は Workers より先に走る。 ルートを置いたところ、すべての -dev ホスト名が Worker が動くことなく www のトップページへ 301 で答えました。シンクホールはゾーンレベルのリダイレクトルール「その他のサブドメインはすべて → www」で、Cloudflare のリダイレクトフェーズは Workers フェーズより前に実行されます。ルールに節がひとつ必要でした。and not ends_with(http.host, "-dev.example.com")。デプロイスクリプトが up で足し down で外します。誰かが手で編集したルールこそ忘れられるものだからです。

dash.cloudflare.com/…/example.com/rules/redirect-rules/…/edit

DNS 側は元からあったあのレコードです。

dash.cloudflare.com/…/example.com/dns/records

その二つを片付ければ、ルーティングは *-dev.example.com/* の Worker ひとつです。

// dev-router.js: <env>-dev.example.com -> myapp-<env>.fly.dev
const DEV_SUFFIX = "-dev.example.com";
const ENV_NAME = /^[a-z0-9-]+-[0-9a-f]{6}$/;   // slug-hash, as scripts/env names them

export default {
  async fetch(request) {
    const url = new URL(request.url);
    if (!url.hostname.endsWith(DEV_SUFFIX)) return new Response("not a dev hostname", { status: 404 });
    const env = url.hostname.slice(0, -DEV_SUFFIX.length);
    if (!ENV_NAME.test(env)) return new Response(`no such environment: ${env}`, { status: 404 });

    url.hostname = `myapp-${env}.fly.dev`;
    const upstream = new Request(url, request);
    upstream.headers.set("X-Forwarded-Host", request.headers.get("host") ?? "");

    const res = await fetch(upstream);
    const out = new Response(res.body, res);
    out.headers.set("X-Robots-Tag", "noindex, nofollow");   // a half-finished branch is not for search engines
    out.headers.set("X-Dev-Environment", env);
    return out;
  },
};

Cloudflare がワイルドカードで TLS を終端し、Worker がラベルから Fly ホスト名を計算し、マシンまでの区間は Fly 自身の *.fly.dev 証明書が覆います。WebSocket のアップグレードは fetch をそのまま通ります。そしてルートがゾーンにあるので、Cloudflare が本番にしてくれることはすべて使えます。WAF ルール、レート制限、ボット対策モード、そして Access。

dash.cloudflare.com/…/example.com/workers

ブランチ三つを同時に上げ、Worker ひとつ、各ホスト名が答えたもの。

すべての 200 には Worker が付けた X-Robots-Tag: noindex, nofollow と X-Dev-Environment: <env> が添えられていました。404 は Fly に尋ねる前に Worker 自身が返したものです。

Cloudflare Access は「公開」を「届くべき人に届く」に変える装置です。*-dev.example.com にアプリケーションひとつ、「@example.com のメールなら誰でも」というポリシーひとつで、ブラウザからの訪問者はログインページを一度見て二度と気にしなくなります。ラップトップのデザイナー、PM、テスターはそれで済みます。デモには入れませんでした。環境は一時間、noindex を付けてシードデータ以外何もない状態で上がっていました。

モバイルアプリは覆えません。ネイティブアプリは Access のログインリダイレクトを完了できないからです。道は二つ。Access はログインを迂回するサービストークン(CF-Access-Client-Id / CF-Access-Client-Secret のヘッダー対)をサポートしていて、モバイルアプリの dev メニューが dev ホスト名用の一対を持てます。あるいはもっと単純に、/api/ に Access の迂回を入れ、ログイン済みのユーザーか環境の ENV_TOKEN、つまり env up がまさにこの環境のために生成したあのトークンのどちらもないリクエストを Django が拒否するようにします。どちらでも、モバイル側はベース URL とトークンの二つのフィールドを持つ dev メニュー画面で、テスターが既にインストールしているアプリがそのブランチと話すようになります。新しいビルドは要りません。OTA(無線)更新チャネルはアプリがビルドされたときのものを指したままで、API のベース URL はビルド時ではなく実行時の設定であり、元々そうあるべきでした。

認証は意図的に共有する唯一の共有サービスです。identity は環境ごとのものではありません。テスターはどのブランチでも同じアカウントでログインしたい。承認済みドメインに example.com を入れた、認証プロバイダーの dev プロジェクトひとつがすべての -dev ホスト名を覆い、すべての環境がそれに対して ID トークンを検証します。各環境のデータベースのユーザーテーブルはテンプレートのユーザーのコピーなので、テスターのアカウントはテンプレートにあったすべての場所にあります。

GitHub Actions でプレビュー環境を自動化する: イベントが入り、環境が出る

#

上のすべてを手でやるのは、やるのが自分だけなら構いません。二人目の開発者がいる時点で、誰かが覚えていたからではなく git で何かが起きたから起きなければなりません。自動化の全体はワークフロー四つ、リポジトリ設定ひとつ、ルールセットひとつ、GitHub environment ひとつで、そのどれもが git イベントを、開発者が手で走らせるのと同じ scripts/env の呼び出しに対応させます。勝手にずれる CI 専用の経路はありません。

ラベル、push、delete のワークフロー

#

# .github/workflows/branch-env.yml
name: branch environment
on:
  pull_request:
    types: [labeled, unlabeled, synchronize, closed]
  delete:
  workflow_dispatch:
    inputs:
      branch: { description: branch to bring up without a PR, required: true }

concurrency:
  group: env-${{ github.head_ref || github.event.ref || inputs.branch }}
  cancel-in-progress: true

env:
  FLY_API_TOKEN: ${{ secrets.FLY_PREVIEW_TOKEN }}   # org-scoped deploy token; a separate preview org keeps it away from prod
  PG_PASSWORD: ${{ secrets.PREVIEW_PG_PASSWORD }}
  # ... the shared Redis URL and bucket credentials, the same way

jobs:
  up:
    # the gate: a PR carrying the `env` label, or someone asking for a branch by hand
    if: >-
      github.event_name == 'workflow_dispatch' ||
      (github.event_name == 'pull_request' && github.event.action != 'closed'
        && contains(github.event.pull_request.labels.*.name, 'env'))
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { ref: "${{ github.head_ref || inputs.branch }}" }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - id: env
        env: { BRANCH: "${{ github.head_ref || inputs.branch }}" }
        run: scripts/env up && echo "url=$(scripts/env url)" >> "$GITHUB_OUTPUT"
      - if: github.event_name == 'pull_request'
        uses: marocchino/sticky-pull-request-comment@v2
        with:
          header: env
          message: "Branch environment: ${{ steps.env.outputs.url }}"

  down:
    # label removed, labelled PR closed or merged, or the branch itself deleted
    if: >-
      (github.event_name == 'pull_request' &&
        ((github.event.action == 'closed' && contains(github.event.pull_request.labels.*.name, 'env')) ||
         (github.event.action == 'unlabeled' && github.event.label.name == 'env'))) ||
      (github.event_name == 'delete' && github.event.ref_type == 'branch')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: BRANCH="${{ github.head_ref || github.event.ref }}" scripts/env down

ゲートは env ラベルで、ここは自分がいちばん強く主張したい部分です。ゲートがないと、すべてのブランチがアプリひとつとデータベースの複製ひとつの費用を払います。ラップトップのバックアップ代わりに push したブランチ、明日 squash されるスパイク、ボットが午前三時に開いた依存関係の更新まで。だから push だけでは何も起きず、PR を開くだけでも何も起きません。PR に env を付けると環境が立ち上がり、ラベルが付いている間は push のたびに更新され、ラベルを外すか PR を閉じるかマージすると落ちます。オプトインは依然として GitHub のイベントであって人への依頼ではなく、誰かが見るかどうかを知っている唯一の人がするクリックひとつです。固定コメントがユーザーインターフェースです。PR にラベルを付けると、誰にでも送れる URL 付きのコメントが現れ、push のたびに積み上がるのではなくその場で更新されます。PR ができる前に立ち上げたいブランチは workflow_dispatch が、残りはラップトップからの ./scripts/env up が受け持ちます。

知っておく価値のあるゲートが他に二つあります。ブランチ名のフィルタ (branches: ['feature/**', 'fix/**']) は PR が要りませんが、すべての機能ブランチが費用を払います。「ドラフトでないすべての PR」はいちばん自動的で、チームが PR を遅く、準備できたときにだけ開くなら正しい選択です。自分がラベルを選んだのは、費用の判断を文脈を知っている人に置けることと、何も閉じずに取り消せることからです。気に入っている副作用がひとつ。フォークからの pull_request の実行にはシークレットが渡らないので、フォークは環境を立ち上げられません。

concurrency は見た目以上に重要です。ひとつのブランチへの立て続けの push は、先行のデプロイと競走させるのではなく取り消します。同じアプリへの fly deploy が二つ同時に走ると、片方が負ける結果になります。

PR があったものは、マージされたかどうかにかかわらず closed が片付けを受け持ちます。delete イベントは workflow_dispatch で立ち上げて結局 PR ができなかったブランチのための保険で、ブランチが実際に削除されたときにしか発火しません。それはリポジトリ設定 Automatically delete head branches で、既定ではオフです。オンにしておけば、Merge を押すことが PR を閉じてブランチを削除するので、どちらのイベント単独でも env down が走っていたはずです。マージボタンが片付けです。

gh api -X PATCH repos/org/myapp -f delete_branch_on_merge=true

FLY_PREVIEW_TOKEN がこのファイルで危険な行です。アプリを作り消せるので、$APP がブランチ環境以外の何かになった瞬間に本番を消せてしまいます。ガードは二つで、両方残します。トークンを別の Fly 組織に限定し、本番組織を文字どおり見えなくすること(デモでは新しい組織に課金情報を付ける手間を省くため本番組織を使い、二つ目のガードだけに頼りました)。そして down() が slug-hash パターンに合わないアプリ名をすべて拒否すること。

ブランチ環境が自分ではできないチェック

#

ブランチは自分のマイグレーションしか見ません。だから肝心のチェックは pull request で main をマージした状態に対して走り、main が要求する唯一のステータスチェックです。

# .github/workflows/migrations-check.yml
name: migrations
on:
  pull_request:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:18
        env: { POSTGRES_PASSWORD: ci, POSTGRES_DB: ci }
        ports: ['5432:5432']
        options: --health-cmd pg_isready --health-interval 5s --health-retries 10
    env:
      DATABASE_URL: postgres://postgres:ci@localhost:5432/ci
      SECRET_KEY: ci-only
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-python@v5
        with: { python-version: '3.14' }
      - run: pip install -r requirements.txt
      - name: Merge main into the branch (a conflict here fails the check too)
        run: |
          git config user.email ci@example.com && git config user.name ci
          git merge --no-edit origin/main
      - name: One leaf in the migration graph
        run: python manage.py makemigrations --check --dry-run
      - name: The full chain applies from nothing
        run: python manage.py migrate --noinput

三十秒。0042 / 0042 の衝突をリリース当日の驚きから二人目の開発者の PR の赤いチェックに変えるのがこれです。下のマイグレーションの節で実際に発火するところを示します。

main の規則

#

ブランチが一か月生きたり、誰かが main に直接 push したりすれば、このどれも持ちません。規則は保護というより、環境を小さく、マイグレーションを最新に保つためのものです。

• main は保護され、常にデプロイ可能。 現在の main に対して migrations チェックが緑の PR でだけマージします(strict なステータスチェックなので、先週緑だった PR は main が動けば再実行されます)。線形履歴、force-push 禁止、削除禁止。
• 機能ブランチは短い。 二週間開いているブランチは main より二週間遅れた環境と、他人のものと衝突する確率が二週間分高いマイグレーションを持ちます。一か月がかりの機能はフラグの裏で小分けに main へマージします。長生きするのはフラグであってブランチではありません。
• ブランチひとつ、環境ひとつ、データベースひとつ。 既に命名が強制しています。
• 本番に行くのはリリースタグだけ。 イメージはタグから一度組まれ、ステージングと本番はそのイメージを動かします。リビルドはしません。
• migrations/ に触れる PR は残りの二人のどちらかがレビューする。 後述。

ルールセットとしては、gh api -X POST repos/org/myapp/rulesets --input ruleset-main.json で一度だけ適用します。

{
  "name": "main", "target": "branch", "enforcement": "active",
  "conditions": { "ref_name": { "include": ["~DEFAULT_BRANCH"], "exclude": [] } },
  "rules": [
    { "type": "deletion" },
    { "type": "non_fast_forward" },
    { "type": "required_linear_history" },
    { "type": "pull_request",
      "parameters": { "required_approving_review_count": 1, "dismiss_stale_reviews_on_push": true,
                      "required_review_thread_resolution": true } },
    { "type": "required_status_checks",
      "parameters": { "strict_required_status_checks_policy": true,
                      "required_status_checks": [ { "context": "check" } ] } }
  ]
}

正直なひっかかりがひとつ。このリポジトリは GitHub Free プランのプライベートリポジトリで、Free ではブランチ保護とルールセットはパブリックリポジトリでしか使えません。API は 403 Upgrade to GitHub Pro or make this repository public と答えます。delete_branch_on_merge 設定、environment、ワークフローは Free でもすべて動きます。だからプライベートな Free リポジトリの小さなチームにとって、上のルールセットは慣習です。migrations ワークフローは変わらず走り、変わらず赤くなりますが、マージボタンを灰色にするものはありません。月 4 ドルの判断で、自分なら二人目がマージできるようになった瞬間にそうします。

develop ブランチも release/* ブランチもありません。Git-flow は統合が高くつき、まとめてやらざるを得ないという前提で設計されました。ブランチ環境が統合を安くするので、まとめる必要が消えます。

ステージングはタグの環境で、本番は昇格

#

ステージングは仕組み全体を再利用します。main の v* タグがブランチ名 staging/v1.42.0 で scripts/env up を走らせ、命名がそれを staging-v1-42-0-<hash> に変えます。同じテンプレート複製のデータベース、同じ放置で suspend されるマシン、同じホスト名の体系。違うのはその後です。

# .github/workflows/release.yml (abridged)
on:
  push:
    tags: ['v*']
jobs:
  staging:
    steps:
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env up
      - run: echo "image=$(fly image show -a "myapp-$(BRANCH=staging/$GITHUB_REF_NAME scripts/env name)" --json | jq -r '…')" >> "$GITHUB_OUTPUT"
  production:
    needs: staging
    environment: production        # required reviewer on this environment = the promotion gate
    steps:
      - run: fly deploy --config fly.api.toml --image "${{ needs.staging.outputs.image }}"
      - run: fly deploy --config fly.ws.toml  --image "${{ needs.staging.outputs.image }}"
      - run: BRANCH="staging/${GITHUB_REF_NAME}" scripts/env down

production ジョブは必須レビュアーのいる GitHub environment を待ちます。誰かがステージングを見て Approve を押すと、本番はステージングが動かした同じイメージを参照で受け取ります。リビルドではありません。最後のステップがステージングを消すのは、役目を終えたからです。誰も承認しなければリリース候補は却下されたということで、その「ブランチ」(staging/v1.42.0 は origin に存在したことがない)が生存チェックに落ちたときにスイーパーがステージングを片付けます。スイーパーが確認できる理由なしには何も存在できません。

毎晩のスイーパー

#

# .github/workflows/sweep-envs.yml
on:
  schedule:
    - cron: '0 14 * * *'     # 02:00 NZST
  workflow_dispatch:
jobs:
  sweep:
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: superfly/flyctl-actions/setup-flyctl@master
      - run: scripts/sweep-envs

fetch-depth: 0 なのは、スイーパーが Actions が既定でチェックアウトする一コミットではなく、すべてのリモートブランチとその最終コミット日時を必要とするからです。workflow_dispatch はインシデントの後に手で走らせられるようにするためです。

開発者が実際にすること

#

ブランチを push し、PR を開き、誰かに見てほしくなったら env ラベルを付ける。リストはそれだけです。三分以内に PR に URL が現れ、push のたびに更新され、PR がマージされるか閉じられれば消えます。チームメイトと衝突していれば、マイグレーションチェックが誰より先に教えてくれます。取り合うステージングがないので誰もステージングを取り合わず、片付けがマージそのものなので誰も何も片付けません。

そして、これを組んだ人がその後ブランチごとにやることは、何もありません。共有の Postgres、Redis、バケットは一度だけ用意し、シークレットは Actions に一度だけ入れ、そこから先に繰り返す作業といえば月曜にスイーパーのログを読むことくらいです。チケットの列も、呼ぶボットも、プロンプトを打つ相手もありません。

片付けを信用しない片付け

#

env down が通常の場合で、面白いのは誰が掃除するかです。Redis のキーとバケットのオブジェクトは共有サービスのもので、down を走らせるラップトップはどちらの認証情報も要りません。環境自身のマシンが既にそれを持ち、自分の接頭辞を既に知っているからです。だから down はマシンが suspend されていれば起こし、そこで小さな後片付け用のコマンドを走らせ、その後で初めてアプリを消しデータベースをドロップします。環境が自分で後片付けをします。

$ BRANCH=feature/profile-website ./scripts/env down
redis: deleted 0 keys under feature-profile-webs-dcb2e7:*
bucket: deleted 278 objects under feature-profile-webs-dcb2e7/
Destroyed app myapp-feature-profile-webs-dcb2e7
DROP DATABASE

$ curl -s -o /dev/null -w '%{http_code}\n' https://feature-profile-webs-dcb2e7-dev.example.com/api/version/
530

530 は調整についての要点をもう一度示しています。Worker は変わらずホスト名をルーティングし、Fly には何もなく、誰も Cloudflare に知らせる必要がありませんでした。

この後片付けのコマンドは ENV_NAME なしでは実行を拒否します。接頭辞が空なら共有バケットの全消去になってしまうからです。そのガードこそ、これがシェルスクリプトの三行ではなくアプリ内のコマンドとして存在する理由のすべてです。

それでも環境は漏れます。GitHub Actions の障害中にブランチが削除される。開発者が試作のためにラップトップから env up を走らせ、push はしないまま。fly apps destroy が一時的に失敗して || true が飲み込む。三か月後にアプリが四十個あり、誰かに何が起きたのかと問わせる請求書が来ます。

だから一つ目を信用しない二つ目の仕組みがあります。上の表の毎晩のスイーパーです。すべての myapp-* アプリを列挙し、それぞれがどのブランチのものか割り出し、ブランチが消えたか七日間 push のないものをすべて消します。一週間放置されたブランチに生きた URL は要らず、次の push が二分で作り直します。ハッシュは逆算できないので、スイーパーは生きているすべてのブランチの環境名を計算し、その集合にないアプリをすべて消してから、背後にアプリのない env_* データベースをドロップします。

#!/usr/bin/env bash
# scripts/sweep-envs: nightly
set -euo pipefail
ORG=${PREVIEW_ORG:-myapp-preview}; TTL_DAYS=${TTL_DAYS:-7}
cutoff=$(( $(date +%s) - TTL_DAYS*86400 ))

git fetch --prune --quiet origin
live=""
while IFS=$'\t' read -r ts branch; do
  [[ "$branch" == "main" ]] && continue
  (( ts >= cutoff )) || continue
  live+="$(BRANCH="$branch" scripts/env name)"$'\n'
done < <(git for-each-ref --format='%(committerdate:unix)%09%(refname:short)' refs/remotes/origin | sed 's#^\([0-9]*\)\torigin/#\1\t#')

apps=$(fly apps list --org "$ORG" --json | grep -o '"Name": *"myapp-[^"]*"' | cut -d'"' -f4)
for app in $apps; do
  env="${app#myapp-}"
  [[ "$env" =~ ^[a-z0-9-]+-[0-9a-f]{6}$ ]] || continue       # not a branch environment (e.g. myapp-preview-pg)
  grep -qx "$env" <<<"$live" && continue
  echo "sweeping $app: branch gone or idle > ${TTL_DAYS}d"
  ENV_OVERRIDE="$env" scripts/env down || true
done
# ...then any env_* database with no app: DROP DATABASE.

デモのブランチはどれも push されたことがなかったので (上のラップトップでの実行です)、スイーパーから見ればすべて消えたものでした。誰かがラップトップから立ち上げて結局 push しなかったスパイクが一週間後に置かれる状態が、まさにこれです。残りの二つを、tagline 環境が書き込んだ Redis キーも含めて解体しました。

$ ./scripts/sweep-envs
sweeping myapp-feature-branch-envir-c65cb4: branch gone or idle > 7d
redis: deleted 0 keys under feature-branch-envir-c65cb4:*
bucket: deleted 322 objects under feature-branch-envir-c65cb4/
Destroyed app myapp-feature-branch-envir-c65cb4
DROP DATABASE
sweeping myapp-feature-profile-tagl-fa8832: branch gone or idle > 7d
redis: deleted 3 keys under feature-profile-tagl-fa8832:*
bucket: deleted 278 objects under feature-profile-tagl-fa8832/
Destroyed app myapp-feature-profile-tagl-fa8832
DROP DATABASE

$ fly apps list --org myapp-preview | grep myapp-
 myapp-preview-pg │ myapp-preview │ deployed

(小さく噛まれたことがひとつ。macOS には連想配列のない bash 3 が付いてきます。スイーパーの最初の版はそれを使っていて、自分のラップトップで declare -A で死にました。上の版は改行区切りのリストを使い、どこでも動きます。)

費用は楽しい部分です。suspend されたマシンは rootfs 分だけで、月に数セント。データベースは既に払っているボリューム上の 19 MB。Redis は従量課金プランで、十万コマンドあたり 20 セント、ブランチテストの規模ではゼロに丸まります。バケットの接頭辞は保存した分だけ。共有 Postgres ノードが唯一の固定費で、月に二ドルほど。アクティブなブランチ二十本で常時稼働の shared-cpu-1x 一台分くらいで、スイーパーがそれを二百ではなく二十に保ちます。デモ全体、つまり一時間の環境三つと共有部品は、その間に飲んだコーヒーより安くつきました。

ブランチをまたぐマイグレーション、警告してくれる共有データベースなしで

#

各開発者が機能を端から端まで持つなら、すべてのブランチにマイグレーションが入っています。だからこの節が重要な節です。

共有環境の世界を離れるときに人が見落とすことがあります。全員がひとつの dev データベースにデプロイしていたとき、マイグレーションの衝突は即座に痛く表面化しましたが、ともかく表面化しました。マイグレーションがひとつ走り、次のデプロイが失敗し、誰かがその日の午後に直した。ブランチごとにデータベースがあると、各マイグレーションは自分の環境で完璧に動き、二つは二つ目が main にマージされたときに初めて出会います。不注意にやれば、衝突は安かった dev から安くないリリースへ移ります。

規則は四つ、すべて CI で強制できるので誰も覚えておく必要がありません。

1. main をマージした状態でマイグレーショングラフの葉が二つなら CI が失敗する。 makemigrations --check はモデルとマイグレーションの食い違いを捕まえますが、肝心の衝突は二つのブランチが両方とも 0042_* を足していることです。ブランチ単体ではなく、main にマージしたブランチに対して確認します。

git fetch origin main
git merge --no-commit --no-ff origin/main || { echo "merge conflict"; exit 1; }
python manage.py makemigrations --check --dry-run
python manage.py migrate --plan 2>&1 | grep -q "Conflicting migrations" && exit 1

これは自分でわざと起こしたものです。デモブランチ三つのうち二つ、feature/profile-tagline と feature/profile-website が、それぞれマイグレーションひとつでユーザープロフィールのモデルにフィールドをひとつ足し、各環境は上がる途中で自分のものを適用しました。新しいカラムはあるべき場所にだけありました。

env_feature_branch_envir_c65cb4      (no new column)
env_feature_profile_tagl_fa8832      tagline
env_feature_profile_webs_dcb2e7      website

両方とも 0042_* です。どちらのブランチも相手のものを見られないので、どちらの環境も問題があるとは教えてくれません。片方をもう片方にマージすると、チェックが教えてくれます。

$ git merge --no-commit --no-ff feature/profile-tagline
$ python manage.py makemigrations --check --dry-run
CommandError: Conflicting migrations detected; multiple leaf nodes in the migration graph:
  (0042_profile_tagline, 0042_profile_website in accounts).
To fix them run 'python manage.py makemigrations --merge'

$ python manage.py makemigrations --merge --noinput
Created new merge migration accounts/migrations/0043_merge_20260919_0324.py
    dependencies = [
        ('accounts', '0042_profile_tagline'),
        ('accounts', '0042_profile_website'),
    ]

二人目の作者が自分のブランチで、自分の環境で、誰の邪魔もせずにその --merge を走らせ、次の env up が自分の複製の上に 0043 を適用します。(この場合、git が先にテキストの競合も報告しました。両方のフィールドがモデルファイルの同じ行に足されていたからです。現実的で、テキストの競合が解消されるまでマイグレーションの衝突を隠すことは知っておく価値があります。)

2. マイグレーションは前のリリースのコードと後方互換である。 デプロイ中には新しいスキーマと古いコードが共存する窓があり、マシンがロールバックすればその逆もあります。カラムは nullable かデフォルト付きで足し、一度にリネームせず、現在のリリースがまだ読むものは決してドロップしない。足して、デプロイして、バックフィルして、コードを切り替えて、後のリリースでドロップする。expand and contract です。ここでより重要になる理由は、使い捨て環境がデプロイを頻繁にし、その窓の中にいる時間が増えるからです。タグごとのステージングがそれをリハーサルする場所です。

3. CI は空のデータベースにゼロからのマイグレーションもする。 テンプレートの複製は「自分のマイグレーションが現実的なデータに適用できるか」をテストします。空からの実行は「チェーン全体がまだ無から動くか」をテストし、前のデータマイグレーションが何かを埋めたと仮定していたマイグレーションを捕まえます。三十秒で、さもなければ次の新しいラップトップを待つ類のバグを捕まえます。

4. スキーマ変更には二つ目の目が付く。 小さなチームに CODEOWNERS ファイルは要りませんが、規則は要ります。migrations/ に触れる PR はマージ前にチームの誰かがレビューし、レビュアーの仕事は SQL を確認することではありません。自分かチームの他の誰かがこの二週間で同じテーブルに触れているかを知っていて、そう言うことです。開発者が十数人を超えるとその知識はひとりの頭に収まらなくなるので、そこで migrations/ への CODEOWNERS の記述が元を取ります。どんなツールもこれの代わりにはなりません。機械的なものはツールが全部捕まえてくれるので二分の仕事で、古い共有環境の世界で残す価値のある唯一の部分です。二人が衝突しかけていると気づく瞬間。

バージョニング、URL が何を動かしているか語るように

#

共有環境がひとつのとき、「ステージングに何が載ってる」はチャットで飛び交う質問でした。複数になれば環境の属性でなければならず、さもなければすべてのバグ報告が考古学から始まります。

• すべてのイメージがコミット SHA を持ち、アプリがそれを公開する。 fly deploy --build-arg GIT_SHA=... --build-arg GIT_BRANCH=... がイメージに環境変数として刻み、/api/version/ が環境名とリージョンと一緒に返します(上の出力参照)。「feature-profile-tagl-fa8832 で壊れてる」に対して誰もが最初にするのは、思っているコミットを動かしているかの確認です。最初のデモ環境はツールがコミットされる一コミット前の作業ツリーからデプロイされていて、エンドポイントがそう言いました。返ってきたのは期待した SHA ではなく、ひとつ前のコミットでした。
• ENVIRONMENT=$ENV がすべてのログ行とエラートラッカーの environment タグにある。 ブランチのエラーが本番のエラー追跡を汚さず、ワンクリックで絞り込めます。
• ブランチは SHA を、リリースはタグを持つ。 feature-payments-retr-3f9a1c にバージョン番号はありません。コミットがあります。ステージングと本番には v1.42.0 があります。
• モバイルアプリは URL ではなく最小 API バージョンを持つ。 dev メニューの URL フィールドがテスターが実機をブランチに向ける方法で、API スキーマバージョンを載せたバージョン確認用のエンドポイントが、アプリが理解できる相手と話しているかを知る方法です。

これで解決しないこと

#

一緒でなければ意味をなさない二つの機能は解決しません。ブランチ環境はブランチひとつを見せます。答えは両方をフラグの裏でマージして main を見ることで、main を追いかける常設環境ひとつ(main-dev.example.com、マージのたびに再デプロイ)でできます。自分が残す唯一の長生きする非本番環境で、誰もそこへデプロイはしません。次のリリースが何になるかを見るためのものです。

登録済みコールバックを求めつつワイルドカードを受け付けないプロバイダーは解決しません。私が使っている認証プロバイダーは親ドメインを受け付けるので、example.com がすべての -dev ブランチホスト名を覆います。一部の OAuth や決済プロバイダーはそうではなく、その場合は Worker が最後に確保した環境へルーティングする共有ホスト名をひとつ置きます。小さなものにかかった小さなロックで、すべてにかかったロックよりずっとましです。

マイグレーションの人間側は解決しません。ツールは機械的な衝突を捕まえます。同じ二週間に二人が同じ概念を両立しない形でモデリングするのは捕まえられず、それを直す唯一の方法は、どちらかが気づくマイグレーションレビューです。

あなたの環境で確かめてみること

#

共有の dev やステージングがあり、それを予約するチャットのスレッドがあるなら:

1. 完成したブランチが、作者以外の誰かに動いているところを見てもらえるまでどれだけ待ちますか? 一時間を超えるなら、そのロックの代金をデリバリー時間で払っていて、小さなチームならその大きな割合が待っています。
2. 共有データベースはどれくらいの頻度でリセットされ、そのとき誰が作業を失いますか?
3. 新しい開発者が初日に、誰にも何も頼まずに自分のブランチが動く公開 URL を手に入れられますか? 頼まなければならないものが何であれ、それが最初に自動化するものです。
4. 新しい環境は現実的なデータから始まりますか? 空から始まるなら、最初に捕まえ損ねるバグは、空のテーブルでは平気で実物のテーブルでは四十分かかるマイグレーションです。
5. 非本番のホスティングに、全員が忘れて一か月経ってもまだ存在するものがありますか? あるなら、何より先にスイーパーを書いてください。漏れは初日から始まります。

チャットのあの質問が消えるのは、人が尋ねるのをやめたからではなく、答えがいつも「使ってますよ、自分のを」だからです。

開示。 この移行と記事の執筆には Codemagic から報酬を受けています。Codemagic のレビューは事実関係の確認だけで、論調には及ばず、先方の要望で書き換えた箇所はありません。問題にぶつかって報告した箇所はそう書いていますし、あなたが読む時点で直っているものは、直ったものとして書いてあります。

2026年9月23日追記。 私が報告した問題には、Codemagic の開発者が順に対応してくれました。iOS のバージョン検出のバグ、二重に数えられたインストール、無音の初回セットアップ、うるさいデバッグコマンドを含めて大半はすでに修正済みで、ドキュメントにもコミット済みのネイティブプロジェクトの扱いとクラッシュ時のロールバックまでの予算が載りました。本文ではそれぞれ該当する箇所でそう書き添え、まだ残っているいくつかは元のままにしています。

2026年10月16日追記。 Patch に移ってから初めてのネイティブのアップグレード（Expo SDK 58）で、Patch の設定がまったく入っていない Android のリリースビルドができあがり、しかもどこもエラーを出しませんでした。何が起きたのかと、ファイル1つで済んだ修正は 初めてのネイティブアップグレード に書きました。

2月に、Expo のアップデートサーバーを自作した話 を書きました。あれは今も動いています。私が運営しているコミュニティアプリの maru は、それ以来すべての OTA 修正をあのサーバー経由で、両プラットフォームに、月1ドルほどで配信してきました。

それは同時に、部品を全部自分で抱えているということでもあります。データベースのテーブル、API エンドポイント、管理コマンド、パブリッシュスクリプト、共有シークレット、そして壊れたアップデートを一つずつ経験して覚えたハマりどころの数々。今回の計画を立てようと腰を据えたとき、スクリプトが書いた日からずっと、本番へパブリッシュするたびに “Sent 0 push notifications” と出力していたことに気づきました。このサーバーが一度も返したことのないフィールドを読んでいたのです。誰も気づいていませんでした。誰よりも私が。自前で運用するというのは、だいたいこういうことになります。

そこで Codemagic から、CodePush をオープンソースでセルフホストできる形にした Patch を試してみないかと声をかけられたとき、条件を一つ付けて引き受けました。デモではなく本物のアプリでやること。本物の署名、本物のリリース手順、手で編集した箇所のあるコミット済みのネイティブプロジェクト、その全部です。EAS Update から移行する人の多くが動かしているのは、まっさらなテンプレートではなく、そういうアプリでしょう。

その顛末を、粗い部分もそのままにして書きます。

Patch とは何か

#

Patch は、自分で動かすサーバーと、アプリに組み込む SDK でできています。サーバー側は API、バックグラウンドワーカー、Postgres、S3 互換のオブジェクトストレージ、Web ダッシュボードで、Docker Compose のスタックとして配布されています。クライアント側は @codemagic/react-native-patch という iOS と Android 向けの TurboModule で、Expo の config plugin が付いています。それに加えて、JavaScript をバンドルしてパブリッシュする CLI の cmpatch があります。

ソースを読んで、設計上の判断が2つ目に留まりました。

1つ目は、アプリが API に「アップデートはあるか」と一度も尋ねないことです。リリースがパブリッシュされるとワーカーが素の JSON マニフェストをオブジェクトストレージに書き、アプリはそれを取りに行くだけ。アップデートの確認はストレージか CDN に対する静的な GET が2回で、API が受け取るのはメトリクスだけです。私の旧エンドポイントは、アプリを起動するたびにリクエスト経路の上に乗っていました。こちらではそれが起こり得ません。

2つ目は、すべてのリリースが対象とするバイナリのバージョンを厳密に指定することと、CLI がネイティブプロジェクトのフィンガープリントを計算して、ネイティブコードが一致しないバイナリへ JavaScript をパブリッシュするのを拒むことです。私のサーバーにあったのは バージョン文字列1つと、たくさんの「大丈夫だろう」でした。

まずは手元のノートパソコンで

#

ドキュメントはローカルの評価用スタックから始めるように案内していて、実際そこから始めるのが正解です。

npm install -g @codemagic/patch-cli
cmpatch selfhost local-eval up

CLI のインストールは2秒でした。スタックのほうは初回に3分14秒かかり、大半はサーバーとダッシュボードのイメージをローカルでビルドしている時間です。非対話モードだとその間何も出力しないので、ハングしているようにしか見えません（その後修正され、今はステップごとに進捗を1行出します）。そのあと、healthy なコンテナが4つ、すべて localhost に束縛された状態で現れました。8080 にダッシュボード、3000 に API、Postgres、そして 9100 に MinIO です。私自身のスタックがすでに使っているポートは、きちんと避けてくれました。

このモードではサインインが無効になっていて、外部に公開するなという警告がすべてのページに出ます。

localhost:8080

スタックには Example Data というアプリがあらかじめ入っています。何かをパブリッシュする前に一度眺めておく価値があります。ダッシュボードが何のためにあるのかが分かるからです。次の2枚のスクリーンショットの数字はそのシードデータで、実際のユーザーではありません。

localhost:8080

localhost:8080

比較のために言うと、私のダッシュボードは、管理画面のアップデート一覧に「有効」のチェックボックスが付いただけのものでした。実際に何台の端末がアップデートを取り込んだのか、まったく分かりませんでした。

CLI のログインは PKCE と localhost へのコールバックを使ったまっとうなブラウザフローで、承認ページにはどのアカウントが要求しているかと、コードが1分ほどで失効することが書いてあります。

localhost:8080

本物のアプリに向ける

#

Patch はプラットフォームごとに1アプリを求め、それぞれに Staging と Production のデプロイメントが作られます。maru-ios はダッシュボードで、maru-android は cmpatch app create で作りました。主に両方を見ておきたかったからです。アプリを作ったあとに出るダイアログは、移行にあたってこの製品でいちばん役に立つ画面です。両方のデプロイメントキー、SDK が必要とする2つの URL、そしてデプロイメントキーは秘密情報ではないという注記が載っています。

localhost:8080

小さなことが2つ。cmpatch init はすでに存在するアプリにプロジェクトを紐付けるコマンドだったので、移行ガイドがどう匂わせていようと、最初のコマンドにはなりませんでした。これはその後修正され、今は対話モードならプラットフォームごとにアプリを1つずつ自分で作ってくれます。それから、ダイアログは API の URL を http://localhost:8080 と示すのに、ドキュメントと CLI は 3000 と言います。どちらのポートも両方を配信しているのでどちらでも動きますが、首をかしげることにはなるでしょう。

次に、手を付けていないアプリに対して cmpatch doctor を走らせたところ、3秒で本物の問題を見つけてきました。iOS のバイナリバージョンを 2.0.0 と報告したのです。アプリは 2.5.1 です。

CLI は ios/ 以下のすべての Info.plist を探し、パスに “test” を含むものがなければ、アルファベット順で最初のものを取ります。maru には WidgetKit の extension があり、そのフォルダがアプリ本体のフォルダより前に並ぶので、CLI は extension の Info.plist を拾いました。その plist が 2.0.0 のまま古くなっていたのは私のバグですが、その影響はたちが悪い。自動検出に任せると、iOS のリリースがすべて、どの端末も動かしていないバージョンを対象にしてしまい、しかも何もエラーになりません。アップデートが単に永遠に届かないだけ。まさにセルフホストの記事で警告した失敗です。Android は versionName を正しく読みました。回避策は --target-binary-version か --plist-file を渡すことで、私のパブリッシュスクリプトは今、app.config.js と両方のネイティブプロジェクトが一致していることを確認したうえで、バージョンを明示的に渡しています。あとになって同じバグのせいで、doctor 自身のマニフェスト確認が、正常に動いているデプロイメントに対して失敗しました。バージョン 2.0.0 のマニフェストを探しに行ったからです。古い plist を直したら、doctor は24項目すべてを通過しました。

これは Codemagic がその後修正しました。CLI は今、extension ではなくアプリターゲットの Info.plist からバージョンを読みますし、アプリの候補になるターゲットが複数あれば、どれがそうなのかを cmpatch が尋ねてきます。

JavaScript 側

#

expo-updates を外して SDK を足すのは2行の変更です。アプリがアップデートに対してやっていたことを置き換えるほうは、もう少し考える必要がありました。

maru は起動時と、フォアグラウンドに戻るたびにアップデートを確認します。ただし最短でも15分おきです。見つかればダウンロードして再起動を提案し、断られれば次のコールドスタートで適用します。設定画面には、動作中のバンドルを表示する手動チェックもあり、エラーレポーターはすべてのレポートに、それが来たアップデートのタグを付けます。

SDK のソースから最初に学んだのは、インポート時に TurboModuleRegistry.getEnforcing でネイティブモジュールを探しに行き、モジュールがなければ例外を投げるということです。maru は Web ビルドも出荷しているので、トップレベルでインポートすると Web アプリが落ちます。そこで、SDK を遅延ロードする小さなモジュールを1つ用意し、すべてそこを通すようにしました。何も返さない .web.ts の双子を置いてあるので、SDK は Web バンドルから完全に外れます。

// ota.ts (ota.web.ts exports a patchSdk() that always returns null)
import { Platform } from "react-native";

type PatchSdk = typeof import("@codemagic/react-native-patch");
let sdk: PatchSdk | null | undefined;

export function patchSdk(): PatchSdk | null {
  if (sdk !== undefined) return sdk;
  if (Platform.OS === "web") return (sdk = null);
  try {
    sdk = require("@codemagic/react-native-patch") as PatchSdk;
  } catch {
    sdk = null;
  }
  return sdk;
}

自動チェック自体はほぼ sync() です。決して例外を投げず、ステータスに解決します。

const status = await patch.sync({
  installMode: "ON_NEXT_RESTART",
  mandatoryInstallMode: "ON_NEXT_RESUME",
});
if (status === "update-installed") offerRestart();

SDK の必須リリースのデフォルトは IMMEDIATE で、ユーザーがどこにいようと JavaScript をリロードします。私はアプリが次にバックグラウンドから戻ってきたときに適用するよう変えました。書きかけの投稿が消えるのは、たいていの修正の効き目より重いバグだからです。それから当時は、InstallMode がドキュメントの例から想像する enum オブジェクトではなく、文字列の union 型でした。今は定数オブジェクトとしてエクスポートされているので、InstallMode.ON_NEXT_RESTART はドキュメントどおりに動きます。

ネイティブ側、ios/ と android/ をコミットしている場合

#

移行ガイドは、config plugin を追加したあとで npx expo prebuild --clean を実行するように言っています。別のチェックアウトで実行してみたところ、同梱の画像、Android のネットワークセキュリティ設定、iOS のプライバシーマニフェスト、Podfile.lock が消え、build.gradle のテストランナー向けの修正と Info.plist の数百行が元に戻りました。--clean なしでも、Expo はどのみち両方のディレクトリを空にしました。

これは Patch のせいではありません。maru は managed な Expo アプリとして始まり、ネイティブのカスタマイズが増えていったので、ios/ と android/ はコミットされていて、EAS はそれをそのままビルドします。ただ、そういうアプリはいくらでもあるのに、ガイドは警告してくれませんでした。今はしてくれます。Expo の移行ガイドには道が2つ用意されていて、生成されたネイティブプロジェクトなら prebuild、コミット済みのプロジェクトなら手で当てる変更をそのまま示してくれます。

plugin が実際に変える内容は、蓋を開けてみれば手作業で済む程度でした。iOS では AppDelegate.swift に import が1つと1行。

return CodemagicPatch.bundleURL() ?? Bundle.main.url(forResource: "main", withExtension: "jsbundle")

Android では MainApplication.kt に import が1つと引数が1つ（これは React Native 0.82 以降の形で、それより古いバージョンでは代わりに getJSBundleFile() をオーバーライドします）。

ExpoReactHostFactory.getDefaultReactHost(
  jsBundleFilePath = CodemagicPatch.getJSBundleFile(applicationContext),
  // ...

加えてプラットフォームごとに設定値が3つと、古い expo-updates の設定の削除。両プロジェクト合わせて13行の追加と20行の削除です。

plugin はこれらの設定値を prebuild 時にリテラルとして書き込みます。コミット済みのネイティブプロジェクトでは、ビルドごとにデプロイメントが1つハードコードされることになります。私は同じプロジェクトから、プレビュービルドは Staging に、ストア向けビルドは Production に向けたかったので、値はビルド環境から取るようにしました。Info.plist では Xcode がビルド設定を展開してくれます。

<key>CodemagicPatchDeploymentKey</key>
<string>$(PATCH_IOS_DEPLOYMENT_KEY)</string>

android/app/build.gradle ではこうです。

def patchEnv = { name -> System.getenv(name) ?: (findProperty(name) ?: "") }
resValue "string", "CodemagicPatchDeploymentKey", patchEnv("PATCH_ANDROID_DEPLOYMENT_KEY")

キーは eas.json の各ビルドプロファイルに、EXPO_PUBLIC_ の値と並べて置きます。値が空だと SDK は黙って何もしません。ローカルビルドならそれで構いませんが、ストア向けビルドでは大惨事なので、app.config.js は preview か production の EAS ビルドでキーが欠けていたり、localhost を向いたままだったりすると例外を投げるようにしました。

最初のアップデート

#

最初のリリースでは、サインインしなくても見えるオンボーディングの見出しを変えて、パブリッシュしました。

./scripts/publish-update.sh ios --notes "Onboarding headline over the air"

30秒かかり、大半は Metro と Hermes です。サーバーのワーカーは、アップロード完了の0.6秒後にマニフェストをパブリッシュしました。アップデートは 7.3 MB の圧縮 tarball で、以前のエクスポートが生成していた 11 MB の Hermes バンドルとアセットに比べて小さくなっています。

ここで間違えてはいけないことが1つ。JavaScript バンドルはビルド時に EXPO_PUBLIC_ の値をインライン展開するので、アップデートは着地先のバイナリと同じ値でビルドしなければなりません。さもないと、間違ったバックエンドに話しかける JavaScript を出荷することになります。私のスクリプトは、バイナリをビルドしたのと同じ eas.json のプロファイルから値を読み込みます。Patch の CI ドキュメントにも今はこの点が明記されていて、release-react 自体は EAS のプロファイルを読まないことも書かれています。

それからアプリを再起動しました。端末のログでは、アップデートの確認全体がオブジェクトストレージへの2リクエスト、meta.json と 2.5.1/manifest.json として現れました。SDK は起動の3秒後に Downloaded イベントを書き、アップデートをステージングし、アプリが再起動を提案しました。

バグは私のものだった

#

そこでダッシュボードを見ました。シミュレーター1台がリリース v1 をインストールしたのに、成功2件、アクティブユーザー2人と表示されています。

localhost:8080

SDK は状態と未送信のメトリクスイベントをアプリのコンテナ内にファイルとして持っているので、追跡は簡単でした。タイムスタンプが同一で id が異なる Success イベントが2つありました。私のフックはマウント時に notifyAppReady() で動作中のバンドルを確定させ、その直後に sync() を呼んでいて、sync() は自分でも notifyAppReady() を呼びます。2つの呼び出しが重なり、どちらもリリースを pending と見なし、どちらもイベントを記録した。サーバーはイベント id で重複排除しますが、id が違うので両方数えられ、その重複は永久に残ります。

私の側の修正は、起動ごとに確認処理を1つだけ共有し、ほかはすべてそれを待つようにすることでした。SDK 自身が重なった呼び出しを防ぐこともできるはずで、そう提案しました。今はそうなっています。sync() の内部のものも含め、重なった notifyAppReady() の呼び出しは1つの確認処理を共有するので、インストールは1回だけ記録されます。SDK のリファレンスにも、sync() は自分で準備完了を確定させるので、sync() を使うアプリが別に notifyAppReady() を呼ぶ必要はない、と書かれるようになりました。

気持ちよかったのは、この修正の出荷です。JavaScript だけの変更なのでリリース v2 として出せて、v1 の端末にはバイナリ差分を送れるので、v2 は 7.3 MB のバンドルではなく 543 KB のパッチ、サイズにして約7% でダウンロードされました。再起動後: ダウンロード1件、インストール1件、成功1件、アクティブ端末1台。

localhost:8080

わざと壊す

#

ロールバックは私がいちばん気にしていた機能です。以前の構成には端末側のロールバックがまったくありませんでした。悪いアップデートを出せば、私が気づいてチェックボックスを外すまで、起動のたびにクラッシュし続けたはずです。

そこで、最初の描画の前に例外を投げる v3 をリリースしました。つまり notifyAppReady() を決して呼べないリリースです。アプリはそれをダウンロードし、再起動を提案し、ホーム画面へ落ちました。

次の起動では再び v3 が立ち上がり、再びクラッシュしました。これには驚きました。ドキュメントには、notifyAppReady() の前にクラッシュしたバンドルはロールバックされると書いてあるからです。ソースが説明してくれました。SDK は未確認の起動を3回まで許してから、クラッシュだと判断します。未確認の起動1回は、JavaScript が動く前に iOS が健全なプロセスを殺しただけかもしれないからです。4回目の起動で v2 に戻ってきました。

そして端末は自分から失敗を crash_rollback として報告し、ダッシュボードは v3 に対してそれを表示しました。理にかなった設計ですが、それが何を意味するかははっきり言っておく価値があります。悪いリリースは、ユーザー一人あたり3回のクラッシュ起動を代償にしてから回復するのであって、当時のドキュメントにはその回数が書かれていませんでした。今は書かれていますし、この予算は設定で変えられます。ネイティブなら CodemagicPatchMaxLaunchAttempts、Expo の plugin なら maxLaunchAttempts です。だからこそ、まず Staging、次に小さな Production ロールアウトなのです。

ほかの全員に対して悪いリリースを止めるのはコマンド1つで、1秒かかりませんでした。

cmpatch release rollback --app maru-ios --deployment Staging

履歴を書き換えることはしません。前のリリースを新しいリリース（v4、v2 のロールバックとしてマーク）としてもう一度パブリッシュするので、クラッシュしたリリースは失敗数とともに一覧に残ります。これが正直な記録です。ダッシュボードからも、ダイアログで同じことができます。

localhost:8080

Android

#

Android には驚きが2つあり、どちらも Patch のせいではありません。SDK 向けに足した R8 の keep ルールは app.config.js に置いてあって、これは prebuild を通してしかネイティブプロジェクトに届きません。つまり最初のリリースビルドは、keep ルールなしで SDK が R8 を生き延びるかどうかを、意図せず試すことになりました。生き延びます。R8 はクラスをすべてリネームしましたが、アップデートのダウンロード、インストール、ロールバックは問題なく動きました。もう1つはエミュレーターで、コールドブートしたばかりで Gradle がまだメモリを握っていたせいで極端に遅く、最初のテストは、SDK がすでに始めていたダウンロードを終える45秒前に諦めてしまいました。

リリース v1 は適用され、成功1件、アクティブ端末1台。クラッシュする v2 は、同じ3回の起動予算のあとにロールバックされました。

ハッピーパスの先

#

アップデートが届いてロールバックされることが核ではありますが、チームが日々使うのはそれ以外の機能なので、一つずつ試していきました。

段階的ロールアウトは決定論的で、これは気に入りました。md5(deviceId + "-" + releaseLabel) の先頭8桁の16進数を 100 で割った余りがロールアウトのパーセンテージ未満なら対象になるので、同じ端末は同じリリースに対してずっと対象か対象外のままです。私のシミュレーターは次のリリースでバケット 91 に入ると計算できたので、25% でパブリッシュしたところ、シミュレーターには正しく何も来ませんでした。cmpatch release patch で 95% に上げると（1秒かかりません）、次の起動で更新されました。

すると次のリリースが 409 で失敗しました。“deployment has an active rollout below 100 percent”。デプロイメントごとに部分ロールアウトは1つしか許されないので、ほかの何かを出す前にカナリアを完了するか、無効化するか、ロールバックする必要があります。妥当ですし、ドキュメントにも書いてありますが、マージのたびにパブリッシュするパイプラインは、カナリアの途中でここにぶつかります。報告してからは、CLI がここで事情を説明してくれるようになりました。アクティブな部分ロールアウトが邪魔をしているなら、待っても解決しないことと、ロールアウトを完了または無効化する方法を教えてくれますし、別のリリースジョブがまだ動いているなら、release inspect --wait で待つように言ってくれます。ドキュメントにも、リリースの変更を順番に行うためのセクションができました。

必須リリースは SDK の mandatoryInstallMode を使います。私は次のレジューム時に適用する設定にしていたので、アプリはアップデートをダウンロードしてプロンプトを表示し、プロンプトを無視してアプリをバックグラウンドに送ってから戻すと、新しいバージョンがただそこにありました。

リリースの無効化は、提供をやめる以上のことをします。最新のリリースを無効化した瞬間、マニフェストはまだ有効な中でいちばん新しいリリースを指すようになり、無効化したリリースにいる端末には、そこへ戻るパッチが提供されました。あるバイナリバージョンのリリースをすべて無効化すると、マニフェストのターゲットは null になり、SDK はアプリを出荷時のバンドルに戻します。私のアップデート用フックは最初このケースでプロンプトを出していなかったので、今は出すようにしてあります。

Staging から Production への昇格は1秒かからず、テストしたのとまったく同じパッケージを、同じハッシュとノートのまま再利用しました。ビルドし直すのではありません。ロールアウトのパーセンテージも受け付けるので、「Production の 10% に昇格」がコマンド1つで済みます。

ビルドとパブリッシュを別々の手順に分けることもできます。cmpatch bundle が .cmpatch のアーティファクトを生成し、ダッシュボードの「Bundle upload」はアップロード前にそれを読み取ります。プラットフォーム、対象バージョン、フィンガープリント、署名の状態、サイズ、バンドラー。CI がアーティファクトをビルドし、いつパブリッシュするかは別の誰かが決める、という体制に向いています。

フィンガープリントのガードに本格的にぶつかったのもここです。古いウィジェットの plist を直したあと、サーバーは次のリリースを 409 で拒否しました。ネイティブプロジェクトのフィンガープリントが、2.5.1 に対して記録されていたものと一致しなくなったからです。Android では app.config.js のコメントを編集しただけで十分でした。Expo はアプリ設定をフィンガープリントに含めるからです。ダッシュボードは同じチェックを、両方のフィンガープリントと「Upload anyway」ボタンの付いた警告として表示します。どちらの場合もインストール済みのバイナリのネイティブ部分は何も変わっていないので、上書きが正解でした。ただ実運用では、正直な答えはほぼ必ずバージョンを上げてストア向けにビルドすることで、私のパブリッシュスクリプトはこれが起きたとき、今はまさにそう伝えます。

コード署名は RS256 です。CLI が RSA の秘密鍵でパッケージのハッシュに署名し、SDK がバイナリにコンパイルされた公開鍵でそれを検証します。鍵は base64 の1行として渡すので、私のビルド設定方式にそのまま収まり、両プラットフォームでテストしました。鍵をアプリに入れた状態では、署名なしのリリースはダウンロード前に拒否されました。アプリで「require code signing」を有効にすると、サーバーは署名なしのパブリッシュを、対処法を示しガイドへリンクするエラーで拒否しました。署名済みのリリースはインストールされ、SDK は署名を検証済みとして記録しました。署名済みのものを無効化したときにサーバーがフォールバックした、古い署名なしのリリースも拒否しています。注意点は、公開鍵が最初に出荷するバイナリに入っていなければならないことです。アップデートで後から足すことはできません。

localhost:8080

チームと CI もカバーされています。メンバーにはチーム全体で共通の4つのロール（owner、admin、developer、viewer）のいずれかが付き、招待は相手が最初にサインインするまで保留されます。パーソナルアクセストークンは空のホームディレクトリでも動き、--token でも環境変数でも渡せて、トークン一覧には最後に使われた日時が出ます。Linux ランナーで同じパブリッシュスクリプトを、シークレットから取り出した署名鍵で走らせる手動実行の CI ワークフローも書きましたが、ホスト済みのサーバーが要るので、まだ実行していません。

当時なら使わずにおいたツールが1つ、cmpatch debug ios です。システムログを “OTA” で大文字小文字を区別せずにフィルタしてストリームしていたので “Rotation” にもマッチしてしまい、20秒のアプリ起動で SpringBoard のメッセージが画面いっぱいに流れ、アプリからは何も出ませんでした。これは修正済みで、今は SDK のマーカーが付いた行だけを表示します。もっとも SDK はもともとあまりログを出さず、出るのはほとんどエラーと開発ビルドでの警告なので、静かなストリームだと思っておいてください。getpwuid_r の警告が出ることがありますが、これは Patch ではなく xcrun simctl から来ています。

実際のところ、どれくらい大変か

#

Codemagic から意見を求められたので、できるだけ率直に書きます。

試すのは簡単です。コマンド2つと数分で、本物のサーバー、デモデータ入りのダッシュボード、自分のアプリに向けられる CLI が手に入ります。最初の1時間でいちばん良かった部分だと思います。

SDK の組み込みはそこそこの作業で、難しさの大半は Patch ではなく自分のプロジェクトの側にあります。ネイティブフォルダを生成させたまっさらな Expo アプリなら、本当に plugin と、expo-updates の呼び出しを置き換える数行だけです。maru のように、コミット済みのネイティブプロジェクト、ウィジェット extension、Web ビルド、R8、ビルドプロファイルを抱えたアプリでは、作業は端のほうにありました。prebuild を避けるためにネイティブの変更を手で当て、Staging と Production のビルドが別物になるように設定をビルド時に決め、SDK を Web から遠ざける必要がありました。アップデートの JavaScript がバイナリと同じ環境でビルドされることも保証しなければなりません。理解してしまえばどれも難しくはありませんでした。私が作業した時点ではその大半がドキュメントにありませんでしたが、コミット済みのネイティブプロジェクトの手順とバンドル時の環境については、今は載っています。

日常の使い勝手は良いです。パブリッシュはコマンド1つと30秒ほど。ロールアウト、昇格、無効化、ロールバックは CLI からでもダッシュボードからでもすべて1秒未満で、エラーは何が悪くて何をすべきかを伝えてくれます。サーバーのガード（フィンガープリントのチェック、一度に1つのカナリア、署名）は厳格で、私が間違ったことをするのを何度も止めてくれました。

本番で運用するのは、より大きなコミットメントです。Postgres とオブジェクトストレージ付きの Docker Compose スタックで、ホスティング、バックアップ、アップグレードは自分でやらなければならず、ドメイン2つと OAuth アプリが必要です。すでにサーバーを運用しているチームなら静かな午後1回分。サーバーを持ちたくないからこそ EAS にいるチームにとっては、SDK の作業よりもここが乗り換えの本当のコストです。

実時間で言うと、12:29 に CLI をインストールし、13:34 にはシミュレーターで最初のアップデートが適用されていました。そのうち30分は、Patch と無関係な理由で止まった Xcode のビルドです。この記事にあることは両プラットフォームとも、ホスト済みのサーバーを除けば午後の半ばまでに終わっていました。

いちばん時間を取られたものを順に挙げると、expo prebuild --clean がコミット済みのネイティブプロジェクトを消してしまい、そのあと全部を手で配線する方法を考えたこと。iOS のバージョン検出のバグで、これは誰も動かしていないバージョンにアップデートを送るところでした。二重に数えられたインストールで、これは自分のせいですが、sync() が自分で notifyAppReady() を呼ぶ以上、誰でも簡単に再現してしまいます。そしてドキュメントにない3回の起動というクラッシュ予算で、テストの途中で驚かされました。その次に来るのが、正しいけれど計画が要るもの。無害なネイティブ周辺の編集のあとに発火するフィンガープリントのガード、デプロイメントごとに一度に1つのカナリア、重ねて実行できないライフサイクルジョブ。最後のはスクリプトが続けていくつか処理をした途端に効いてきます。残りは小さなものでした。無音の初回セットアップ、うるさいデバッグコマンド、当時コードと合っていなかったドキュメントの例がいくつか。

これらはすべて詳細とともに Codemagic に書いて渡し、9月23日の時点でその大半が直っていました。バージョン検出、重なった確認処理、prebuild についての警告、クラッシュ予算、無音のセットアップ、デバッグコマンド、InstallMode の例、そしてリリースジョブやカナリアが邪魔をしているときのエラーです。まだ残っているのは小さなものです。ほかがすべて :3000 と言うなかでダッシュボードだけが API を :8080 と表示すること、Web と Jest で SDK が import 時に例外を投げること、それにドキュメントの穴がいくつか。

本番へ

#

ここまでの内容はすべて評価用スタックに対して動かしたものです。本番は同じアプリと同じスクリプトを本物のサーバーに向けるだけで、これが maru の計画です。

サーバーを動かすサポート対象の方法は Docker Compose でのインストールです。ポート 80 と 443 が開いた Linux マシン、ドメイン2つ（API とダッシュボード用、ダウンロード用）、そしてサインイン用の GitHub OAuth アプリ。OAuth アプリがないとサーバーは起動しません。あとはインストーラーが TLS まで含めてやってくれます。

scripts/selfhost/install.sh \
  --api-domain updates.example.com \
  --storage-domain storage.updates.example.com \
  --email you@example.com \
  --github-oauth-client-id <id> --github-oauth-client-secret <secret>

データベースとストレージのシークレットを書いた .env.selfhost が生成されるので、パスワードマネージャーに入れておきましょう。

とはいえ同梱のデータベースとストレージを使う必要はなく、それが私のようなスタックにも合う理由です。maru の API はすでに Fly.io で動いていて、ファイルは Tigris にあり、Patch はどちらでも動きます。Compose ファイルの下にあるのは MODE=all（API とリリースワーカーを一緒に）で動くコンテナ1つで、必要なのは Postgres のデータベース、S3 互換ストレージ、ファイル用の公開 HTTPS URL です。つまり、リポジトリの Dockerfile からビルドした Fly アプリ（公開されたイメージはまだないので fly deploy がビルドします）、Fly Postgres のデータベース、Tigris のバケットです。

MODE=all
DATABASE_URL=postgresql://…            # Fly Postgres
STORAGE_ADAPTER=s3
S3_ENDPOINT=https://fly.storage.tigris.dev
S3_REGION=auto
S3_BUCKET=myapp-patch
S3_FORCE_PATH_STYLE=true
PUBLIC_BASE_URL=https://myapp-patch.fly.storage.tigris.dev/codemagic-patch

注意点が2つ。Compose の外で動かす方法はリポジトリに参考資料として書かれているだけで、この最初のオープンソースリリースではサポート対象の経路ではないので、Fly 上でのアップグレードとバックアップは自己責任です。私もまだその形ではデプロイしていません。これは計画であって、報告ではありません。それから、Fly のゼロスケール の記事を読んだ方は、マシンを最低1台は動かしておいてください。マニフェストはストレージから直接来るので、端末がアップデートの確認で API を待つことはありませんが、そうしないとメトリクスのアップロードとリリースジョブがすべてコールドブートから始まることになります。

Tigris はいちばん楽しみにしている部分です。maru のファイルがすでにある場所ですし、アプリの起動のたびに叩かれる URL の前に CDN を置いてくれます。これをやるならマニフェストのキャッシュには気をつけてください。素の base-URL 配信アダプターでは、Patch は CDN をパージできないためマニフェストを no-cache で配信します。マニフェストが独自の TTL でキャッシュされると、ロールバックしたばかりのリリースを配り続けてしまうからです。設定リファレンスには今、この点が MANIFEST_CACHE_CONTROL の項に書かれていて、ドキュメントサイトでも S3 互換ストレージが扱われています。

ホスト済みのサーバーでもう一度アプリを作り、新しいキーを eas.json の preview と production プロファイルに（Staging のキーと Production のキー）入れ、パブリッシュ用のトークンを作ります。

cmpatch token create --name ci

コード署名をするなら、今決めてください。本番用の鍵ペアを生成し、秘密鍵は CI のシークレットとして保管し、公開鍵をビルドプロファイルに入れ、両アプリで「require code signing」を有効にします。Patch 入りの最初のバイナリには新しいバージョン番号も必要です。ストアにすでにあるバイナリは expo-updates を動かしているからです。まず preview プロファイルで TestFlight と Play の内部テスト向けにビルドし、誰かに渡す前に、キーが実際にビルド済みの Info.plist と Android のリソースに入ったかを確認してください。環境変数を手でエクスポートしていたので、ここだけはローカルのテストで検証できていない繋ぎ目です。それから Staging にパブリッシュし、テスター1人につきダウンロード1件と成功1件を確認して、そこで初めてストア向けにビルドします。

Production のリリースは小さく始めて広げます。

./scripts/publish-update.sh ios --production --rollout 10
cmpatch release patch --app maru-ios --deployment Production --label v1 --rollout-percentage 100

その間、古いサーバーは動かしたままにします。まだアップデートしていない 2.5.1 は今もそちらを確認していますし、そのユーザー向けのホットフィックスは引き続き古いスクリプトを通ります。ログでそのリクエストが止まったのを確認できたら、古いサーバーも、そのパブリッシュスクリプトとシークレットも、すべて消せます。

初めてのネイティブアップグレード

#

2026年10月16日追記。

10月初めから、maru の本番のアップデートは Patch が運んでいます。それ以降で初めてのネイティブリリースが Expo SDK 58 への移行でした。React Native 0.88、そして Android では Gradle プラグインの新しいメジャーバージョンです。ネイティブの変更は OTA では届けられないので新しいバイナリ 2.6.0 になり、私のパブリッシュスクリプトはそのバイナリが存在するまで 2.6.0 向けのアップデートを送ろうとしません。ビルドは両プラットフォームとも一発で通りました。

上の本番のセクションでは、誰かにビルドを渡す前に、キーが実際にビルド済みの Info.plist と Android のリソースに入ったかを確認するよう書きました。今回はちゃんと確認しましたし、このセクションがあるのはその確認のおかげです。iOS のビルドには Patch の設定が4つともありました。Android のビルドには1つもありませんでした。

bundletool dump resources --bundle=build.aab --values | grep -A1 "string/Codemagic"

このコマンドは 2.5.11 のビルドではキーを4つ出力し、2.6.0 では何も出しませんでした。環境変数のせいではありません。Gradle の generateReleaseResValues は4つとも書き出しています。消しているのはその後に走るリリースのリソースシュリンカーで、Android Gradle Plugin 9 ではずっと攻撃的になりました。同じアプリでリソースが 9,240 個から 7,116 個に減っています。SDK は設定を getIdentifier で名前から読みますが、シュリンカーにはそれが見えないので、4つの文字列を未使用とみなして消しました。存在しない文字列は空として読まれ、空は「アップデートなし」を意味します。何も失敗しなかったはずです。Android の 2.6.0 はインストールされ、普通に動き、アップデートを一度も受け取らず、唯一の兆候はダッシュボードに Android 2.6.0 の端末が1台もないことだけだったでしょう。

修正は、シュリンカーに4つの文字列を残すよう伝えるリソースファイル1つです。

<!-- android/app/src/main/res/raw/codemagic_patch_keep.xml -->
<resources xmlns:tools="http://schemas.android.com/tools"
    tools:keep="@string/CodemagicPatch*" />

keep.xml という名前にはしないでください。React Native のバンドルタスクが JavaScript のアセット用にすでに raw/keep.xml を生成していて（画像やフォントが生き残ったのはそのためです）、2つがぶつかります。ライブラリの keep ファイルはアプリに自動でマージされるので、このルールの置き場所としては SDK 自体のほうがふさわしく、デプロイメントキーなしでリリースビルドが起動したときに警告が1つ出るだけでも、黙って起きていたことが目に見えるようになります。前に出てきた iOS のバージョン検出のバグと同じ種類の失敗です。何もエラーにならず、アップデートがただ届かない。

同じ確認で、Patch とは関係のない2つ目の問題も見つかりました。こちらは別の理由で知っておく価値があります。Android のリリースビルドは起動直後にクラッシュしました。それも2回、Expo 自身のモジュールの中にある別々の2つの原因によってです。まず、Expo のウィジェット用モジュールがネイティブクラスの登録に失敗し、JavaScript が動く前にアプリが落ちていました。それを直すと、アプリは JavaScript の起動までは進んだものの、そこで止まりました。Expo の新しいモジュールシステムに移った3つのモジュールが登録されていなかったからです。どちらにも Patch のクラッシュロールバックは役に立ちません。ロールバックすべきアップデートがないからです。守ってくれるのは悪いアップデートからであって、悪いバイナリからではありません。Patch があってもなくても、ネイティブのアップグレードはストアに出す前に実機かエミュレーターにインストールして開いてみる必要があります。

同じテストから、もう1つ小さなことが出てきました。sync() は失敗すると "error" を返し、アプリが開発モードで動いていない限り理由は教えてくれません。なのでリリースビルドでは、何かがうまくいかなかったことしかログに残せません。今は私のフックが、sync が失敗したあとに一度だけ checkForUpdate() を呼んで、そこで投げられたものをログに出します。そうして初めて、サーバーが壊れていたのではなく、ローカルのシミュレータービルドの Patch の URL が空だった（unsupported URL）とわかりました。最後のエラーがリリースビルドでも読めれば助かります。

ネイティブリリースのチェックリストには、以前はなかった3行が加わりました。ビルド済みの .ipa と .aab から Patch の設定をダンプすること、デプロイメントキーをビルドプロファイルと突き合わせること、そして提出前にデバッグビルドではなくリリースビルドそのものを起動すること。

Expo の請求書を抱えている人に伝えたいこと

#

サーバーを作るのが大変そうに見えたから EAS Update にお金を払っているのなら、Patch は本物の答えです。サーバーは動かしますが、それは Compose スタックとインストーラーであって、自分でメンテナンスするコードではありません。私が作ったものと比べると、段階的ロールアウト、リリースごとのインストール数と失敗数、バイナリパッチ、フィンガープリントのガード、コード署名、端末側でのクラッシュロールバック、ロールバックボタンが手に入ります。私はどれも作っていませんでした。

代償は、SDK をアプリに入れる必要があるので、誰かに Patch のアップデートが届く前に新しいバイナリが要ること。アップグレードとバックアップを続けるサーバー。リリースが十分ひどければ、デフォルトでユーザー一人あたり3回のクラッシュ起動。ネイティブプロジェクトをコミットしているなら、いくらかの手作業。それに、まだ若い。今回のバージョンは 0.3.0 で、バージョン検出のバグ、うるさいデバッグコマンド、ドキュメントの穴をいくつか踏み、SDK が防げたはずのバグを自分でも作りました。バージョン検出とデバッグコマンドはその後修正され、ドキュメントの穴も大半が埋まり、私がやった間違いも今は SDK が防いでくれます。どれも移行を止めるものではなく、すべてが CLI、ダッシュボード、あるいは端末上の SDK 自身のファイルで見えていました。これは以前の構成には言えなかったことです。

2026年9月13日追記。 この記事の公開後、CodemagicがCodePush系のオープンソースでセルフホストできるOTAサーバー、Patchをリリースしました。サーバーを自分で作りたくなくてここにたどり着いた方には、いまや現実的な選択肢です。私自身、その後この記事の構成からPatchへアプリを移行してその顛末を書きましたし、おわりにの下に短い補足も足してあります。開示: その移行と執筆にはCodemagicから報酬を受けていて、ここで触れることも先方からの依頼です。本文のコードは、その後短い例に絞りました。

私が開発している見積もりアプリでは、バグ修正をOTA（Over-the-Air）で配信しています。JavaScriptの変更が、App Storeの審査を通さずにユーザーの端末へ届くわけです。ExpoのホストサービスであるEAS Updateを使えば同じことができるのですが、私はDjango REST FrameworkとTigris S3で自前のサーバーを作りました。以来、iOS・Androidのアップデートはすべてここから配信しています。

ExpoのOTAアップデートの仕組みはこうです。アプリに入っているexpo-updatesライブラリが、プラットフォームとランタイムバージョンをヘッダーに載せて、アップデートサーバーにマニフェストを要求します。サーバーは互換性のある最新のアップデートを、そのJavaScriptバンドルとアセットのURLと一緒に返し、アプリはそれらをダウンロードして、次回の起動時から新しいバンドルで動きます。EAS Updateはこのプロトコルを実装したExpoのホストサーバーですが、同じプロトコルに対応していればどんなサーバーでも構いません。私が作ったのは、まさにそういうサーバーです。

この記事では、モデル設計からマニフェストエンドポイント、パブリッシュのパイプライン、そして実際に運用して初めて分かったハマりどころまで、一通り紹介します。

そもそもなぜ自前でホスティングするのか

#

私の場合、一番の理由はコストでした。EAS Updateの料金は使用量に応じて増えていくので、ユーザーが増えて更新頻度も上がるとそれなりの金額になります。一方、TigrisのようなS3互換ストレージならほとんどタダみたいなものです。ほかの理由が効いてくる場合もあるでしょう。アプリケーションのアセットをすべて自社インフラ内に置くことが求められる業界もありますし、サーバーを自分で持てばアップデートの流れを丸ごと制御できるので、特定のユーザー層への配信やバンドルのA/Bテストも自由にできます。Expoの稼働状況や次の料金改定に振り回されずに済むのも、地味に大きいところです。

全体の構成

#

構成要素は4つです。アップデートのマニフェストを返しメタデータを保存するDjangoバックエンド、バンドルとアセットの実体を置くTigris、エクスポート・アップロード・登録をまとめて行うパブリッシュ用スクリプト、そしてExpoのサーバーではなく自分のサーバーを向くように設定したモバイルアプリ本体です。

┌─────────────────┐
│   Mobile App    │
│  (expo-updates) │
└────────┬────────┘
         │ 1. Request manifest
         │    (with headers: platform, runtime-version)
         ↓
┌─────────────────┐
│  Django Server  │
│  /api/expo-     │◄─── 2. Query DB for latest update
│   updates/      │
│   manifest/     │
└────────┬────────┘
         │ 3. Generate presigned URLs
         │
         ↓
┌─────────────────┐
│   Tigris S3     │
│  (Asset Files)  │◄─── 4. App downloads bundles directly
└─────────────────┘

実装

#

2つのモデル

#

すべての土台になるのがExpoUpdateとExpoUpdateAssetです。前者は各アップデートのメタデータを持ちます。

class ExpoUpdate(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    runtime_version = models.CharField(max_length=50, db_index=True)
    platform = models.CharField(
        max_length=10,
        choices=[("ios", "iOS"), ("android", "Android")],
        db_index=True
    )
    is_active = models.BooleanField(default=True, db_index=True)
    manifest_data = models.JSONField()
    description = models.TextField(blank=True)
    created_at = models.DateTimeField(auto_now_add=True)

    class Meta:
        indexes = [
            models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
        ]

設計上のポイントがいくつかあります。runtime_versionはapp.jsonのruntimeVersionに対応するフィールドで、クライアントは自分のランタイムバージョンに一致するアップデートしかダウンロードしないため、ここが要になります。バンドルの中身が違うので、iOSとAndroidは別レコードです。is_activeはロールバックの仕組みで、問題のあるアップデートを無効化すればクライアントはひとつ前のものに戻ります。そしてmanifest_dataにはExpo Updates v1プロトコルのマニフェストを丸ごとJSONで保存しておくので、配信時は取り出すだけで済みます。

ExpoUpdateAssetは個々のファイルを管理します。

class ExpoUpdateAsset(models.Model):
    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
    update = models.ForeignKey(ExpoUpdate, on_delete=models.CASCADE, related_name="assets")
    hash = models.CharField(max_length=255, db_index=True)
    key = models.CharField(max_length=255)
    content_type = models.CharField(max_length=100)
    file_extension = models.CharField(max_length=10)
    file_path = models.CharField(max_length=500)
    file_size = models.IntegerField(default=0)

アセットはSHA-256ハッシュで参照するので、不変でキャッシュも効きます。同じアセットを複数のアップデートで共有することも可能です。

マニフェストエンドポイント

#

アプリとサーバーが実際にやり取りするのが/api/expo-updates/manifest/です。Expo Updates v1プロトコルを実装しています。

@action(detail=False, methods=["get"], url_path="manifest")
def manifest(self, request):
    # Extract required headers
    protocol_version = request.META.get("HTTP_EXPO_PROTOCOL_VERSION")
    platform = request.META.get("HTTP_EXPO_PLATFORM")
    runtime_version = request.META.get("HTTP_EXPO_RUNTIME_VERSION")

    # Validate protocol version
    if protocol_version != "1":
        return Response(
            {"error": f"Unsupported protocol version: {protocol_version}"},
            status=400
        )

    # Find latest active update for this runtime + platform
    update = ExpoUpdate.objects.filter(
        runtime_version=runtime_version,
        platform=platform,
        is_active=True,
    ).order_by("-created_at").first()

    # No update available - client uses embedded bundle
    if not update:
        response = Response(status=204)
        response["expo-protocol-version"] = "1"
        return response

    # Generate presigned URLs for all assets
    manifest_data = build_manifest(update)  # fills in presigned asset URLs

    return Response(manifest_data, status=200)

ポイントは3つあります。アップデートがないときは204を返し、アプリは組み込みのバンドルをそのまま使い続けます。マニフェスト内のアセットURLは署名付きURL（presigned URL）なので、Djangoを経由せずTigrisのCDNから直接ダウンロードされます。そしてレスポンスのexpo-protocol-versionヘッダーは省略できません。クライアントがきちんと確認しています。

アップデートのパブリッシュ

#

パブリッシュはDjangoの管理コマンドと、それを包むシェルスクリプトで行います。管理コマンドはexpo exportの出力を読み取り、各アセットのSHA-256ハッシュを計算し、バンドルとアセットをTigrisへ並列アップロードし、データベースにレコードを作り、必要ならプロダクション同期用のインポートJSONもバケットに置きます。要点だけに絞るとこうなります。

from concurrent.futures import ThreadPoolExecutor

from django.db import transaction


def publish(platform, runtime_version, manifest, files):
    # Upload the bundle and assets in parallel (keys are content hashes)
    with ThreadPoolExecutor(max_workers=10) as executor:
        list(executor.map(upload_asset, files))

    # Swap the active update in one transaction
    with transaction.atomic():
        ExpoUpdate.objects.filter(
            runtime_version=runtime_version,
            platform=platform,
            is_active=True,
        ).update(is_active=False)

        return ExpoUpdate.objects.create(
            runtime_version=runtime_version,
            platform=platform,
            manifest_data=manifest,
        )

普段実際に叩くのは、ラッパースクリプトのほうです。

# Publish to local environment
./publish.sh ios

# Publish to production
./publish.sh ios --production

# Dry run to validate
./publish.sh --dry-run

エクスポート前にプロダクションの環境変数を読み込み、プラットフォームは片方でも両方でも指定でき、次に説明するプロダクション同期まで面倒を見てくれます。

プロダクションへの同期

#

プロダクションの認証情報を手元のマシンに置きたくなかったので、本番へのデプロイは2段階にしました。まずローカルでパブリッシュし（アセットはTigrisへ、メタデータのJSONスナップショットも一緒に）、そのあとS3のパスを添えてプロダクションのAPIを呼び、サーバー側でメタデータを取り込んでもらいます。

@action(detail=False, methods=["post"], url_path="import-update")
def import_update(self, request):
    # Authenticate via Bearer token
    token = request.META.get("HTTP_AUTHORIZATION", "").removeprefix("Bearer ")
    if not hmac.compare_digest(token, settings.IMPORT_TOKEN):
        return Response({"error": "Invalid token"}, status=401)

    # Download the import JSON from the bucket
    s3_key = request.data.get("s3_key")
    obj = s3_client.get_object(Bucket=bucket_name, Key=s3_key)
    data = json.loads(obj["Body"].read())

    # Import into the production database
    with transaction.atomic():
        update, _ = ExpoUpdate.objects.update_or_create(id=data["id"], defaults={...})
        for asset_data in data["assets"]:
            ExpoUpdateAsset.objects.update_or_create(...)

    # Clean up the import JSON
    s3_client.delete_object(Bucket=bucket_name, Key=s3_key)
    return Response({"update_id": str(update.id)})

アプリをサーバーに向ける

#

app.jsonでアップデートURLとランタイムバージョンを設定します。

{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://api.example.com/api/expo-updates/manifest/"
    }
  }
}

runtimeVersionはアプリとサーバーで厳密に揃えてください。ネイティブコードを変えたときやExpo SDKを上げたときは、ランタイムバージョンを上げて、そのバージョン向けにアップデートを出し直します。

Tigrisでのストレージ

#

TigrisはS3互換のオブジェクトストレージで、本家AWS S3よりかなり安く、グローバルなエッジキャッシュも込みです。数メガバイト級のバンドルをユーザーがダウンロードすることを考えると、これが効いてきます。Django側の設定は次の通りです。

# settings.py
BUCKET_NAME = os.getenv("BUCKET_NAME")
AWS_ENDPOINT_URL_S3 = os.getenv("AWS_ENDPOINT_URL_S3")
AWS_ACCESS_KEY_ID = os.getenv("AWS_ACCESS_KEY_ID")
AWS_SECRET_ACCESS_KEY = os.getenv("AWS_SECRET_ACCESS_KEY")
AWS_REGION = os.getenv("AWS_REGION", "auto")

クライアントの生成はごく普通のboto3です。

import boto3

def create_s3_client(endpoint_url, region, access_key, secret_key):
    return boto3.client(
        "s3",
        endpoint_url=endpoint_url,
        region_name=region,
        aws_access_key_id=access_key,
        aws_secret_access_key=secret_key,
    )

ダウンロードには署名付きURLを使うため、アプリはCDNから直接取得します。

presigned_url = s3_client.generate_presigned_url(
    "get_object",
    Params={"Bucket": bucket_name, "Key": asset.file_path},
    ExpiresIn=3600,  # 1 hour
)

セキュリティ

#

マニフェストエンドポイントは、あえて認証なしにしています。ログイン前のアプリにもアップデートは必要だからです。一方、インポートエンドポイントはプロダクションのデータベースに書き込めるので話が別で、共有シークレットで守り、タイミング攻撃を避けるために定数時間で比較します。

IMPORT_TOKEN = os.getenv("IMPORT_TOKEN")

# Constant-time comparison prevents timing attacks
if not hmac.compare_digest(token, IMPORT_TOKEN):
    return Response({"error": "Invalid token"}, status=401)

アセットの整合性は、この設計なら勝手についてきます。すべてSHA-256ハッシュで検証されるので、改ざんされたアセットは単に失敗するだけです。署名付きURLも1時間で失効するため、バンドルが延々と直リンクされ続ける心配はありません。

速度まわり

#

(runtime_version, platform, is_active, -created_at)の複合インデックスのおかげで、アップデートがいくら溜まってもマニフェストのクエリは速いままです。

class Meta:
    indexes = [
        models.Index(fields=["runtime_version", "platform", "is_active", "-created_at"])
    ]

パブリッシュ用スクリプトはアセットを並列でアップロードします。

with ThreadPoolExecutor(max_workers=10) as executor:
    futures = {executor.submit(upload_asset, asset): asset for asset in assets}
    for future in as_completed(futures):
        # Track progress

アセット50個ほどの典型的なアップデートで、パブリッシュ時間は約2分から15秒になりました。配信側でやることは何もありません。Tigrisが勝手にユーザーの近くのエッジへキャッシュしてくれます。

日々の運用

#

開発中

#

# 1. Make code changes in the app
git commit -am "Fix bug"

# 2. Publish OTA update to local environment
./publish.sh ios

# 3. Test on device
# App automatically downloads and applies update

プロダクションへのリリース

#

# 1. Publish to production
./publish.sh ios --production

# 2. Monitor
# Check Django admin for update records
# Verify assets in Tigris dashboard

ロールバック

#

# Mark problematic update as inactive in Django admin
# or via management shell:
python manage.py shell

>>> from updates.models import ExpoUpdate
>>> bad_update = ExpoUpdate.objects.get(id="uuid-here")
>>> bad_update.is_active = False
>>> bad_update.save()

# Clients will now receive the previous active update

かかっている費用

#

このアプリのアクティブユーザーは500人ほどです。Tigrisでは、過去のアップデート約200MB分のストレージが月$0.02ほど、アップデートのダウンロードによる月約50GBのエグレスが$1.00ほど。Django側はもともとAPIを動かしているサーバーに相乗りしているので、追加コストはゼロです。全部で月1ドルといったところ。同じ規模でEAS Updateを使うと年間$300〜500ほどになるはずなので、元はほぼ即座に取れました。

モニタリングとデバッグ

#

凝ったことはしていません。ViewSetがマニフェストのリクエストをすべてログに残します。

logger.info(f"Manifest request: platform={platform}, runtime={runtime_version}")

実質的なダッシュボードはDjango adminです。モデルを登録しておけば、確認も絞り込みも一通りできます。

@admin.register(ExpoUpdate)
class ExpoUpdateAdmin(admin.ModelAdmin):
    list_display = ["platform", "runtime_version", "is_active", "created_at"]
    list_filter = ["platform", "is_active", "runtime_version"]
    search_fields = ["description"]

クライアント側では、expo-updatesが何を見ているかを教えてくれます。

import * as Updates from 'expo-updates';

Updates.checkForUpdateAsync().then(update => {
  console.log('Update available:', update.isAvailable);
  console.log('Manifest:', update.manifest);
});

ハマりどころ

#

ランタイムバージョンの不一致

#

一番よくある失敗が、一番静かに起きます。クライアントは自分のランタイムバージョンに一致するアップデートしかダウンロードしません。インストール済みのアプリがランタイム1.0.0なのに1.0.1向けにパブリッシュすると、何も届かず、エラーも出ません。ランタイムバージョンはビルドと同期させ、上げるのはネイティブコードが変わったときだけにしてください。

createdAtタイムスタンプ

#

expo-updatesクライアントはマニフェストのcreatedAtを組み込みバンドルのcommitTimeと比較し、createdAtのほうが新しいアップデートだけを適用します。ViewSetではデータベースのタイムスタンプで上書きしています。

manifest_data["createdAt"] = update.created_at.strftime("%Y-%m-%dT%H:%M:%S.%fZ")

ローカル開発では、OTAをパブリッシュしたあとにバイナリをビルドした場合、タイムスタンプが新しくなるようにOTAを出し直してください。

マニフェストのアセットkey

#

マニフェスト内の各アセットのkeyフィールドはexpo-updatesがキャッシュに使うもので、ランダムなUUIDや適当な文字列ではなく、決定論的なハッシュ（ファイル名のMD5など）でなければなりません。ここを間違えると、クライアントがアセットを正しくキャッシュ・取得できなくなり、最初の1回だけ成功したあとアップデートが黙って壊れます。この問題を報告してくれた読者のRaphael Mutschlerさんに感謝します。原因を突き止めるまで、彼の環境ではアップデートがちょうど1回だけ動いていたそうです。

expoClientのアプリ設定

#

LinkingやConstantsなど、実行時にアプリ設定を読むものを使っている場合は、マニフェストのextra.expoClientフィールドにアプリ設定を含める必要があります。これがないと、最初は普通に起動するのに、アプリを閉じたあと再起動できなかったりクラッシュしたりします。expo-updatesが組み込みマニフェストをOTAのものに置き換えるため、expoClientが欠けているとこれらのAPIが頼りにしている設定へアクセスできなくなるのです。これもRaphael Mutschlerさんが見つけてくれました。

アセットの掃除

#

古いアップデートはTigrisに溜まっていきます。今のところ、掃除は手作業です。

# Delete updates older than 30 days
from datetime import timedelta
from django.utils import timezone

cutoff = timezone.now() - timedelta(days=30)
old_updates = ExpoUpdate.objects.filter(created_at__lt=cutoff, is_active=False)

for update in old_updates:
    # Delete assets from S3
    for asset in update.assets.all():
        s3_client.delete_object(Bucket=bucket_name, Key=asset.file_path)
    # Delete DB records
    update.delete()

本来はスケジュールタスクに載せるべき処理ですが、まだ手を付けられていません。

この先やりたいこと

#

(2026年9月: いまではPatchがこの3つも、それ以上もやってくれます。移行の記事を参照してください。)

段階的ロールアウト

#

rollout_percentageフィールドを足せば、まず一部のユーザーだけに配信できます。

rollout_percentage = models.IntegerField(default=100)

# In the manifest view:
if update.rollout_percentage < 100:
    # Hash user ID and check if they're in rollout group
    user_hash = int(hashlib.sha256(user_id.encode()).hexdigest(), 16)
    if (user_hash % 100) >= update.rollout_percentage:
        return Response(status=204)  # No update