English · 日本語
Web UI のセルフホスティング¶
bajutsu の Web UI(cli)を、自前のハードウェア上で、プライベートな Tailscale ネットワーク 越しにチームから到達できるよう動かします(セルフホスティングロードマップ BE-0016)。今日使える 段階は 2 つあり、どちらも BE-0051 の認証と入力検証で公開を安全にしています。
- Tier A、単一 Mac。 トークン認証付きの
bajutsu serveと、その job を実行するローカルのbajutsu workerを、1 台の Mac で動かします。本ページの「Tier B」節より前がこれを扱います。- Tier B、セルフホストのサーバ backend。 BE-0015 のコントロールプレーン(FastAPI、Postgres、 S3 互換ストレージ、GitHub OAuth、RBAC、クォータ)を Linux ノードで動かし、Mac をワーカーにします。既定では シングルテナントで動き、config で org を宣言すれば複数 orgに対応します(後述の「Tier B、サーバ backend の セルフホスティング」節を参照)。
フルマネージドの公開クラウド提供(ホスト型の Mac ワーカープール+IaC)は将来のままです (BE-0015)。
macOS の制約¶
ランナーは iOS Simulator を駆動し、Simulator は GUI ログインセッション(Aqua セッション)を必要と します。ヘッドレスな daemon では動きません。以下の選択はすべてここから来ます:
- serve は per-user の
LaunchAgent(GUI セッション)として動かします。LaunchDaemonではありません。 - 再起動後に GUI セッションを回復するよう Mac を auto-login にします(FileVault はコールドブート後、 auto-login が進む前に一度だけ対話ログインが必要)。
- セッションを生かし続けるためスリープを無効化します:
sudo pmset -a sleep 0 disablesleep 1。
これらの制約は iOS Simulator(XCUITest) backend に固有のものです。web(Playwright) backend はヘッドレスの ブラウザを動かすため、どれも必要ありません。Mac でも Linux でも(Tier B のノード上でも)serve でき、web だけの 構成ならこの節は読み飛ばせます。
1. LaunchAgent を生成する¶
先に、この agent が使う venv へ backend のランタイム依存を入れてください。 agent は
python -m bajutsu serveを直接起動するため、make serveと違って依存をオンデマンドでは入れません。 入れるのは backend のランタイムクロージャ、つまり実行が到達するものをすべて名前で束ねた 1 つの extra です。ここにはvisual(スクリーンショット)とschema(responseSchema)のアサーション依存も 含まれます(BE-0173)。web(Playwright)backend ならuv sync --extra worker-web && playwright install chromium、iOS Simulator(XCUITest)backend ならuv sync --extra worker-iosです(XCUITest backend は backend の pip extra を必要としません。xcodebuildは Xcode が供給し、target が事前ビルドのdriver.runner.testRunnerを供給するので、worker-iosはvisual/schemaのアサーション依存だけです)。 backend の extra 単体(たとえばweb)では入れ足りず、その実行は アサーションの時点で遅延的に失敗します。クロージャをまったく入れずに飛ばすと、実行のディスパッチ時にno available actuatorで失敗します。
bajutsu serve --emit-launchagent は、渡した serve フラグに対応する launchd plist を出力して、サーバを
起動せずに終了します。強いトークンを選び、plist を LaunchAgents に書き出します:
export TOKEN="$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
bajutsu serve --emit-launchagent --config bajutsu.config.yaml --token "$TOKEN" \
> ~/Library/LaunchAgents/com.bajutsu.serve.plist
chmod 600 ~/Library/LaunchAgents/com.bajutsu.serve.plist # plist はトークンを含む
出力される plist は、次のように動きます:
python -m bajutsu serve --host 127.0.0.1 --port 8765 --config …を、RunAtLoad+KeepAlive付きで実行します(コマンドを動かしたのと同じインタプリタ、つまりあなたの venv を使います)。- トークンを
EnvironmentVariables(BAJUTSU_SERVE_TOKEN)に入れます。argv には載せないので、psからは 見えません。 - stdout/stderr を
~/Library/Logs/bajutsu-serve.{out,err}.logに書きます。
出力された plist が設定しない項目が 2 つあり、どちらも EnvironmentVariables に追記します。
ANTHROPIC_API_KEY:AI パス(record、--system-alert-handling)に必要です(自動では埋め込みません)。Bedrock プロバイダを使うなら、代わりにここへBAJUTSU_AI_PROVIDERとBAJUTSU_BEDROCK_MODEL、AWS の認証情報を置きます。PATH:iOS(XCUITest)backend のときだけ必要です。launchd は最小のPATHで agent を起動し、bajutsu はxcodebuild/xcrun/simctlをPATH経由で探すため、これがないと実行がno available actuatorで 失敗します。Xcode のコマンドラインツールの bin、Homebrew の bin、venv の bin を含めてください(web backend は Playwright を import で見つけるのでPATHの追記は要りません)。
XML を手で編集せずに、PlistBuddy で両方を追記できます(.venv が解決できるよう、リポジトリ root で実行してください)。
PLIST=~/Library/LaunchAgents/com.bajutsu.serve.plist
/usr/libexec/PlistBuddy -c "Add :EnvironmentVariables:ANTHROPIC_API_KEY string sk-ant-…" "$PLIST"
/usr/libexec/PlistBuddy -c "Add :EnvironmentVariables:PATH string $(brew --prefix)/bin:/usr/bin:/bin:/usr/sbin:/sbin:$(pwd)/.venv/bin" "$PLIST"
エージェントが起動するのはサーバだけです。サーバはすべての job を bajutsu worker のキューに積み、
自分では1つも実行しません(BE-0449)。2つ目の LaunchAgent として worker を横で動かします。
- plist を別のラベルで複製します。
- その
ProgramArgumentsをpython -m bajutsu worker --platform iosに変えます。続けて--server-state-dir <プロジェクト>/.bajutsuを加えます。<プロジェクト>は、サーバの runs ディレクトリを 置くディレクトリです。--server-state-dirを渡すと、このマシン上のファイルを指定する job を worker が受け取れます (1台のマシンで動かすサーバ backend)。サーバが 8765 以外のポートで待ち受けるときは、--server-url http://127.0.0.1:<ポート>も加えます。 - 同じトークンを、その
EnvironmentVariablesにBAJUTSU_TOKENとして入れます。 - 作業ディレクトリはそのままにします。worker は job ごとに専用の一時ディレクトリで実行します。
作業場所を固定したいときは
--workdir <ディレクトリ>を渡します。
worker が問い合わせるまで job はすべてキューに残り、UI は使える worker がないことを示します。
serve のバインドは 127.0.0.1 のままで、これを到達可能にするのは次の手順です。
2. ロードする¶
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.bajutsu.serve.plist
launchctl print gui/$(id -u)/com.bajutsu.serve # ロード確認
plist を編集した後に再読み込みするには、launchctl bootout gui/$(id -u)/com.bajutsu.serve の後で再度 bootstrap します。
3. Tailscale で公開する(推奨)¶
serve は 127.0.0.1 のままで、Tailscale が tailnet 内にだけ公開します。identity ベースのアクセスと
自動 TLS が備わり、公開面はありません:
tailscale serve --bg 8765 # → https://<machine>.<tailnet>.ts.net(tailnet 内のみ到達可能)
チームがその URL を開くと、初回に UI がトークンを尋ねます(以後はブラウザがセッション Cookie を持ちます)。
API クライアントは Authorization: Bearer $TOKEN を送ります。
0.0.0.0をインターネットに公開しないでください。 トークンがあっても、安全な既定はプライベートな tailnet です。serve はトークン無しの非 loopback--hostを拒否しますが、公開バインドは不必要に面を広げます。 本当に内部ホスト名が必要なら、serve の前段に Caddy を置いて TLS(+ basic auth)を付け、オープンな インターネットからは隔離してください。
セキュリティのまとめ(BE-0051)¶
セルフホストの serve は
BE-0051
のハードニングに依存します。全リクエストのトークン認証、/api/run と /api/record をアプリの scenarios dir
に限定して backend/udid を検証すること、CSRF Origin チェックとセキュリティヘッダ、run dispatch の同時実行上限です。
トークンは秘匿し、Mac は tailnet 上に置き、OS は更新し続けてください。
CSRF の Origin チェックと Host ヘッダの許可リストは、トークンが設定されているときだけでなく無条件で動きます
(BE-0121)。これがいちばん
効くのは make serve の既定(ループバック、トークンなし)です。別タブで開いたページからのクロスオリジンの POST は
ブロックされ、Host がバインド済みのインタフェースを指さないリクエストは拒否されるので、リバインドされたホスト名では
GET /api/apikey のようなループバックのエンドポイントに到達できません。Origin ヘッダを持たない非ブラウザの
クライアントは影響を受けません。Host の許可リストは serve がバインドするインタフェースから導かれます。ループバックに
バインドすればループバックの名前、それ以外はそのホストです。ワイルドカードのバインド(0.0.0.0 や ::)は到達しうる
名前を列挙できないため Host チェックを無効化し、クロスオリジンの防御は CSRF が担います。
アップロードされた config のコマンド実行(BE-0090)¶
アップロードされた .zip バンドルは、テスト対象アプリを起動するシェルコマンドを services.server.cmd
(および、配線され次第 services.mockServer.cmd)に持つ config を同梱できます。このコマンドは信頼できない入力なので、
serve がホスト上で直接実行することはありません。アップロードされたバンドルの run がこのコマンドを必要とする
ときの挙動は、--upload-exec オプション(ホスト型 backend では環境変数 BAJUTSU_UPLOAD_EXEC)で選びます。これが
効くのはアップロード由来の config だけで、ローカルや Git 由来の config は運用者が信頼しているため影響を受けません。
sandbox(既定):コマンドを使い捨ての Docker コンテナの中で実行し、serveホストには決して触れさせません。 バンドルはランタイムを、dockerImage(公開済みのベースイメージ。例node:20-slim)かdockerfile(バンドル相対の パスで、serveがdocker buildでビルドします)のどちらか一方で宣言し、加えてport(コンテナ内の待ち受けポート) を指定します。コンテナはハードニングされ(--rm、全ケーパビリティの剥奪、権限昇格の禁止、読み取り専用ルート ファイルシステムとtmpfsのスクラッチ、非 root ユーザ、CPU・メモリ・pid の上限、そして単一のポートだけを ループバックのホストポートへ publish)、run の後に破棄します。serveホストには Docker が必要です。reuse:アップロードされたコマンドは実行せず、subject.urlですでに応答している運用者提供のサーバをプローブする だけです。何も応答しなければ、何かを起動するのではなく run を fail loud させます。deny:アップロードされたコマンドをきっぱり拒否します。reuseと同様、外部で応答するサーバがあれば受け入れ、 なければ run を fail loud させます。
どのモードもアップロードされたコマンドをホスト上で実行することはなく、黙ってそこへフォールバックすることも
ありません。ブロックされた、あるいは設定の誤った services.server は、flaky に見える run ではなく明確なエラーで
失敗します。その判断(denied / reused / sandboxed、sandbox のときは使ったイメージ)は run の manifest.json の
provenance に記録されるので、「この run は何を実行し、何を抑止したのか」に、あとから答えられる状態を保てます。
リモート config のコマンド実行(BE-0121)¶
起動時に --config でバインドした config(自分で入力したローカルパスや github: の spec)は運用者が信頼しているため、
serve はその subject.build コマンドを通常どおり実行します。あとから UI の「from Git」ピッカーでバインドした Git config
(git の spec を伴う POST /api/config)は信頼のレベルが違います。クロスオリジンのリクエストがそれをバインドした
可能性があるので、アップロードされたバンドルと同じ扱いにし、その subject.build コマンドは既定ではホスト上で実行しません。
UI からバインドした Git config でその build を信頼して run を回したいときは、--allow-remote-build(または環境変数
BAJUTSU_ALLOW_REMOTE_BUILD=1)で明示的に opt-in してください。opt-in がなければ、アップロードされたバンドルの build が
抑止されるのと同じように build を抑止したまま run が進みます。ネットワーク越しに届いた config から、黙ってホスト側で
コマンドが実行されることはありません。
XCUITest runner をその場でビルドする driver.runner.build にも、同じ判定を適用します。このコマンドを実行するのは
serve 自身ではなく、serve が起動する run です。run は driver.runner.testRunner のファイルが無いときにこのコマンドを実行します。
アップロードされたバンドルと、--allow-remote-build なしで UI からバインドした Git config では、起動された run が
このビルドを拒否し、driver.runner.build withheld というエラーで失敗します。こうした config では、.xctestrun を
ビルド済みの状態で testRunner の位置に同梱してください。run はそのファイルをそのまま使います。
Git config source の非公開リポジトリへのアクセス(BE-0224)¶
serve(や CLI)が config を 非公開の GitHub リポジトリから読むとき、すなわち github: の spec
(BE-0063)のときは、読み取りを
許可する資格情報が要ります。公開リポジトリには要りません。資格情報は取得のたびに解決するので、
ローテーションしても再起動なしで反映されます。解決の順序は次のとおりです。
- 設定済みの GitHub App installation(無人ホストではこれを推奨します。下記参照)
- Web UI の「From a Git repository」ダイアログで入力した資格情報(
BAJUTSU_GIT_CONFIG_TOKENに保持します。下記参照) - 環境変数の
GITHUB_TOKEN/GH_TOKEN gh auth token(自分のマシンで対話的なghセッションを持つ開発者向け)- いずれも無ければ匿名(公開リポジトリのみ)
最小権限で付与してください。 classic の repo スコープの個人アクセストークン(PAT)は、その人が見える
すべての非公開リポジトリに読み書きを与えます。「テスト用リポジトリを 1 つ読む」には過剰です。対象の
リポジトリだけに Contents: read 権限だけで絞った細粒度(fine-grained)の PAT、または GitHub App
installation を選んでください。
無人のデーモンへトークンを渡す¶
launchd や systemd の serve には対話的な gh セッションが無いので、デーモンのレベルでトークンを注入します。
手順 1 の LaunchAgent なら plist の EnvironmentVariables に加えます。Linux や
systemd では unit の Environment=(または誰でも読めるわけではない EnvironmentFile=)を使います。ただし PAT は
人に紐づき、その人のアクセスを帯び、ローテーションや離任で失効します。無人で非公開リポジトリを読むサービスは、
サービス自身として認証すべきで、それが GitHub App です。
GitHub App(サービスに推奨)¶
GitHub App の installation トークンは短命で、その installation のリポジトリに限定され、人ではなくサービスに紐づきます。 Contents: read を持つ App を作り、対象のリポジトリにインストールしたうえで、次を与えます。
export BAJUTSU_GITHUB_APP_ID=123456
export BAJUTSU_GITHUB_APP_PRIVATE_KEY_FILE=/etc/bajutsu/app.pem # または BAJUTSU_GITHUB_APP_PRIVATE_KEY で直接
# 任意: installation を固定する。無ければ取得対象のリポジトリから解決します
export BAJUTSU_GITHUB_APP_INSTALLATION_ID=7654321
App 経路は、秘密鍵で短命な RS256 の JSON Web Token(JWT)に署名し、それを installation トークンと交換します。
署名には cryptography を使い、githubapp extra でオンデマンドに導入します(uv sync --extra githubapp)。PAT で
認証するデプロイがこれを読み込むことはありません。
App の資格情報はプロセスの環境から読むので、設定した App はすべてのリクエストに適用され、PAT より優先します。 Web UI で入力したものも含みますし、ホスト型の複数組織のデプロイでは各組織の保存した資格情報よりも優先します。App の identity ですべての取得を認証させたいのでなければ、どちらか一方だけを設定してください。
Web UI から資格情報を入力する¶
「Open config」ダイアログの 「From a Git repository」 ソースには資格情報の入力欄があります。細粒度の PAT や
App トークンを入力すると、serve の秘密ストアを通じて write-once で保存します。Claude API キー
と同じストアで、値はマスクして表示し、読み出すことはありません。ローカルの serve では、bajutsu 専用の変数
(BAJUTSU_GIT_CONFIG_TOKEN)にプロセスの寿命のあいだ保持し、取得時には環境の GITHUB_TOKEN より先に読みます。あえて
GITHUB_TOKEN そのものは使いません。UI で資格情報を入力したり消したりしても、起動時にエクスポートしたトークンに
触れないためです。データベースを持つサーバは保存時に暗号化し、組織ごとにスコープするので、各テナントの保存した
資格情報はそれぞれ独立です。ローカル起動とホスト型バックエンドは、どちらもこのデータベースを持ちます。
バインドは、組織が保存した値を自身の取得処理に渡します(BE-0449)。この値の優先順位は、設定した GitHub App の次で、
環境のトークンより前です。値は取得処理にだけ届き、レスポンスには載りません。アクセス不足で
バインドが失敗したときは、ダイアログ内にその場で診断を表示します。メッセージは、レート制限、組織のシングルサインオン
(SSO)の認可不足、トークンの拒否、あるいは「<owner>/<repo> に Contents: read を持つ資格情報を用意してください」
といった、本当の原因を名指します。素の 404 では終わりません。
Tier B、サーバ backend のセルフホスティング¶
Tier A は、1 台の Mac で動くサーバとそのローカルの worker です。Tier B は BE-0015 のサーバ backend、すなわち FastAPI の
コントロールプレーン(Postgres、S3 互換ストレージ(MinIO)、GitHub OAuth、RBAC、per-user クォータ)を Linux
ノードで動かし、1 台以上の Mac をワーカーにします。既定ではシングルテナント(全ユーザが 1 つの
default org)で動き、config で org を宣言すれば複数 orgに対応します(後述の「複数 org」を参照)。すぐ動かせる
一式は deploy/self-host/(compose、Dockerfile、.env.example)にあります。
Mermaid ソース
flowchart TB
laptops(["チームの端末"])
control["Linux ノード — docker compose<br/>bajutsu serve --asgi<br/>postgres・minio<br/>[+ Linux web ワーカーのコンテナ]"]
macWorker["Mac ワーカー × N(ベアメタル)<br/>bajutsu worker(iOS・XCUITest)<br/>bajutsu run・Simulator"]
webWorker["Linux web ワーカー(web)<br/>bajutsu worker・Chromium"]
laptops -->|"HTTPS(Tailscale tailnet、<br/>またはホスト名で Caddy)"| control
control -->|"job(HTTP)"| macWorker
macWorker -->|result| control
control -->|"job(Tailscale tailnet)"| webWorker
webWorker -->|result| control
Linux のコントロールプレーンは安価で、Mac ワーカーが Simulator の run を担う希少な部分です。フリートは backend ごとに異なる構成になります。Mac の iOS ワーカーは iOS Simulator のために Aqua の GUI セッションが 要るので ベアメタルで動かし(Tier A と同じ)、Linux の web(Playwright)ワーカーはヘッドレスなので コンテナで動かします(BE-0173)。web backend には GUI セッションの制約がないためです。どちらも同じ コントロールプレーンから HTTP でリースを受けます。web ワーカーのコンテナは cloud SDK もオブジェクトストレージの 秘密情報も不要で(BE-0160)、必要なのはコントロールプレーンの URL とトークンだけです。混在フリートは任意です。 既定は iOS だけの構成で、これは変わりません。web の run をホストするときに web ワーカーを足してください (§ Linux web ワーカーを足す)。
config のソースはデプロイ形態で変わります(BE-0108)。「Open config」ダイアログは、アクティブな config
を最大3つのソースからバインドします。Git リポジトリ、アップロードした .zip バンドル、そして
serve ホストの --root を辿るファイルブラウザです。サーバ backend(この Tier)ではファイルブラウザを
外します。UI から隠すだけでなくサーバ側でも拒否し(/api/fs と POST /api/config の path ブランチは 403
を返します)、Git とアップロードの2つだけを残します。ホスト型のユーザは共有ワーカーのファイルシステムと
関係を持たないため、オペレータの --root を辿っても自分が所有する config はバインドできません。ファイル
ブラウザを外すことで、ログイン済みの全ユーザにそのツリーのディレクトリ一覧を見せてしまう露出も避けられ
ます。ローカル起動(Tier A、セルフホストの単一 Mac)では3つのソースすべてを残します。そこではファイル
システムがオペレータ自身のものだからです。
config、シナリオ、アプリバイナリ全体で見る、ローカルとホスト型の違い¶
ここまでの説明は「どうデプロイするか」を軸にしています。ここでは視点を変え、serve が管理する状態の種類
ごとに何が変わるかをまとめます。
以下の「ローカル」は、Tier A と、ノート PC 上で素の make serve を動かす場合の両方を指します。どちらも
hosted: false で動作します。Tier B のサーバ backend は BAJUTSU_SERVER_STORE にバケットを指定するので、
hosted: true になります。バケットを指定せずに1台のマシンで起動したサーバ backend は hosted: false の
ままです。この場合は、後の節「1台のマシンで動かすサーバ backend」で扱います。
| 状態 | ローカル(hosted: false。Tier A、または素の make serve) |
ホスト型(hosted: true。Tier B のサーバ backend) |
|---|---|---|
| config | ファイルブラウザ + Git + アップロード。自分のファイルシステムで、パスの閉じ込めなし | Git とアップロードのみ。ファイルブラウザは無効、403(BE-0108) |
| シナリオと run の成果物 | scenarios/、runs/ をディスク上に保持し、キューと run の履歴は .bajutsu/queue.db に保持。ソフトデリートは run のツリーに .deleted の印を残す |
オブジェクトストレージ(S3/GCS)+ Postgres。ソフトデリートは deleted_at を設定(BE-0239) |
| アプリバイナリ | subject.path をディスク上に保持。存在しないときだけ build(アップロードされたバンドルはビルド済みのバイナリを持つため build しません) |
アップロードされたバンドルのバイナリは presigned URL で worker に届き、build は走りません(BE-0413)。Git 由来の config は引き続き worker がチェックアウトから build します。リモート build はゲート付き(BE-0121) |
| 実機の画面を見ながらの作成 | Capture モードと Edit モードのライブピッカーが、serve プロセス内に driver を開いたまま保持 |
どちらも提供しない。2つの操作は理由付きで無効化(#1721) |
- config。 どちらの側も最大3つのソースからバインドしますが、
hostedが true になった瞬間にファイル ブラウザだけが消えます(前述のとおりです)。パスの閉じ込めを決めるのは Tier ではなくソースです。ローカル ファイルの config は自分自身のディレクトリを基準に解決し、閉じ込めはありません(兄弟ディレクトリを指すことも できます)。一方、Git またはアップロード由来の config は信頼できない入力として扱われ、paths.scenarios/paths.baselines/subject.pathは、どちらの Tier でバインドしたかに関わらずチェックアウトまたはバンドルのルートに 閉じ込められます(configurationの「Git リポジトリからの config」の節を参照してください)。 ホスト型ではローカルファイルのソースをそもそも提供しないため、ホスト型の config は結果としてすべて閉じ込め られます。これはファイルブラウザを外したことの副作用であり、別立てのルールではありません。 - シナリオと run の成果物。 ローカルでは、シナリオストアと run の履歴がふつうのディレクトリツリー
(
scenarios/、runs/)を読み書きします。ソフトデリートすると、run のツリーに.deletedの 目印が付きます。ホスト型 では、両方ともコントロールプレーンのオブジェクトストレージ(BAJUTSU_SERVER_STORE。S3 互換または GCS)と、 run ごとの Postgres の行に置かれます。そのためソフトデリートは、ディスク上でバイトを移動させる代わりにdeleted_atを設定するだけです(後述の「run の削除と、ゴミ箱の保持期間」を参照してください)。 - 実機の画面を見ながらの作成。 Capture モードは、スクリーンショットをクリックしてシナリオを記録します。
Edit モードのライブピッカーは、デバイスに映っている画面に対してセレクタを解決します。どちらも、作成者が
クリックを続けているあいだ
serveプロセス自身のなかに driver を開いたまま保持します。ホスト型では デバイスが worker 側にあり、ブラウザは worker と直接やり取りしません。そのため/api/capture/*のルートは すべてローカル専用で、ホスト型のデプロイは404を返します。起動時の読み取り(GET /api/config)は、この 提供可否をケーパビリティのフラグとして報告します。ホスト型の Author タブは、最初の呼び出しが失敗する モードを見せる代わりに、2つの操作をサーバ自身の理由付きで無効化して Edit モードで開きます(#1721)。 ホスト型でないデプロイは、どちらのトランスポートでも capture のルートを提供します。ローカルのbajutsu serve --asgiも、サーバ backend のローカル起動も、デバイスがその機械の上にあるので Capture を 残します(BE-0449)。Record タブは動き続けます。POST /api/recordは run と同じように job をディスパッチするため、AI 経由での 記録はホスト型でも動きます。 - アプリバイナリ。 アップロードされたバンドルはすでにビルド済みのバイナリを持っているため、Tier に関わら
ず
subject.buildは実行されません(_governed_build、DESIGN §1「Bajutsu はアプリをビルドしない」)。ホスト型 では、worker がそのバイトを受け取る必要があります。job のリース応答に含まれるbundle_urlsフィールドが、 バンドルを構成する各オブジェクトへの presigned GET URL を1つずつ運び、worker はそれを HTTP 経由で取得して run を始める前に自分のワークスペースへ再構成します(BE-0413)。共有ファイルシステムは不要で、build も走り ません。Git 由来(またはローカルではファイルブラウザ由来)の config は従来どおり、バインドした config からsubject.pathを解決し、それが存在しなければ config のsubject.buildコマンドを実行します。ホスト型では、Mac の worker が、コントロールプレーンがその job 用に解決したのと同じチェックアウトの素材から build します。共有 ファイルシステムではなく、署名した presigned URL 経由でバイトをやり取りします(前述の BE-0160)。リモート build のゲートは Tier とは独立しています。UI の「from Git」 ピッカーで後からバインドした config は、その UI がノート PC 上の Tier A にあるか Tier B のコントロール プレーンにあるかに関わらず、subject.buildが既定で抑止されます。起動時に与えた config だけがオペレータ信頼として 扱われます(前述の「リモート config のコマンド実行」を参照してください)。web(Playwright)backend には どちらの側にもバイナリという概念自体がなく、ブラウザエンジンがオンデマンドでインストールされるだけです。
1台のマシンで動かすサーバ backend(BE-0449)¶
bajutsu serve は、クラウドのサービスがない1台のマシンで起動し、そこでは環境変数も要りません。
サーバ自身は job を1つも実行しません。ビルドの段階を含む run、run-set、triage、record、crawl
のすべてを、キューに積みます。同じマシンで動く bajutsu worker が各 job をリースして実行し、
make serve はその worker を起動します。worker がいなければ job はキューで待ち、UI は利用できる
worker がないことを表示します。
サーバのディスク上のパスでファイルを指定する job は、サーバのマシンの worker だけに渡ります。ローカルで
起動したサーバは、ランダムなマシン識別子を runs ディレクトリの隣の .bajutsu/machine-id に保存します。
設定と runs ディレクトリをそのパスで指定する run、triage、record、crawl は、capability トークン
machine:<id> を必要とします。worker は、このファイルを読む --server-state-dir <ディレクトリ> か、
--machine-id <id> を付けて起動したときに、このトークンを広告します。make serve は、自分で起動する
worker に --server-state-dir を渡します。別のマシンの worker や Device Farm の worker は、このような job を
リースしません。サーバのマシンの worker が問い合わせるまで、UI は利用できる worker がないことを表示し続けます。
アップロードしたバンドルから実行する run のように、ファイルを送る job はマシンのトークンを必要とせず、
どの worker にも渡ります。識別子を渡されてもサーバのファイルを持たない worker は、サーバのマシンの worker が
必要だというメッセージで job を失敗させます。
--backend フラグは非推奨です。以前のサーバには、サーバのプロセス内で job を実行する local backend と、
job をキューに積む server backend がありました。今はどちらの値でも同じサーバが起動するので、このフラグは
何も変えません。bajutsu serve は local と server を受け付けて警告を表示し、次のリリースでフラグを
取り除きます。コマンドライン、LaunchAgent、コンテナのコマンドから外してください。未知の値を渡すと、
これまでどおり起動を止めます。
triage の job は、診断する run をサーバの runs ディレクトリから読みます。job はそのディレクトリ、
バインドした設定、シナリオのソースを、サーバのディスク上の絶対パスで指定します。結果の triage.json は
run ディレクトリに書き、UI はそこから読み戻します。同じマシンの worker は、ローカルの run と同じく設定の
ディレクトリから triage を実行します。triage の job も run と同じく、サーバのマシンの worker だけに渡ります。
--ai を付けた triage も、キューのほかの job と同じく AI キーを lease から受け取ります。
UI で設定したキーは、job 仕様に入らないまま調査役のエージェントに届きます。
crawl と record の job も、同じマシンの worker を前提とする点は同じです。crawl は画面マップを
サーバの runs ディレクトリに書き、record は作成したシナリオをターゲットのシナリオディレクトリに書きます。
crawl の実行中、worker は画面マップが新しくなるたびに、その内容を POST /api/worker/artifact に送ります。
サーバは各スナップショットを、job のイベントストリームの artifact イベントとして Crawl タブへ中継します。
そのため、worker の探索とともにグラフが育ちます。ファイルは永続的な写しとして残り、ページは
job の終了時にそれを読みます。worker は 2 MiB を超えるスナップショットを送りません。job のライブ予算は
16 MiB です。予算を使い切ると、ストリームはそのことを一度だけ伝え、ページは代わりにファイルを読みます。
別のマシンの worker では、crawl の実行中にサーバのディスクにファイルがありません。その場合、グラフは
job の終了時に更新されます。
record は一時停止して、ブラウザの前にいる人へ助けを求めることがあります(ワンタイムパスワードの入力など)。
worker はその要求を POST /api/worker/handoff に送り、ページは従来どおり要求を表示します。人の回答は、
サーバがシークレットのキーで暗号化し、jobs テーブルに置きます。record が待つあいだ、worker は毎秒
POST /api/worker/handoff-response に問い合わせます。worker はそこから回答を受け取り、record の標準入力に
書き込みます。回答は、worker が読んだ時点か job が終わった時点でテーブルから消えます。サーバは、record の
待ち時間(5 分)より古い回答を捨てます。待っている record への取り消しも同じ問い合わせで届くので、
次のハートビートを待ちません。
中継のルートは、次の3つの規則で守ります。
- 各ルートは、lease を持つ worker からの送信だけを受け付けます。ほかの worker には
409を返します。handoff のルートはrecordの job だけを受け付けます。要求は一度に1つで、job あたりの合計は 64 MiB までです。 - ブラウザやマシンのログインで来た呼び出しには
403を返します。これらのルートが受け付ける資格情報は、worker が持つ共有トークンだけです。 - handoff への回答は job 自身の org での editor の操作として扱い、取り消しと同じ方法で確かめます。
デプロイが設定しなかった項目ごとに、サーバは
ローカルの既定値を補います。既定値はすべて、runs ディレクトリの隣の .bajutsu/ ディレクトリに置きます。
サーバはこのディレクトリを所有者だけが使える権限(0700)で作り、Git はこのディレクトリを無視します。
これらの既定値を使うのは、BAJUTSU_SERVER_STORE が未設定のときです。バケットを指定したデプロイには、
デフォルトのデータベースを用意しません。レプリカごとに SQLite のファイルを持つと、キューが分かれてしまうためです。
そうしたデプロイは BAJUTSU_DATABASE_URL を設定する必要があり、設定しなければサーバは起動を拒否します。
サーバ自身は job を実行しないので、キューのないサーバは何も実行できないからです。
この形には、通常の pip install bajutsu だけで足ります。FastAPI、uvicorn、SQLAlchemy、Alembic、
cryptography は基本の依存に含まれ、SQLite は Python に同梱されています。server の extra は S3 の
バケット向けに boto3 を、db の extra は PostgreSQL 向けに psycopg を追加します。hosted のデプロイは、
Tier B のイメージと同じく、これらの extra を引き続きインストールします。
| 未設定の項目 | ローカルの既定値 |
|---|---|
BAJUTSU_DATABASE_URL |
SQLite のファイル .bajutsu/queue.db です。Alembic を実行するオペレータがいないので、サーバが起動のたびに最新のスキーマへ移行します。 |
BAJUTSU_SECRETS_KEY |
.bajutsu/secrets.key に一度だけ生成する Fernet キーです。所有者だけが読める(0600)通常のファイルです。既定の SQLite を使うときに限り、BAJUTSU_SECRETS_KEY を設定すればそちらを使います。 |
BAJUTSU_SERVER_STORE |
file:// ストアです。サーバ自身の /api/store/objects/ ルートが配信します。default org の run は runs のツリーに置き、それ以外のオブジェクトはすべて .bajutsu/objects/ に置きます。 |
BAJUTSU_HOSTED |
false です。バケットを指定したときは true です。 |
データベースを設定した場合は、これまでの規則のままです。BAJUTSU_DATABASE_URL を設定して
BAJUTSU_SECRETS_KEY を設定しなければ、サーバは起動を拒否します。オペレータ自身のデータベースのために
サーバがキーを生成することはありません。起動時には、すでにある安全でないキーファイルも拒否します。
シンボリックリンク、別のアカウントが所有するファイル、グループやその他に権限を与えるファイルが該当します。
共有ホストで別のローカルアカウントがキーを読めると、保存したシークレットがすべて漏れるためです。
1つの .bajutsu/ を使えるサーバは、一度に1つだけです。サーバは動いているあいだ、.bajutsu/serve.lock
をロックしています。同じディレクトリで2つ目の bajutsu serve を起動すると、そのディレクトリ名を示して
起動を拒否します。2つのサーバが同じディレクトリを使うと、1つのキューを共有するためです。互いに相手が
使った job の ID を払い出してしまい、どちらの worker も相手の job を引き受けてしまいます。1つの
チェックアウトから2つのサーバを動かすときは、それぞれの --runs に、親ディレクトリの異なる runs
ディレクトリを指定してください。.bajutsu/ は runs ディレクトリの隣に置かれるためです。または、それぞれに別の
BAJUTSU_DATABASE_URL と BAJUTSU_SECRETS_KEY を指定してください。ロックはプロセスの終了とともに外れるので、異常終了した
サーバが後始末の必要なファイルを残すことはありません。
ファイルストアはバケットと同じキーの配置を使い、違いは1点だけです。default org の run の
アーティファクト(キーは artifacts/<run id>/)は、bajutsu run が書く場所(runs/<run id>/)に
そのまま置きます。そのため、コマンドラインで書いた run は、ファイルを動かさずにストア経由で読めます。
すでに runs/ の下にある run も同じです。それ以外のオブジェクトは、バケットのキーのまま
.bajutsu/objects/ に置きます。アップロードしたバンドルと、他の org の run、シナリオ、ベースラインが
該当します。default org のシナリオとベースラインは、次の小節で述べるとおりローカルのツリーに置きます。
これらのオブジェクトを runs/ の外に置くことで、テナントが分かれます。default org から acme や
scenarios という名前の run を求めても何も見つからないので、他の org の run やストアのフォルダを
読むことも消すこともできません。
サーバは runs ディレクトリそのものには手を加えません。runs/ がなければ作りますが、権限は変えません。
runs/ がシンボリックリンクのとき(容量の大きいディスクへ移した場合など)は、リンク先をたどって使います。
各キーは解決した先のディレクトリの中に閉じ込めるので、その外には届きません。所有者だけが使える権限
(0700)にしてシンボリックリンクを拒否するのは、サーバが所有する .bajutsu/objects/ だけです。
サーバとコマンドラインは同じ runs のツリーを使います。サーバで削除した run は、.deleted という目印を
置いたまま runs/<run id>/ に残ります。bajutsu flakiness --history と bajutsu triage --flaky は
この目印のあるツリーを読み飛ばします。そのため、コマンドラインから見ても、その run は削除したままです。
ブラウザとワーカーは、保存したファイルに署名付き URL でアクセスします。サーバは各 URL に、ハッシュベースの
メッセージ認証コード(HMAC)のキーで署名します。このキーは .bajutsu/store-signing.key にあり、
同じ 0600 の規則で扱います。各 URL は、サーバに渡した --host を指します。ワイルドカードで bind
したときは 127.0.0.1 を使います。これらのルートを配信するのは FastAPI のトランスポートだけです。そのため、バケットのないサーバは自動で
--asgi に切り替え、起動時にその旨を表示します。URL には起動時に決めたポートが入るので、このサーバは
--port 0 を拒否します。
run の履歴は、ディレクトリの一覧ではなく runs テーブルから読みます。そこでサーバは
起動時に、runs/ の下の run のツリーをすべて default org の runs テーブルへ登録します。読める
manifest.json がないツリーと、job がまだ書いている run は登録しません。登録は行の追加だけなので、
テーブルにすでにある run は、完了した job が書いたときの行のまま残ります。サーバの稼働中に bajutsu run が書いた run は、再スキャンで拾います。
admin が POST /api/runs/rescan を呼ぶと、新しいツリーを登録して {"indexed": <件数>} を返します。
バケットを使うデプロイでは run が runs/ の下にないので、再スキャンには 409 を返します。
hosted は独立したデプロイの設定で、BAJUTSU_HOSTED から読みます。この変数が受け付ける値は true、
false、1、0 です。それ以外の値では起動をエラーで止めます。変数が未設定なら、hosted はストアに
従います。BAJUTSU_SERVER_STORE にバケットがあれば true になり、既存の Tier B のデプロイはこれまでどおり
動きます。それ以外は false です。データベースがあっても hosted にはなりません。そのため、キューを持つ
ローカル起動でもファイルブラウザ(BE-0108)は残ります。record のデバイスの引き継ぎ(BE-0185)も
残ります。作成者がデバイスの前にいるからです。
ローカル起動が以前のローカル backend から引き継ぐもの¶
ローカル起動は、サーバのプロセス内で job を実行していたころのローカル backend が提供していた機能を 残します。下の各項目は、ローカル起動の default org に当てはまります。default org は、run が もともと runs のツリーにある org です。
| 機能 | ローカル起動での置き場所 |
|---|---|
| キャプチャモードと、エディタのライブなステップ選択 | hosted でないデプロイでは、FastAPI のアプリが /api/capture/* と /api/ant/login を配信します。UI もローカル backend と同じく Capture を提供します。 |
| UI で設定した secret | データベースに暗号化して保存します。job は worker の lease で値を受け取るので、AI のキーと ${secrets.X} の値を環境変数で受け取ります。 |
| シナリオ | 割り当てた config のシナリオディレクトリに保存します。シナリオの一覧が読むのと同じディレクトリです。 |
| ビジュアルのベースライン | 承認すると --baselines のディレクトリに入ります。run が参照するディレクトリと同じです。ファイルストアはこのディレクトリを baselines/ に割り当てるので、worker も同じファイルをダウンロードします。runs ディレクトリや .bajutsu/ を含む --baselines のディレクトリは、起動時に拒否します。 |
| AI プロバイダの設定 | runs ディレクトリの隣にある provider-settings.json を読み書きします。以前のローカル backend が使っていたファイルと同じです(BE-0184)。 |
| run のファイル | run は、bind した config、シナリオ、runs ディレクトリ、--baselines のディレクトリを、このマシン上のパスで指定します。同じマシンの worker は、config のディレクトリで run をビルドして実行し、run のツリーを runs/ に直接書きます。 |
サーバが保存した secret を平文で読む経路は2つです。どの HTTP レスポンスにも値は載りません(BE-0136)。
| 経路 | 値の使い道 |
|---|---|
| worker が job を lease する | lease の応答。受け取るのはその worker です |
| サーバが非公開の Git リポジトリから config を bind する | その取得処理の資格情報 |
lease が中継するのは、lease した job の org の secret だけです。共有トークンで認証した呼び出し元は値を 受け取ります。トークンのないループバックでの起動では、どの呼び出し元も受け取ります。lease の経路に届いた ブラウザやマシンのログインは、値を受け取りません。値は job の仕様に入らないので、キューのデータベースが 持つのは暗号化した行だけです。worker は値を job の環境変数に重ね、引数には載せません。job の環境変数には Git の資格情報を入れません。job は config を取得しないからです。
secret は、job のプロセスの読み込み方や動き方を変える変数を設定できません。サーバと worker は、そうした 名前を捨て、値を含めずに名前だけをログに残します。
| 拒否する対象 | 名前 |
|---|---|
| シェルとシステムの変数 | PATH、HOME、USER、SHELL、LANG、TERM、PWD、OLDPWD、LOGNAME、TMPDIR、DISPLAY、IFS、ENV、BASH_ENV、PS4、PROMPT_COMMAND |
| インタプリタのオプション | NODE_OPTIONS、NODE_PATH、RUBYOPT、RUBYLIB、PERL5OPT、PERL5LIB、JAVA_TOOL_OPTIONS、_JAVA_OPTIONS |
| 名前の接頭辞 | LD_、DYLD_、PYTHON、BAJUTSU_ |
macOS と Linux では名前を厳密に比べ、Windows では大文字と小文字を区別せずに比べます。同じ規則は、config の
ai.keyEnv と evidence.secrets の名前にも当てはまります。拒否された ai.keyEnv があると、サーバは
ANTHROPIC_API_KEY を読み、警告をログに残します。
worker を待つ run は、待っている理由を示します。待機が終わるのは、run が求める能力をすべて宣言する 稼働中の worker が現れたときです。それまでは、次の3か所に、使える worker がないという通知が出ます。
- job の表示(
GET /api/jobs/<id>)のnoticeフィールドに出ます。 - job のライブストリーム(
/api/jobs/<id>/events)にnoticeイベントとして届きます。 - UI の run のステータス行に出ます。
lease のタイムアウトの範囲内に問い合わせかハートビートを送った worker を、稼働中とみなします。
bajutsu_unroutable_jobs のメトリクスも同じ範囲を使います。この通知は、そうした worker が問い合わせた
時点か、worker が run を lease した時点で消えます。
プロバイダの設定は、データベースへ移さずファイルに残します。こうすると、ローカル起動は以前のローカル backend が書いたファイルを読み書きするので、更新した利用者にも同じ選択が見えます。
ローカル起動の他の org は、.bajutsu/objects/ の下でバケットと同じ配置を使います。その org の
シナリオとベースラインは hosted のデプロイと同じ方法でワーカーに届くので、どのテナントも default org の
ツリーには書き込みません。
これを保つため、default org の配置にあるフォルダの名前(artifacts、baselines、scenarios、
uploads)は org の slug に使えません。POST /api/orgs も orgs: のエントリも、これらの slug を拒否します。
CI の run に job 単位でアーティファクトを差し替える(BE-0431)¶
プルリクエストの継続的インテグレーション(CI)が求める run は、多くの場合「このビルドのバイナリを、この
ブランチのシナリオで」というものです。POST /api/compose でもこの組を渡せますが、org のアクティブな config を
バインドし直すことになります。セッションを持たない呼び出し元は、この binding を共有しています。そのため、
同時に走る2つの CI が同じ binding を奪い合い、バインドのたびに org の記憶された構成も動きます。代わりに、
POST /api/run のボディは省略可能な2つのフィールドを受け付けます。どちらも、呼び出し元の org に保存済みの
アーティファクトを sha256 で指します。
| フィールド | job が受け取るもの |
|---|---|
binaryArtifact |
binary アーティファクト。指定した target の subject.path だけに置きます |
scenariosArtifact |
scenarios アーティファクト(zip)。その target の scenarios ディレクトリを置き換えます |
リクエストが指定しなかった側は、これまでどおり org の binding から解決します。binding 自体には手を
加えません。各アーティファクトは先に POST /api/artifacts/binary や POST /api/artifacts/scenarios で
アップロードしておきます。保存済みのバイトは GET /api/artifacts/exists で確かめれば送り直さずに済みます。
2つのフィールドに必要なロールは、POST /api/run がもともと要求する editor と同じです。
curl -X POST "$SERVER/api/run" -H "Authorization: Bearer $TOKEN" \
-H 'Content-Type: application/json' \
-d '{"scenario": "added.yaml", "target": "demo",
"binaryArtifact": "<sha256>", "scenariosArtifact": "<sha256>"}'
コントロールプレーンは、job を作る前にリクエストを検査します。
- org が保持していないアーティファクトを指定すると
400を返します。オブジェクトストアが応答できない ときは、再試行できる503を返します。アップロードがなかったと告げる400は返しません。 scenariosArtifactを指定すると、scenarioの値は zip 自身のエントリと、target の scenarios ディレクトリの下で照合します。ほかのどこにもないシナリオでも実行できます。zip の構成は compose と同じで、 エントリは config からの相対パス(scenarios/added.yaml)です。エントリはすべて target の scenarios ディレクトリの下に置きます。バインドしたバイナリやベースラインを差し替えで上書きしないためです。単一の YAML ファイルは拒否します。 ダイジェストにはファイル名がなく、scenarioと照合できないためです。subject.pathを持たない target(web の target)にbinaryArtifactを指定すると400を返します。- 単一プロセスの
serveは、どちらのフィールドも拒否します。その構成では job がオペレータ自身の プロジェクトディレクトリで動くため、差し替えで上書きするわけにはいかないからです。 POST /api/run-setも、どちらのフィールドも拒否します。ファンアウトのジョブは、ターゲットのプラットフォームを 扱う worker ならどれでもリースでき、Device Farm の worker もその1つです。差し替えを Device Farm への リクエストに対応づける作業は、まだ済んでいません。
リースは、指定された差し替えごとに presigned GET(binary_url、scenarios_url)を、リースした job の
org の下で署名します。worker は各ダウンロードを sha256 で検証し、その job 専用のツリーを組み立てます。
このツリーは、差し替えのない job が使うツリーとは別になります。bundle の job では、差し替え用のツリーは
キャッシュ済み bundle のローカルコピーなので、bundle の zip は一度しか取得しません。取得が 404 なら
job を終了します。ダイジェストが一致しない場合はリースの失効に任せ、別の試行で成功できるようにします。
run の manifest.json は、provenance の下に binaryArtifact / scenariosArtifact を記録します。
バインドした bundle の識別子がある場合は、その隣に並びます。差し替え用のツリーは worker の .overrides/
ディレクトリに置かれるので、.bundles/ のキャッシュと一緒に整理してください。
1. コントロールプレーンを起動する¶
cd deploy/self-host
cp .env.example .env # BAJUTSU_SERVE_TOKEN, POSTGRES_PASSWORD, AWS_*(MinIO), bucket を設定
mkdir -p config && cp /path/to/bajutsu.config.yaml config/ # 公開する target の一覧
docker compose up -d # postgres + minio + migrate(alembic upgrade head)+ bajutsu
migrate が bajutsu の起動前に Alembic マイグレーションを head まで適用し、minio-init がバケットを
作成します。コントロールプレーンは :8765 で待ち受けます。
web UI のバージョンバッジ(BE-0272)に、このイメージが動作しているコミットを表示したい場合は、そのコミットを
ビルド時に渡します(BE-0277)。イメージには読み取れる .git が含まれないため、バッジはこの埋め込み値に
フォールバックします。
GIT_COMMIT=$(git rev-parse HEAD) docker compose build bajutsu # そのあと `docker compose up -d`
docker-compose.yml は、呼び出し元のシェル(または .env のエントリ)から GIT_COMMIT を解決し、
bajutsu サービスのビルド引数に渡します。設定しなければ、バッジは従来どおりバージョンだけを表示します。
compose を通さずコントロールプレーンのイメージを直接ビルドする場合は次のようにします。
docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) -f deploy/self-host/Dockerfile .
公開ポートは BIND_ADDR(既定は 127.0.0.1)にバインドします。Mac の worker が別ホストから MinIO に届く
ようにするには、.env の BIND_ADDR をノードの tailnet IP に設定してください。公開インターフェースを
持つホストで 0.0.0.0 にはしないでください。成果物バケットを露出させてしまいます。
アーティファクト/シナリオ/ベースラインに加え、アップロードされた zip バンドル(BE-0243)のストアも、
BAJUTSU_SERVER_STORE という1本の URI で選びます(BE-0204)。s3://bucket/prefix(S3 互換。
この compose が同梱する MinIO)と gs://bucket/prefix
(Google Cloud Storage)のどちらかを指定できます。すでに Google Cloud 上で他のスタックを動かしているなら、
docker-compose.yml から minio と minio-init サービスを外し、BAJUTSU_SERVER_STORE を GCS バケットに
向けて、コントロールプレーンのイメージの deploy/self-host/Dockerfile
のインストール行に gcs extra を追加してください(.[server,worker,db,oauth,gcs])。S3 互換バケットを
別途用意する必要はなくなります。
以前の BAJUTSU_S3_BUCKET / BAJUTSU_S3_PREFIX の組み合わせを使っていた環境からアップグレードするときは、
prefix を URI のパスに畳み込んでください。BAJUTSU_S3_BUCKET=bajutsu と BAJUTSU_S3_PREFIX=tenant/ の
組み合わせは BAJUTSU_SERVER_STORE=s3://bajutsu/tenant/ になります。prefix を畳み込まずに設定すると、
その prefix 配下にあった既存のキーが解決できなくなります。
2. GitHub OAuth を足す(任意)¶
オペレータが数人なら共有トークン(BAJUTSU_SERVE_TOKEN)だけで十分です。ユーザごとのブラウザログインには、
GitHub OAuth アプリを作り(callback は https://<your-host>/api/oauth/callback)、.env に
BAJUTSU_OAUTH_GITHUB_CLIENT_ID/_SECRET/_REDIRECT_URI を設定します。
OAuth を構成すると、アクセスは手作業の login リストではなく GitHub organization と Team のメンバーシップに 従います(BE-0313)。
- サインインと viewer ロールは org メンバーシップに従います。構成済みの org のメンバー(明示の
members、githubOrgsに挙げた GitHub org の一員、またはgithubTeamsに挙げた Team かeditorTeamsに 挙げた Team の 直接メンバー。orgs:を参照)だけがサインインでき、成功すると viewer(閲覧のみ)が付きます。githubTeamsは粒度の細かい 指定で、GitHub org 全体を通さずに 1 つの Team だけを通します。複数チームで共有している organization の うち、1 つの Team だけがこのデプロイに触れてよい場合に必要になる単位です。GitHub の Teams API が エラーを返している間は、/user/teamsが fail closed なので、所属が Team だけの login は障害が続く あいだ拒否されます。どの org にも一致しない login は 拒否されるので、OAuth を使う構成ではorgs:ブロックの宣言が必須です。ただし、構成済みの admin Team の メンバーだけは例外で、このゲートを直接通過します(下の admin を参照)。データベースも繋いだ構成では、 このメンバーシップを config ファイルではなくデータベースが持ちます。最初の一度だけ同じorgs:ブロック から書き写し、以後は Web UI から管理します(下の複数 orgを参照)。どちらの構成でも、どの org がどの target を持つかは引き続きorgs:ブロックが決めます。 - editor は org の
editorTeamsに従います。挙げたフラットな GitHub Team のいずれかの直接メンバーが、run、 record、scenario の編集をできます。editorTeamsは昇格させるだけでなくサインインも許すので、ここに挙げた Team をgithubTeamsに重ねて書く必要はありません。1つの Team ではなくリストを持つのは、複数の GitHub organization にまたがる org が organization ごとの書き込み Team を挙げられるようにするためです。旧来の 単数形editorTeamを書いた config もそのまま動きます。serveがそのキーをeditorTeamsに畳み込む からです。ただし、文書に載るのは複数形だけなので、名前は変更してください。 - admin はサーバ全体で 1 つ以上の GitHub Team、
BAJUTSU_OAUTH_ADMIN_TEAMS(カンマ区切りのリスト。各要素は"<github-org>/<team-slug>"の形で、<team-slug>は GitHub 自身が小文字化した slug であり、Team の 表示名ではありません。githubTeamsやeditorTeamsと同様、各エントリは 1 つのフラットな Team を指し、 その下にネストした Team は一致しません。また、GitHub が org login と Team slug を大文字小文字の区別なく 解決するのに合わせて、大文字小文字を区別せずに比較します)に従います。そのメンバーはサーバ設定(config、API キー、provider)も変更 できます。admin はデプロイ全体で 1 段のロールなので、どの org を越えても信頼できるメンバーの Team だけを 指定します。上の viewer と editor の場合とは異なり、構成済みの admin Team のいずれかのメンバーは、サインインのゲートを 直接通過します。admin Team を、どこかの org のgithubTeamsやeditorTeamsに挙げる必要も、その organization をgithubOrgsに含める必要も、そのメンバーをmembersに列挙する必要もありません。そのため、orgs:ブロックが壊れている、あるいは 存在しない状態でも、admin はサインインして、サーバの向き先を修正済みの config へ張り替えられます。 ただし、この経路も GitHub の Teams API の障害までは越えられません。/user/teamsは fail closed なので、障害のあいだは admin Team のメンバーシップだけを頼りにした login も、ほかの login と同じく 拒否されます。この性質により、BAJUTSU_OAUTH_ADMIN_TEAMSは、ロールの対応づけだけでなくサインインの資格情報そのものになります。各エントリの GitHub organization 側は、実際に自分が管理する organization でなければなりません。その organization を管理する人は誰でも、 一致する slug の Team を作って admin としてサインインできてしまうからです。
メンバーシップはログインのたびに読み直されるので、GitHub org や Team を抜けると、対象ユーザの次のサインインで
反映されます。サーバ側のリストを編集する必要はありません。ログインは常にこれらのメンバーシップを読むために
read:org scope を要求するので、同意画面には organization へのアクセスが表示されます。
ログインリストからの移行にあたって。 ロールの由来が変わること以外にも、2 点変わります。1 つ目は、サインインが
今後は構成済みの members/githubOrgs/githubTeams/editorTeams の全員を通すようになることです。旧来の BAJUTSU_OAUTH_ALLOWED_USERS
がその org の全メンバーより狭い範囲を許可していたなら、切り替え前に orgs: を絞ってください。org のゲートだけに
なると、その分アクセスが広がります。2 つ目は、BAJUTSU_OAUTH_ALLOWED_USERS/_ADMINS/_VIEWERS が単純に無視さ
れるようになることです。切り替える前に、admin と editor のそれぞれを Team メンバーシップとして宣言し直してくだ
さい。editorTeams や BAJUTSU_OAUTH_ADMIN_TEAMS でまだカバーされていない login は、次のログインで viewer に
落ちます。すでに旧来の単数形 BAJUTSU_OAUTH_ADMIN_TEAM を設定していたデプロイは、同じタイミングで
BAJUTSU_OAUTH_ADMIN_TEAMS に改名してください。旧名はもう読まれません。serve は、次の 4 つの
いずれかに当てはまるとき、起動時に stderr へ警告を出します。廃止名がまだ設定されているとき、
BAJUTSU_OAUTH_ADMIN_TEAMS の解決結果が空のリストになるとき、エントリが正しい
"<github-org>/<team-slug>" の組でないとき、そして GitHub OAuth が部分的にしか構成されていない
ときです。4 つ目は、BAJUTSU_OAUTH_GITHUB_CLIENT_ID / _CLIENT_SECRET / _REDIRECT_URI のどれか
1 つでも未設定の状態を指します。このとき GitHub のサインインはすべて 404 になり、代わりに共有トークンの
ログインが静かに有効へ戻ります。BAJUTSU_SERVE_TOKEN も未設定なら、共有トークンへも戻れず、すべての
エンドポイントが認証なしで応答します。これらの警告はいずれも構造化
ログの event=server.startup_warning(どの警告かを示す check フィールド付き。運用ログ
を参照)としても再送されるので、起動出力を誰かが読むことに頼らずアラートを設定できます。org ゲートが
拒否したサインインは event=oauth.denied として記録され、org モデルが一致しなかった理由を名指しします。
名指しの対象は orgs: ブロックか、メンバーシップをデータベースが持つ構成であれば org のテーブルです。
WARNING になるのは admin Team が1つも使える状態にない場合だけです。リストが空である、あるいは
全エントリが不正な形式である場合を指し、どちらも orgs: を直しにサインインできる admin が誰も残って
いない状態です。構成済みの admin Team に単に一致しなかっただけの
通常の拒否、および GitHub account をまったく必要としない4つの手前の失敗(OAuth が構成されていない、
CSRF の state 不一致、例外を発生させた exchange、identity を返さなかった exchange)は INFO になります。
通常の拒否は GitHub account を持つ誰でも到達できるため、アラートは event 名そのものではなく WARNING
をキーにしてください。そうしなければ、興味本位のサインイン試行がページングすべき状態を埋もれさせます。
アップグレード後はログの最初の数行を確認してください。
3 つ目は、セッションそのものです。POST /api/login を無効にするのは、OAuth を構成した後に新たなトークン
Cookie セッションが発行されなくなるだけで、それ以前にすでに発行されたセッションは無効になりません。OAuth を
有効にする前に共有トークンでサインインしていたブラウザは、そのセッションが持つ完全な権限(トークンで発行された
セッションには identity が無く、role のゲートがそもそも適用されないため)を、既定 7 日間の有効期限
(BAJUTSU_SESSION_TTL)が切れるまで保ち続けます。トークンのみの運用から OAuth に切り替えるデプロイは、この
7 日間の失効を待つのではなく、切り替え時にセッションストアをローテーションする(既存の Cookie を強制的に無効化
する)ことをお勧めします。
OAuth を構成すると、共有トークンはワーカーの通信だけに狭まります。ワーカーのコントロールプレーンの route
(/api/worker/* の endpoint と、run のエビデンスアップロード URL の要求)を認可し、それ以外には効きません。ブラウザのトークンログイン(POST /api/login)は無効になり(人間の
サインインは GitHub OAuth だけになります)、生の Authorization: Bearer <token> はワーカー以外のどの endpoint にも
届きません。トークンでワーカー以外の endpoint をスクリプト運用していたデプロイは、OAuth を有効にするとその経路を
失います。OAuth を使わない構成(単一 Mac の閉じたネットワーク)では、トークンは従来どおりすべてに届きます。
CI ジョブを認証する(任意、BE-0414)¶
継続的インテグレーション(CI)のジョブは、上の 2 種類のどちらの呼び出し元でもありません。ブラウザでの サインインはできません。そして直前の段落が述べた事情は、そのまま問題になります。OAuth を有効にすると、 共有トークンはワーカー以外の endpoint に届かなくなるからです。すべてのパイプラインに長命のシークレットを 配る代わりに、 BE-0414 は、 CI プラットフォームがすでに発行している OpenID Connect(OIDC)トークンでジョブを認証します。そのトークンを 一度だけ交換して、短命のマシンセッションを発行します。パイプラインはシークレットを一切保持しません。 デプロイの側は「トークンが提示された」ではなく「どのリポジトリが実行したか」を記録できます。
CI 側に登録作業はありません。 GitHub App、OAuth app、ID プロバイダの登録は、どれも要りません。GitHub Actions の ジョブは、権限を 1 つ宣言してトークンを要求するだけです。
jobs:
e2e:
runs-on: ubuntu-latest
permissions:
id-token: write # GitHub 側の準備はこれだけ
steps:
- name: OIDC トークンをマシンセッションと交換する
run: |
set -o pipefail
token=$(curl -sSf -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$BAJUTSU_AUDIENCE" | jq -er .value)
curl -sSf -c cookies.txt -X POST "$BAJUTSU_URL/api/oidc/exchange" \
-H 'Content-Type: application/json' \
-d "{\"token\": \"$token\", \"org\": \"acme\"}"
env:
BAJUTSU_URL: https://bajutsu.example.com
BAJUTSU_AUDIENCE: https://bajutsu.example.com
パイプラインの以降の呼び出しは、OIDC トークンではなく Cookie を提示します。
serve 側では audience を設定します。この 1 つの変数が、呼び出し元の形そのものを有効にします。
| 変数 | デフォルト | 意味 |
|---|---|---|
BAJUTSU_OIDC_AUDIENCE |
(未設定) | トークンが持つべき aud です。未設定なら OIDC は無効で、交換の endpoint にそもそも到達できません。 |
BAJUTSU_OIDC_PROVIDER |
github-actions |
どの CI プラットフォームのクレーム名を読むかを選びます。今は GitHub Actions だけです。 |
BAJUTSU_OIDC_ISSUER |
プラットフォーム固有 | セルフホスト環境向けの上書きです。GitHub Enterprise Server は自身のホスト名から発行します。 |
BAJUTSU_OIDC_MAX_TOKEN_AGE |
300 |
トークンの iat からこの秒数を過ぎたら、exp とは無関係に拒否します。 |
BAJUTSU_OIDC_SESSION_TTL |
900 |
発行するマシンセッションの寿命(秒)です。トークン自身の exp と、デプロイ全体の BAJUTSU_SESSION_TTL の両方で頭打ちになるので、3つのうち最も短いものが効きます。 |
audience は意識して設定してください。 audience を選ぶのはワークフローの側です。どんな値でも受け入れる デプロイは、無関係なサービス向けに発行されたトークンまで受け入れてしまいます。デフォルト値を用意していないのは そのためです。未設定のときは「届いた値をそのまま受け入れる」に倒れるのではなく、呼び出し元の形ごと無効になります。
交換にはデータベースと oauth extra が必要です。 各トークンの jti は共有の記録先で使用済みにします。
単一プロセスの中だけでなく、コントロールプレーンのレプリカをまたいで一度きりにするためです。
どのサーバもこのデータベースを持ちます。バケットを指定したデプロイはデータベースの指定が必須で、
バケットを指定せずに1台のマシンで動かすサーバはデフォルトの SQLite を使います。後者では、交換はその1つの
プロセスの中で機能します(前述の「1台のマシンで動かすサーバ backend」を参照してください)。トークンの
署名の検証には joserfc を使い、これは GitHub OAuth と同じ oauth extra に入っています
(uv sync --extra oauth)。この extra が欠けていると、serve は起動時に警告します。パイプラインが
失敗を1回ずつ積み上げて気付く形にはなりません。
続いて、各 org が受け入れるリポジトリを allowedRepositories に列挙します。
orgs:
acme:
members: [alice]
allowedRepositories:
- acme/app # このリポジトリのどのワークフローでも可
- repository: acme/web # …あるいはさらに絞る
environment: production
エントリは "<owner>/<repo>" という名前だけを書くか、その名前に加えて絞り込みの条件を持つオブジェクトを
書きます。条件は environment、ref、workflowRef(GitHub Actions の job_workflow_ref クレーム)の 3 つです。
条件はそのエントリだけに効きます。レビュー必須の環境で動くリポジトリと、条件なしのリポジトリを 1 つの org
に並べて書けます。照合はトークンの個別クレームとの完全一致です。sub の解析や前方一致は使いません。
acme/app は acme/app-evil を受け入れません。
交換の要求はorg を名指しします。そして名指しは選択であって付与ではありません。トークンを受け入れるかどうかを
決めるのは、その org 自身の allowedRepositories です。名指しを必須にしているおかげで、共有のパイプライン用
リポジトリを複数の org から使えます。org を推論する設計なら、この形を禁じるしかありません。
隣に並ぶメンバーの一覧と同じく、データベースを接続していればリポジトリの一覧もデータベース側にあります。管理者は
POST /api/orgs/<slug>/membership から再デプロイなしに編集できます。そのリクエストの本文から
allowedRepositories を省いた場合は、値を変更しません。キーを送ったときだけ([] を含む)置き換えます。この
フィールドに対応していない古いクライアントが、すべてのパイプラインの権限を黙って剥奪してしまわないようにする
ためです。
リポジトリを列挙する前に、次の 3 点を確認してください。
- リポジトリ名は変わりえます。 リポジトリを削除、改名、移管すると、その名前は解放されます。次にその名前を 取得した相手は、あなたのエントリに一致するトークンを発行できます。リポジトリが変わったら、エントリをただちに 更新するか削除してください。
- ワークフローをマージできる人はトークンを発行できます。
allowedRepositories: [acme/app]は、 そのリポジトリのワークフローの書き手に org の権限を与えます。それでは広すぎる場合はenvironmentで絞ります。GitHub の Environment は、ジョブの実行前にレビューを必須にできます。 - フォークからのプルリクエスト。 フォークのプルリクエストは、デフォルトでは
id-token: writeを得ません。 ただしpull_request_targetのワークフローはベースリポジトリのコンテキストで動くため取得できます。フォークの プルリクエストに書き込みトークンを渡すリポジトリ設定も同様です。そうしたリポジトリはenvironmentで絞り、 外部の貢献者が影響を与えられる実行からトークンが発行されないようにしてください。
マシンセッションを統べるのは endpoint の許可リストであって、ロールではありません。 パイプラインは人では ありません。viewer / editor / admin のどのランクも当てはまらないのです。下の表の左側のうち4つは、今日なら admin の endpoint です。マシンにそのランクを与えれば、config の再バインドと operator シークレットの読み出しまで ついてきます。endpoint を名指しすれば、手の届く範囲をパイプラインに必要なものだけに保てます。
| マシンセッションが使えるもの | 拒否されるもの |
|---|---|
GET /api/artifacts/exists(publish 済みのビルドの有無を問う) |
POST /api/config、POST /api/compose(org の有効な config の再バインド) |
POST /api/artifacts/config、.../scenarios、.../binary(3種のアーティファクトの publish) |
GET /api/config/content(config の本文にシークレットが埋まっていることがある) |
POST /api/run、POST /api/run-set(run と run のグループの投入) |
POST /api/apikey、POST /api/claudecodetoken(operator のシークレット) |
GET /api/runs、GET /api/jobs/<id>、GET /api/run-set/<groupId>(投入した run の監視) |
/api/orgs*(誰がサインインして書けるか) |
右の列は serve が保持している一覧ではありません。許可リストは、何も書かれていなければ拒否します。左に
現れないことによって、その endpoint はマシンに閉ざされます。来年 serve に足された経路も、誰かが意図して
開くまで閉じたままです。
org はセッションとともに運ばれます。 パイプラインがどのテナントとして振る舞うかは、交換の時点で確定 します。許可リストのどの呼び出しも、その答えを読むだけで、自分で導き直しません。マシンが投入した run は その org に入り、読める run と job もその org のものだけです。別の org の job は 404 を返します。存在しない job の id と見分けがつきません。「権限がない」と返せば、その id の存在を教えてしまうからです。
監査エントリが名指しするのは、ユーザーではなくリポジトリです。 ユーザーの表にパイプラインの行はなく、
actor_id はその表への外部キーです。列は null のままにして、リポジトリはエントリの detail に入れます。列を
埋めるために合成のユーザーを作れば、/api/orgs が開示する名簿にパイプラインが並んでしまいます。有無を問う
呼び出しも publish と並べて監査します。ビルドがすでにあると判明して終えたパイプラインも、記録を残します。
監査エントリはジョブも名指しします。 1つのリポジトリは多くのジョブを動かすので、リポジトリだけでは
再実行と元の実行を区別できません。交換はトークンにあるジョブの claim をセッションに保存し、そのセッションが
書くすべてのエントリは、detail の actor の下にジョブの記録を持ちます。交換そのものも、同じ記録を持つ
oidc.exchange のエントリを書きます。この1回の書き込みが失敗しても、交換はセッションを返し、失敗を
oidc.audit_failed として ERROR で記録します。トークンはすでに使用済みで、500 を返すとジョブが再試行できなく
なるからです。
{
"repository": "acme/app",
"actor": {
"runId": "123",
"runAttempt": "1",
"checkRunId": "456",
"ref": "refs/heads/main",
"workflowRef": "acme/app/.github/workflows/e2e.yml@refs/heads/main",
"sha": "…",
"triggeredBy": "octocat"
}
}
runId と checkRunId の組で1つのジョブが決まり、runAttempt で再実行と元の実行を区別します。github.com
では、ジョブのページは https://github.com/<repository>/actions/runs/<runId>/job/<checkRunId> です。
GitHub Enterprise Server では、同じパスを自身のホストで提供します。トークンにはホストが含まれないので、serve は
リンクを保存せず、リンクを組み立てる id を個別に保存します。トークンにない claim は、null として書かずに記録から省きます。
マシンセッションを終わらせる。 GitHub が発行したトークンは、何をしても期限まで生き続けます。マシン
セッションは serve 自身が発行したものなので、serve から失効させられます。
# -b: 管理者自身のサインイン済み Cookie です。ほかの /api/orgs の呼び出しと同じです。
curl -X POST "$BAJUTSU_URL/api/orgs/acme/machine-sessions/revoke" -b cookies.txt \
-H 'Content-Type: application/json' -d '{"repository": "acme/app"}'
/api/orgs/… の他と同じく、admin の操作です。パイプラインのセッションではなく、管理者のセッションが
要ります。リポジトリ名は名簿と同じ綴りで構いません。大文字と小文字は両側で畳んで比べます。repository を省くと、その org のマシンセッションがすべて
終わります。名簿そのものに問題があったときに欲しい範囲です。org を退役させたときも、その org のマシン
セッションは終わります。
失効の及ぶ範囲には、2つの区切りがあります。
- 一度に1つの org。 複数の org に列挙されたリポジトリは、他の org のために発行したセッションを保ちます。 ある org の admin が、別の org のパイプラインを終わらせることはできません。
- ジョブ単位ではなくリポジトリ単位。 あるリポジトリが発行したマシンセッションは、すべて
repo:<owner>/<repo>という identity を持ちます。失効させれば、そのリポジトリで同時に走っている パイプラインもまとめて終わります。
allowedRepositories からエントリを消す操作は、新しいセッションの発行を止めるだけです。稼働中のものは
走り続けます。構成が効くのは交換の時点だからです。失効は、その operator の責務のもう半分にあたります。
列挙したリポジトリを改名、移管、削除したら、エントリを消したうえで、すでに発行されたセッションも失効させて
ください。
オペレータのシークレット(Claude API キー)¶
管理者が設定パネルから登録する API キーはオペレータのシークレットであり、ホスト型のコントロール
プレーンでは write-once かつ保存時に暗号化されます
(BE-0136)。
どのエンドポイントも平文を再び返すことはなく(管理者を含めどのロールでも)、返すのはマスクした
プレビューだけです。キーを更新するときは管理者が上書きし、古い値を読み出すことはありません。値は
データベースの secrets テーブルに認証付き暗号(Fernet)で暗号化して保存し、org ごとにスコープするので、
再起動をまたいで残り、コントロールプレーンの複数レプリカで共有されます。
この暗号化にはマスターキーが必要で、BAJUTSU_DATABASE_URL と同じくデータベースの外側で用意します。
# 一度だけ生成し、.env やプラットフォーム自身のシークレットストアに保管する
python3 -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
export BAJUTSU_SECRETS_KEY=…
データベースを使うコントロールプレーンは BAJUTSU_SECRETS_KEY を必須とし、設定されていなければ
起動を拒否します。シークレットをプロセスのメモリだけで保持する形へ黙って後退しないためです。
バケットを指定せずに1台のマシンで動かすサーバは、シークレットをデフォルトの SQLite に保存します。
暗号化には、サーバが .bajutsu/secrets.key に生成するキーを使います。この
キーはデータベースのパスワードと同様に扱ってください。失うと保存済みのシークレットは復元できず、更新した
キーは古いキーで書いた値を復号できないので、更新後は各シークレットを入力し直します。
設定パネルは二つ目の write-once なオペレータのシークレットも同じ形で保持します。Claude Code の OAuth
トークン(CLAUDE_CODE_OAUTH_TOKEN)で、ブラウザの無いホストで claude-code プロバイダを動かすため
claude setup-token の対話的なサインインを完了できないデプロイのためのものです
(BE-0215)。
保存もマスク表示も更新も、上の API キーとまったく同じように扱います。
同じストアは、シナリオが自身で宣言するシークレットも保持します
(BE-0274)。config が
${secrets.X} のために evidence.secrets に並べる名前のことです。これまでは値を供給する手段が、プロセスが
引き継ぐ .env しかありませんでした。今は管理者が設定パネルの Scenario secrets セクションから各値を
設定でき、ホスト型のコントロールプレーンでは、オペレータの認証情報と同じ org ごとの暗号化された secrets
テーブルに(上ですでに必須の BAJUTSU_SECRETS_KEY を再利用し、新しい鍵は不要で)、write-once かつマスクして
保存します。run は、保存したシークレットを、自分を lease したワーカーの上で読みます(BE-0449)。
コントロールプレーンは lease の時点で org のシークレットを復号し、lease の応答で渡すので、平文が
ジョブキューに載ることはありません。ワーカーは値を spawn する run の環境変数に重ねます。API キー、
Claude Code のトークン、各 ${secrets.X} は、そこで解決します。値を受け取るのは共有トークンで取った
lease で、ブラウザのログインは受け取りません。保存した Git config ソース用トークンは、コントロール
プレーン自身の取得処理に届き、job には届きません。
3. Mac ワーカーを動かす¶
各 Mac で(Tier A と同じ Aqua セッション設定。auto-login と caffeinate/pmset)、iOS ワーカーの
ランタイムクロージャ bajutsu[worker-ios](iOS(XCUITest)ワーカーは backend の pip extra を必要としないので、
実行が到達する visual / schema のアサーション依存だけ。BE-0173)をインストールし、tailnet 越しに
コントロールプレーンへ向けます:
export BAJUTSU_SERVER_URL=http://<linux-node>.<tailnet>.ts.net:8765
export BAJUTSU_TOKEN=… # コントロールプレーンと同じ operator トークン
export ANTHROPIC_API_KEY=… # シナリオが AI パス(record / --system-alert-handling)を使う場合のみ
bajutsu worker
worker はオブジェクトストレージの認証情報を一切持ちません(BE-0160)。BAJUTSU_SERVER_STORE /
BAJUTSU_S3_ENDPOINT / AWS_* も、クラウド SDK も不要です。run のベースラインのダウンロード、完了した
runs/<id>/ ツリーのアップロード、record ジョブが生成したシナリオの保存は、いずれもコントロールプレーンが
署名した presigned URL 経由で行います。オブジェクトストレージの認証情報が置かれる場所はコントロールプレーン
だけです。バイト列は worker からストレージへ直接流れます(署名済み URL は MinIO を指します)ので、worker には
オブジェクトストレージへの到達性は必要ですが、その秘密は不要です。
アップロードされたバンドルによる run も同じ経路を通ります。コントロールプレーンは、ドロップ
された zip や、合成した config、scenarios、binary の 3 成果物をバインドします。そのツリーは
コントロールプレーン自身のディスク上にあり、worker から見えません。そのためリースは、バンドルを
構成する保存済みオブジェクトごとに署名済みの読み取り URL を運びます。
worker は作業ディレクトリの .bundles/<org>/<id>/ にそのツリーを組み直します。そしてツリーのルートから
ジョブを実行します。config の相対の subject.path、paths.scenarios、paths.baselines は書かれたとおりに解決
します。ツリーの鍵はバンドルの内容ダイジェストなので、同じバンドルの 2 本目以降の run は何も
ダウンロードしません。このダイジェストが 2 つのビルドを区別します。バイナリのパスが同じで中身の
違う 2 つのバンドルは、作業ディレクトリを共有しません。
この経路にはオブジェクトストアの設定が必要です。オブジェクトストアなしで動いているコントロール
プレーンは、バンドルをどこにも保存していません。そうしたジョブは、インストール時を待たず
bundle unavailable として失敗します。
運用上、知っておきたい点が 2 つあります。1 つは、ツリーを削除する仕組みがないことです。ビルドごと
にバンドルをアップロードするパイプラインでは、ビルドごとに 1 つのツリーが積もります。worker の
ディスクに余裕がなければ、.bundles/ を定期的に刈ってください。もう 1 つは、バンドルの run が
組織の保存済みベースラインをダウンロードしなくなることです。バンドルが自前のものを同梱するため
です。serve でベースラインを承認しつつバンドルもアップロードしている場合は、承認済みの画像を
バンドルに入れてください。
1 台のマシンで動かせるものを宣言するには、bajutsu worker --worker-config <worker.yaml> で
worker 能力ファイルを渡します(BE-0450)。このファイルには、マシンが提供するドライバと、1 つのシナリオが
同時に持てる target の数(maxTargetsPerJob)を書きます。フラグを省くと、worker は同梱の既定を使います。
既定はすべてのドライバを提供し、target の数に上限を設けません。worker は起動時、job をリースする前に
ファイルを検証します。さらに、起動するすべての bajutsu run にファイルの絶対パスを渡します。リースした run は、
それぞれのシナリオをこのファイルに照らして検査します。このマシンで動かせないドライバを必要とするシナリオは、
worker-capability-unsupported: で始まる理由により失敗します。コントロールプレーンはこのファイルを読みません。ファイルの形式と検査の内容は
drivers で説明しています。
ファイルが environment: devicefarm のようにデバイスクラウドを指す worker は、ジョブの予算もこのファイルから
読みます(BE-0448)。最上位の maxJobConcurrency が同時に持てるジョブの数で、枠がすべて埋まっている間、
worker はリースの要求を送りません。値が 1 を超えると、worker は各ジョブを専用のスレッドで、.slots/<n>/ の下の
作業ディレクトリで処理します。このような worker に停止シグナルを送ると、ジョブを取り消さずにリースを期限切れに任せ、
再起動した worker が実行を再開します。予算と投入前の検査は、
AWS Device Farm で実行する で説明しています。
再起動を越えるよう、Tier A と同じく LaunchAgent で包みます。worker はコントロールプレーンの
/api/worker/lease エンドポイントを HTTP でポーリングし(Redis は不要です)、各ジョブをクリーンな
Simulator で実行し、runs/<id>/ ツリー(console.log 含む)をアップロードし、結果を
/api/worker/result へ返します。コントロールプレーンが完了した run を Postgres に記録するので、
worker はデータベースへのアクセスを必要としません。
キューに入った job のコンソールも、ブラウザにはライブで表示されます(BE-0449)。job の実行中、
worker は新しいログ行をおよそ 1 秒ごとに /api/worker/log へ送ります。worker は送る前に資格情報の形を
伏せ字にし、秘密鍵のブロックは END の行まで複数行にわたって伏せ字にします。コントロールプレーンは
リースを持つ worker の送信だけを受け付け、それ以外の worker には 409 を返します。409 を受けた
worker は、ハートビートの 409 と同じく、リースを失ったものとして扱います。1 回の送信は 500 行かつ 4 MiB までです。
worker はそれを超える分を分けて送り、コントロールプレーンはそれより大きい本文を読む前に 413 で拒みます。
8 KiB を超える行はコントロールプレーンが切り詰めます。1 つの job のライブの行が 50,000 行か 16 MiB を超えると、
コントロールプレーンは打ち切りの通知を 1 行だけ流し、残りを捨てます。コントロールプレーンは各行を job の
Server-Sent Events(SSE)のストリームへ流し、worker の結果がそのストリームを閉じます。
送信に失敗した行は、ログに記録して捨てます。送信の失敗で job が失敗したり遅れたりすることはありません。
ライブの行は、実行中の job を見ている閲覧者のためのものです。アップロードされた console.log は、
ログの永続的な写しとして残ります。
- 終わった job を開いた閲覧者には、
console.logがあればそれを表示します。 - ライブで見ていた閲覧者に 1 行も届かなかった場合は、最後に
console.logを表示します。 - ライブの行を一部でも受け取った閲覧者には、
console.logから同じ行を繰り返しません。
コントロールプレーンのレプリカが複数あるなら、ライブのログには BAJUTSU_REDIS_URL が必要です。
1 プロセスならライブの行はメモリに置きますが、ロードバランサーの後ろのレプリカには共有の置き場所が
要ります。次の 2 つを行ってください。
- すべてのレプリカに
BAJUTSU_REDIS_URLを設定します(たとえばredis://cache:6379/0)。 - サーバーの extra に加えて、
redisパッケージをインストールします(pip install redis)。
Redis を置くと、worker の送信とブラウザのストリームは、どのレプリカに着いても同じ Redis で出会います。 Redis を置かないと、ブラウザは別のレプリカへ送られた行を受け取れません。この上限は、 レプリカごとに別々に適用します。
job のキャンセルは、job がキューで待っていても、すでに worker で動いていても同じように働きます。 コントロールプレーンは jobs テーブルから job を探すので、再起動の前にキューへ入った job もキャンセルできます。
- キューで待つ job は
cancelledになり、どの worker もリースしません。 - リース済みの job はリースを保ったまま、コントロールプレーンが印を付けます。worker の次のハートビートには
{"ok": true, "cancel": true}が返ります。worker は自分の run を止めます。runの job は安全な境界で止まり、 レポートを書き終えます。それ以外の種類の job はプロセスグループごと終了します。worker は run が止まるまで リースを更新し続け、そのあとキャンセルの結果を送ります。job をcancelledにするのは、リースを持つ worker が 送ったキャンセルの結果だけです。 - 終わった job には何もせず、キャンセルは job の最終状態を返します。
キャンセルされた job を止めている途中で worker がオフラインになった場合、その job は別の worker に渡りません。
リースが切れると、job は cancelled で終わります。
リース済みの job のキャンセルには、この版以降の worker が要ります。worker はコントロールプレーンと一緒に 更新してください。
4. 公開する¶
Tier A と同様に前段を置きます。tailscale serve --bg 8765(tailnet 内のみ、推奨)、または実ホスト名なら Caddy
(docker compose --profile caddy up -d、BAJUTSU_PUBLIC_HOST を設定)。ワーカーは tailnet 越しに
コントロールプレーン(:8765)と MinIO(:9000)へ到達するので、ノードはプライベートな tailnet 上に置いて
ください。
5. Linux web ワーカーを足す(コンテナ、任意)¶
web(Playwright)backend は Linux 上でヘッドレスに動くので、そのワーカーはベアメタルの Mac ではなく
コンテナになります(BE-0173)。compose 一式には任意の worker-web サービスが含まれ、既定では無効
(profile の裏)なので、iOS だけの構成は変わりません。Linux ノード上でも、コントロールプレーンへ到達できる
別の Docker ホスト上でも、次のように有効化します:
cd deploy/self-host
# BAJUTSU_SERVE_TOKEN を .env に設定しておくこと(web ワーカーはこれを operator トークンとして再利用します)
docker compose --profile web-worker up -d --build
このサービスは worker-web.Dockerfile をビルドします。これは
マルチステージのイメージで、ワーカーのランタイムクロージャ(bajutsu[worker-web] = web backend +
visual + schema)と、ブラウザに必要なヘッドレス Chromium だけを入れます。コントロールプレーンのスタック
(server / db / oauth)、cloud SDK、AI SDK は入れません。ワーカーはコントロールプレーンとオブジェクト
ストレージへ HTTP で話し、BE-0160 のとおりオブジェクトストレージの認証情報を一切持たないためです
(必要なのは BAJUTSU_SERVER_URL と BAJUTSU_TOKEN だけです)。イメージを小さく保つため、フルの headed
ビルドではなく Chromium のヘッドレスシェルを入れます(playwright install --with-deps --only-shell
chromium)。シェルは Playwright がヘッドレス実行で既定として使うものなので実行の挙動は変わらず、ブラウザの
容量を数十 MB 削り、システムライブラリの依存も軽くなります。Linux のワーカーは常にヘッドレスなので、シェルが
落とす headed 専用の機能は関係しません。イメージが入れるのは Chromium のシェルだけなので、Chromium の
web run(既定のエンジン)を担います。Firefox や WebKit に固定したシナリオ(BE-0076)には、それらのブラウザを
持つワーカーが必要で、このスリムなイメージでは動きません。
compose の外(たとえば別の Linux マシン)で web ワーカーを動かすときは、イメージを直接ビルドして実行します:
docker build -f deploy/self-host/worker-web.Dockerfile -t bajutsu-worker-web .
docker run -d --rm \
-e BAJUTSU_SERVER_URL=http://<linux-node>.<tailnet>.ts.net:8765 \
-e BAJUTSU_TOKEN=… \
bajutsu-worker-web
web ワーカーは web ジョブだけを、Mac の iOS ワーカーは iOS ジョブだけをリースします。プールは capability でルーティングするので、backend が混在するフリートでも安全です(下記の能力に基づくキューの 振り分けを参照)。
能力に基づくキューの振り分け(BE-0166)¶
現実の Mac プールが均一であることはまれです。マシンごとにインストールされている iOS ランタイムは異なり、 iPad 向けに整えたものもあれば iPhone 向けのものもあり、web ワーカーはそもそも別の backend を動かします。 区別のない単一キューでは、どのワーカーもどのジョブもリースできてしまうため、iOS のジョブが Linux の web ワーカーに渡って失敗しかねません。それは本物の欠陥ではなく、誤ったマシンへ振り分けられたことによる 失敗です。能力に基づくルーティングはこれを防ぎます。ジョブは、それを実際に実行できるワーカーからのみ リースされます。
各ワーカーは仕事をポーリングするときに capability トークンの集合を広告し、ジョブは自分が必要とする
集合を持ちます。コントロールプレーンは、ワーカーがジョブの必要とするトークンをすべて広告している場合に限り、
そのジョブをリースします。ルーティングが決めるのはどの空きワーカーがジョブを取り上げるかだけで、決定的な
run の判定は変わりません。
- ワーカーの広告集合は、その
--platform(backend 軸。Mac の iOS ワーカーはplatform:ios、Playwright の コンテナはplatform:web)と、マシン自身から得るトークンでできています。どのワーカーも、自分が動く OS を表すhost:<os>を広告します。Mac ならhost:darwinです(BE-0450)。 iOS ワーカーは、インストール済みの Simulator 在庫も広告します。在庫からは、ランタイムごとのiosNNトークンと、iphoneとipadのデバイス種別が得られます。iOS ワーカーは、接続されている実機の ファミリーをdevicectlで読み、device:iphoneとdevice:ipadも広告します。実機は抜き差しされるので、 ワーカーはリースを試みる際に、15 秒に 1 回を上限として実機を読み直し、読めた内容が変わるたびにログに残します(BE-0468)。 ローカルで起動したサーバのマシンで 動くワーカーは、サーバの識別子を表すmachine:<id>も広告します。このトークンが、そのマシン上のファイルを 指定するジョブを振り分けます(1台のマシンで動かすサーバ backend)。web ワーカーのコンテナは--platform webを組み込んであるので、webを広告し、フラグは要りません。 - ワーカーは、fan-out のジョブが必要とするトークンも広告します(BE-0484)。
どのワーカーも
job:run-intentを広告します。fan-out のジョブを自分の形の実行へ変換できる、という印です。 iOS のワーカーは、在庫に iPhone か iPad の Simulator があればkind:simulatorを広告します。devicectlで iPhone か iPad の実機を読めている間は、kind:deviceも広告します。worker 能力ファイルでrealDevices: falseを設定すると、このトークンは広告しません。Device Farm のワーカーはplatform:android、platform:ios、kind:deviceを広告します。サービスが予約するプラットフォームとデバイスの種類です。 - ローカルのワーカーは、扱えないプラットフォームを拒否します。 ワーカーは起動時に、各
--platformを worker 能力ファイルとホストに照らして検査します。ファイルが そのプラットフォームのドライバを含まないとき、またはホストがそのドライバを動かせないとき、ワーカーは ドライバを名指しするメッセージを出して終了します。そのため、既定の--platform iosで起動した Linux の マシンは、xcuitest runs only on macOS; this worker runs on linuxを示して止まります。決して始められない ジョブを待ち続けることはありません。検査はプラットフォームのドライバを判定するので、fakeの backend で 動く iOS のターゲットも Mac のワーカーを待ちます。 - ジョブの必要集合は、ターゲットのプラットフォーム軸と、そのドライバが動くホストだけです。ターゲットの
platformがドライバを決めます。そのドライバが 1 つの OS でしか動かない場合は、host:<os>も加わります。xcuitestドライバで動く iOS のターゲットは、host:darwinを必要とします。web や Android のターゲットは ホストを必要としません。一致するホストのワーカーがジョブをリースし、デバイスの操作を始める前に、ワーカー 自身の検査が各シナリオを判定します。ターゲットがトークンを追加で宣言する手段はもうありません。requires:とdefaults.requiresは取り除きました(BE-0452)。 ルーティングは、ターゲットのrunsOn.ios.osからランタイムのトークン(ios18)を導きません。そのため、 iOS のランタイムでジョブを振り分けることはできません。 - ジョブの必要集合には、ターゲットの
runsOn.ios.familyも入ります。 serve のジョブは、ターゲットのrunsOn.ios.kindに並ぶ種類をすべて実行します。そのため、種類ごとに合うデバイスが必要です。Simulator の 実行は在庫のiphoneとipadのトークンを、実機の実行はdevice:のトークンを使います。ファミリーが 1 つなら、そのトークンを必要とします。kind: deviceとfamily: ipadの組み合わせならdevice:ipadです。 ファミリーの優先順位リストは、どれか 1 つのファミリーで足ります。部分集合の判定ではこの条件を表せません。 そこでジョブは、any-of のグループanyof:device:ipad|device:iphoneを保存します。ワーカーはその要素の どれか 1 つを広告すれば条件を満たします。リースしたワーカーは、自分のプールでリストを解決し直します。 ルーティングがワーカーを選び、リストがデバイスを選びます。ファミリーを指定しないターゲットは、トークンを 加えません。ターゲットをfakeドライバで動かすリクエストも加えません。このドライバはデバイスを操作しない からです(BE-0468)。 - fan-out のジョブは、実行場所を要求しません。
POST /api/run-setのジョブは、ターゲットのplatform:<p>、job:run-intent、シナリオのルートのcap:とsetting:のトークン(後述)を必要とします。 iOS のジョブは、上のファミリーのトークンと、実行する種類ごとに 1 つのkind:<kind>トークンも必要とします。host:、environment:、machine:のトークンは必要としません。そのプラットフォームを扱い、これらの トークンを広告するワーカーなら、ローカルでも Device Farm でもリースできます。Device Farm のワーカーは ファミリーのトークンを広告しないので、runsOn.ios.familyを指定したターゲットは Device Farm へ振り分けられません。environment:トークンを広告するワーカーは、通常はその トークンを必要とするジョブだけをリースします。fan-out のジョブは環境を指定しないので、この規則の例外です (BE-0484)。 - ペアリング済みの実機は、接続中として読まれます。
devicectlは、ペアリング済みの実機を、差さって いるかどうかにかかわらず一覧に出します。トンネルの状態は、実行がトンネルを開くまでdisconnectedと 読めます。このフィールドでは、使われていない実機と抜かれた実機を区別できません。そのため、ワーカーは抜かれた 実機のファミリーも広告し続けます。そこへ振り分けられたジョブは、キューに残るのではなく、実行がデバイスを 操作する時点で失敗します。 - run のジョブは、ルート上でステップと設定が必要とするものも要求します(BE-0467)。
各ターゲットは環境ルートに解決されます。ルートは
ios-simulator、ios-device、ios-live(WebDriver の エンドポイント)、android、webのいずれかです。3 つの iOS ルートは対応する設定が異なるので、 プラットフォームだけでは区別できません。ジョブは次の 2 種類のトークンを必要とします。 cap:<route>:<capability>:そのターゲットに割り当てたステップが必要とする capability ごとに 1 つsetting:<route>:<key>:ジョブが有効にする設定のうち、ターゲットがrunsOn.ignoredSettingsで無視を 宣言していないものごとに 1 つ
Appium のグリッドで動かす実行では、iOS のターゲットを ios-live に置きます。
- ワーカーは、ドライバが動かすルートごとにトークンの集合を広告します。 xcuitest は Simulator の
ルートを、adb は android を、playwright は web を動かします。対象のドライバは、--platform に
かかわらず、worker 能力ファイルが提供し、ホストが起動できるもの
すべてです。シナリオのほかのターゲットも同じマシンで動くからです。xcuitest のワーカーは、ファイルで
realDevices: false を設定しない限り、ios-device のルートも加えます。appium のワーカーは ios-live
を広告します。ルートの集合はファイルの記述どおりなので、ファイルにはマシンにインストール済みのドライバ
だけを並べてください。こうしたワーカーはどれも cap:routing も広告します。ルートのトークンを計算する
ワーカーであることを示す印で、このトークンを必要とするジョブはありません。集合どうしの共通部分は取りません。そのため、Simulator と接続した
iPhone の両方を動かす Mac は、実機のルートで erase を使うジョブを受け取らず、Simulator のジョブは
すべて受け取ります。
- 不一致は投入時に失敗し、動かすワーカーのいないルートは待ちます。 コントロールプレーンがジョブを
拒否するのは、次の 3 つがすべて成り立つ場合です。
- 稼働中のワーカーが、すでにジョブのルートを動かしています。
- ジョブが必要とするトークンをすべて広告する、稼働中のワーカーがいません。
- ジョブを扱える稼働中のワーカーが 1 台もいません。この項目より前のワーカーはほかのトークンで照合されるので、
そうしたワーカーがジョブを扱える間は、混在した構成でもジョブを受け付けます。
このとき POST /api/run は 400 を返します。エラーには、
不足しているトークンと、それを必要とするステップや設定が並びます。POST /api/run-set も、各ジョブを
同じ方法で検査します。拒否されるジョブが 1 つでもあればリクエスト全体を 400 で拒否し、エラーには
そのシナリオと不足しているトークンが並びます。稼働中のワーカーがそのルートを
動かしていない間は、ジョブはキューに残り、bajutsu_unroutable_jobs に数えられます。コールドスタートや
ワーカーの再起動の最中がこれにあたります。
- ワーカーは、ジョブを受け取るときにもう一度チェックします。 lease の応答は、サーバーがジョブの振り分けに
使ったトークンをワーカーに渡します。ワーカーは、何かを取得したりデバイスを lease したりする前に、
worker.yaml とホストが起動できるドライバから自分のルートのトークンを計算し直します。ワーカーが
もう提供していないトークンを必要とするジョブは、そのトークン名を示して失敗します。
- Appium のグリッドで動かす実行は、環境で振り分けます。 通常の実行リクエスト(POST /api/run)は、
任意の environment を受け付けます。指定できる値は appium だけで、ほかの値には 400 を返します。
このジョブが必要とするのは environment:appium だけです。グリッドがデバイスとそのホストを持つからです。
worker.yaml で environment: appium を設定し、グリッドの endpoint を指定したワーカーは、このトークン
と job:run-intent を広告し、--platform を取りません。platform: のトークンは広告しないので、
fan-out のジョブは受け取りません。そのワーカーは、自分の --worker-config を付けたローカルの
bajutsu run を実行します(iOS を実機で動かす)。
fan-out(POST /api/run-set)は environment を取らず、各ジョブをターゲットのプラットフォームで
振り分けます(AWS Device Farm で実行する)。
- ワーカーの手書きの入力は非推奨です。 ワーカーの --capabilities と $BAJUTSU_WORKER_CAPABILITIES は
トークンをそのまま加えます。どちらも今回のリリースでは引き続き効き、1 回だけ通知を記録します。次のリリース
で削除します。Simulator 在庫と worker 能力ファイルが、上書きの用途をすでに担っているからです。上書きは、
マシンにないランタイムを広告できてしまう点でも問題です。どちらも、予約済みの接頭辞 environment:、
host:、machine:、device:、cap:、setting:、job:、platform:、kind: を含められません。ワーカーがいずれも自分で埋めるからです。ワーカーは起動時に、そのトークンを
拒否します。
- 振り分け不能のジョブ、すなわち必要とする capability を稼働中のどのワーカーも広告していないジョブは、
非互換のワーカーにリースされたり捨てられたりせず、キューに残ります。そして bajutsu_unroutable_jobs
メトリクス(下記)で顕在化するので、運用者は不足している capability を持つワーカーを足せばよいと分かります。
同一構成のプールは影響を受けません。どのワーカーも同じ軸を広告するので、どのジョブもこれまでどおり
ルーティングされます。
[!NOTE] ワーカーはコントロールプレーンと同時か、それより先に更新してください。 投入されるジョブはすべて 少なくとも
platform:*を必要とするようになり、能力ルーティング以前のビルドのワーカーは広告集合を 送りません。そのため何も広告できず、実ジョブを一つもリースできません。BE-0450 でも同じです。xcuitestで動く iOS のジョブはhost:darwinを必要とするようになり、その変更より前のビルドの ワーカーはこのトークンを広告しません。誤配送はしない安全側の挙動ですが、 更新済みのコントロールプレーンに古いワーカーを残すと、そのワーカーは黙ってリースを止め、bajutsu_unroutable_jobsの増加としてのみ現れます。ワーカーのバイナリを先に(または同時に)更新し、あとにしないでください。 BE-0449 でも同じ順序が必要です。コントロールプレーンはrunをpython -m bajutsu.run.internalとしてキューに積むようになり、 その変更より前のビルドのワーカーはこのコマンドを自分のインタプリタに置き換えられないため、リースしたrunがすべて失敗します。BE-0467 は逆の向きです。それより前のビルドのワーカーは
cap:やsetting:のトークンを広告しません。 コントロールプレーンはそのワーカーをほかのトークンだけで照合するので、更新によってキューが止まることは ありません。lease は、そうしたジョブの provenance にworkerRouting: uncheckedを記録し、この記録は run のmanifest.jsonに届きます。ローカルの serve のように閲覧時に描画するレポートは、その記録を notices に 載せます。run の時点で焼き込んだレポートには載りません。古いワーカーは、記録が届く前にレポートを焼き込む からです。この記録をなくすには、ワーカーを更新してください。BE-0484 では、再びワーカーを先に更新する必要があります。fan-out のジョブは
job:run-intentを必要とし、 その変更より前のビルドのワーカーはこのトークンを広告しません。それより前のビルドの Device Farm のワーカーは、platform:のトークンも広告しません。どちらの場合も、fan-out のジョブはキューに残り、bajutsu_unroutable_jobsに数えられます。--capabilities platform:…やkind:…を付けたワーカーは、以前は起動できましたが、今は 起動を拒否します。この 2 つの接頭辞はワーカー自身が埋めるので、トークンを取り除いてください。
オブジェクトストレージへの証跡アップロード(任意、BE-0110)¶
上記のワーカーのアップロードは、コントロールプレーンがレポートを配信するアーティファクトストアに各 run ツリーを書き込むものです。これとは別に、各 run の証跡をライフサイクル管理されたバケットへアーカイブでき ます。main ブランチの証跡は監査のために保持し、feature ブランチの証跡は数日で失効させる、といった運用です。 コントロールプレーンに URI を一つ設定するだけです。
# コントロールプレーン側(docker compose の環境変数、または serve プロセス)
export BAJUTSU_EVIDENCE_STORE=s3://audit-bucket/evidence/ # gs://… も可。--evidence-store でも指定できます
証跡ストアは、アーティファクトストアとは独立した2つ目の保存先です。別のアカウントにも、より厳しい権限で
ライフサイクル管理したバケットにもできます。どちらのバケットも worker にとっては認証情報が不要です。
コントロールプレーンが各バケットの認証情報を保持してファイルごとに presigned PUT URL を発行し、worker は
平文 HTTP でアップロードします(証跡は BE-0110、アーティファクトストアは BE-0160)。s3 または gcs extra は
コントロールプレーン側に入れます(uv sync --extra s3 または --extra gcs)。worker にはどちらも不要です。
CI ジョブは run を開始するときに evidence_prefix を渡して、run ごとのパス、つまりライフサイクルポリシーを
選びます。
curl -X POST "$SERVER/api/run" -H "Authorization: Bearer $TOKEN" \
-d '{"scenario": "smoke.yaml", "target": "demo", "evidence_prefix": "main/abc1234/"}'
コントロールプレーンは evidence_prefix を安全な相対セグメントとして検証し、自分のバケットとベースプレフィッ
クスを前置します。最終的なキーは evidence/main/abc1234/<runId>/… となり、run ID が必ずパスに含まれるので run
同士が衝突せず、呼び出し元がベースプレフィックスの外へ出ることもできません。アップロードは判定の後に走るの
で、失敗してもログに記録するだけで pass/fail は変わりません。BAJUTSU_EVIDENCE_STORE が未設定なら、ワーカーは
問い合わせるだけで何もアップロードしません。
複数 org¶
1 つの backend で複数チームをホストするには、マウントした config に org を宣言します。各 org に所属メンバー (GitHub login、GitHub org、GitHub Team)と、その org が持つ targets を指定します(configurationを参照)。
orgs:
acme:
members: [alice, bob]
githubOrgs: [acme-gh] # この GitHub org の全員(ログインは read:org scope を要求)
targets: [demo, checkout]
globex:
members: [carol]
githubTeams: [shared-gh/globex-qa] # 共有 organization のうち 1 つの Team だけ
targets: [other]
各ユーザは自分の org にスコープされます。自 org の targets だけが見え、別 org の run/scenario/成果物は not-found
または 403 になり、各 org の artifacts/scenarios/baselines はその org 専用のオブジェクトストレージ prefix の下に
置かれます。orgs: ブロックが無ければ backend はシングルテナント(1 つの default org)のままで、共有トークンと
GitHub 許可リストがアクセス境界です。フルマネージドの公開クラウド提供(ホスト型の Mac ワーカープール+IaC)は
BE-0015 で今後の作業です。
データベースを繋いだら、org を Web UI から管理する。 BAJUTSU_DATABASE_URL を設定した backend は、各 org のメンバーシップをそのデータベースに持ちます。config ファイルが持つのをやめる対象は members、githubOrgs、githubTeams、editorTeams の4つです。これにより、テナントを1つ増やす作業にも、チームの書き込み権限を別の GitHub Team へ移す作業にも、config の編集と再デプロイが要らなくなります(BE-0375)。admin には Web UI に Orgs ページが現れ、その裏では admin 専用の4つのエンドポイントが動きます。
| リクエスト | 動作 |
|---|---|
GET /api/orgs |
生存している org を、そのメンバーシップとともに一覧します。 |
POST /api/orgs |
{"slug": "...", "name": "..."} から org を作ります。メンバーは空なので、メンバーシップを設定するまで誰もサインインできません。 |
POST /api/orgs/<slug>/membership |
{"members": [...], "githubOrgs": [...], "githubTeams": [...], "editorTeams": [...]} を1つの単位として置き換えます。allowedRepositories だけは例外です。キーを省くと、リポジトリの一覧はそのまま残ります。キーを明示したときだけ([] も含めて)置き換えます。旧来の単数形 editorTeam を載せた body は 400 で拒否します。その body は editorTeams を挙げておらず、従えばその org の書き込み権限を消してしまうからです。 |
DELETE /api/orgs/<slug> |
org を廃止し、その org としてセッションを持っている全員をサインアウトさせます。default は常に拒否します。 |
4つとも監査ログに記録します。default は3つの変更操作すべてで予約されています。作成も、メンバーシップの置き換えも、廃止も、この slug に対しては拒否します。未一致のサインインが落ちる先の org であり、admin Team の迂回で入った admin も全員ここに入るからです。ここに実在のテナントを置けば、admin が復旧に使う名前空間を奪います。名簿を与える操作も同じことです。login をある org に置くのはメンバーシップだからです。ただし一覧には、フォールバックである旨を添えて表示します。迂回で入った admin 自身がここにいるので、隠すとその admin の run や secret や証跡がどこに落ちるかも見えなくなります。org の削除は soft delete です。サインインを受け付けなくなり一覧からも消え、同時に、そのメンバーがすでに持っているセッションもすべて失効します。廃止前に発行された cookie で、そのテナントとして振る舞い続ける人が残らないようにするためです。その org の run と監査記録は引き続き参照できます。admin の操作が取り上げるのはテナントの行動能力であって、そのテナントがすでに行ったことの記録ではないからです。slug も予約されたままなので、同じ名前で作り直すことはできません。
どの target を org が持つかは、引き続き上の orgs: ブロックが決めます。したがって、この方法で作った org は、そこにエントリが書かれるまで1つも target を持ちません。同じ名前の target を2つの org がそれぞれ要求してもよく、どちらの org もその target に対して認可されます。
複数の org に所属するメンバー¶
上記のメンバーシップが複数の org への所属を認める GitHub のログインは、その時点でひとつの org として振る舞い、どの org かを自分で選びます。サインインは、そのログインが振る舞える org をすべて記録します。それぞれで持つロールも併せて記録します。org の editorTeams が昇格させるのはその org の中だけなので、ロールはテナントに追随します。Web UI のヘッダーは、読み取り専用の org バッジの代わりに、それらをドロップダウンとして提示します。裏側にあるエンドポイントは1つで、上記の4つと違って admin 専用ではありません。すでに呼び出し元を受け入れている org のあいだを移動するだけであり、前回のサインインが確立した以上のものは何も与えないからです。
| リクエスト | 内容 |
|---|---|
POST /api/org |
{"org": "<slug>"} を呼び出し元のアクティブな org にします。ロールもその org で持つものになります。呼び出し元がメンバーでない org は 403 で拒否します。存在しない slug と同じ答えなので、この拒否は、呼び出し元が振る舞えないテナントの存在を漏らしません。 |
監査ログは、この移動を切替先の org に対して記録します。移動元はエントリの detail に入ります。選択は以後のサインインでも保たれます。org を選んだログインは、もっともよく一致する org へ解決し直されるのではなく、選んだ org に再び着地します。これが選択と同点処理の違いです。保たれなくなるのは、その org がそのログインを受け入れなくなったときだけです。そのときの次回のサインインは、何も選んでいないログインを移すのとまったく同じように移します。BAJUTSU_OAUTH_ADMIN_TEAMS の Team によって受け入れられた admin は、生存しているすべての org として振る舞えます。サインイン後に作られた org も含みます。どの org のメンバーシップもその admin を挙げていないため、サインイン時に保存した集合は空になり、あとから保存した集合は次の POST /api/orgs で古くなるからです。
POST /api/orgs/<slug>/membership で取り消したメンバーシップは、そのログインが次にサインインするまで、その org への切替を受け入れ続けます。メンバーシップ変更がもともと持つ次回サインインまでの待ち時間であり、すでにその org として振る舞っている状態を続けさせるのと同じ待ち時間です。ただちに効かせたいときは、そのユーザーのセッションを失効させてください。org の廃止(DELETE /api/orgs/<slug>)は、それを代わりに行います。
切替が向きを変えるのは、呼び出し元がこれから行うことだけです。run は投入時の org を、リモートのワーカーに渡ったあとまで保持します。そのため、実行中に呼び出し元が切り替えても、証跡もデータベースの行も、実行を開始した org に入ります。
データベースを繋いだデプロイの移行。 Alembic のマイグレーションは通常どおり実行します。追加するのは列だけで、データは書き込みません。次回の起動時に、serve 自身が、この serve を起動したときの config の orgs: のメンバーシップをデータベースへ写します。そのため、既存のデプロイは移行前と同じ顔ぶれを受け入れ続けます。
この書き写しが起きるのは、orgs テーブルが空のときの一度だけです。org が1つでも入っている状態で起動すれば、廃止済みのものが1つあるだけでも、何も書き写しません。起動後に Web UI や POST /api/config で bind した config は、そもそも一切書き写しません。これらの bind が受け取る config は、その内容がこちらの管理下にないからです。同じファイルの subject.build を --allow-remote-build まで統制の外に置く信頼境界(リモート config のコマンド実行を参照)と同じ線で、誰がサインインできるかを決めさせません。加えて、書き写した行は bind より長く残るため、bind を切り替えても許可を取り消せなくなります。移行後に org を増やすときは、Orgs ページで宣言してください。
以後、この4つのフィールドをファイルが決めることはなくなり、まだ宣言しているエントリがあれば serve が event=org.membership.ignored(check=orgs_membership_ignored)として org 名を挙げて警告します。該当のエントリは、都合のよいときに targets: だけへ削ぎ落としてください。このフィールドは引き続き読みますし、書き写しの起きる起動より前に削ぎ落としても後に削ぎ落としても同じです。targets: だけを宣言したエントリは書き写しの対象から外れるので、誰も受け入れない状態で org が固定されることはありません。
移行に伴って意図的に変わる点が2つあります。1つは、config が読めない状態でも、bind されていない状態でも、誰も拒否しなくなることです。サインインを決めるのがデータベースだけになるからです。もう1つは、serve がデータベースを読めないときの答え方です。ユーザの GitHub メンバーシップのせいにする 403 ではなく、ストアを名指しする HTTP 503 でサインインに答えます。この 503 は oauth.denied ではなく、専用の event=oauth.store_unavailable として WARNING で記録します。誰も拒否されていませんし、拒否を対象にしたアラートが指すべきなのは GitHub 側の構成であって、ストアの障害ではないからです。
3つ目の変化は、2つの org が同じ相手を挙げている場合にだけ現れます。githubOrgs に同じ GitHub organization を挙げているか、githubTeams や editorTeams に同じ Team を挙げている場合です。明示の members に載っていない login は、その条件を満たす最初の org に解決されますが、この「最初」が orgs: ブロックでは宣言順、データベースでは slug 順です。どちらも安定しているので、同じ login は毎回同じ org に入りますが、この重なりを持つデプロイでは、移行のときに一度だけ解決先が動くことがあります。複数の org に属する login が、そのどれとして振る舞うかを選ぶ手段は、現時点ではありません。
最初の org をどう作るか。 新品のデータベースには org が1つもないので、サインインのゲートには誰も一致しません。構成済みの BAJUTSU_OAUTH_ADMIN_TEAMS の Team のメンバーは、org がいくつあるかにかかわらずこのゲートを通過します(上の GitHub OAuth を足すを参照)。そのメンバーが admin としてサインインし、Orgs ページから最初の1つを作ります。
Mac プールを org 間で公平に保つ。 BAJUTSU_MAX_CONCURRENT_PER_ORG を設定すると、1 つの org が同時に
持てる run 数の上限を決められます。各ユーザがそれぞれの BAJUTSU_MAX_CONCURRENT_PER_USER 以内にとどまって
いても、忙しい org が希少なデバイスを独占することを防げます。どちらも既定は無制限(0)で、いずれもグローバルな
--max-concurrent-runs の下に効きます。上限を超えたリクエストはキューに入れず拒否します(HTTP 429)。
ただし fan-out(run-set)は例外です。すべてのシナリオをキューに積み、ワーカーがジョブを
リースする時点で上限を適用するので、枠が空くたびに順に実行します(BE-0484)。(org を
またぐ公平なスケジューリング、つまり拒否した分を org 別キューで保留してラウンドロビンで投入する仕組みは、まだ
今後の作業です。今日は通常の run を上限で拒否します。)
run の削除と、ゴミ箱の保持期間。 run(とそのレポート)は API から削除できます(BE-0239)。DELETE /api/runs/{id}
はソフトデリートで、run は履歴一覧から消えますがゴミ箱へ移るだけなので、POST /api/runs/{id}/restore で復元できます。
DELETE /api/runs/{id}?purge=true はゴミ箱を経ずに実体を即座に削除します。ソフトデリートと復元は editor、即時の完全削除は
admin の操作です。POST /api/runs/bulk-delete(本文 {"ids": [...], "purge": <bool>})は複数をまとめて処理します。
ソフトデリートした run は、ゴミ箱に入ってから保持期間を過ぎると完全に削除されます。判定は次に履歴を読むときに都度おこない、
バックグラウンドのジョブはありません。
| 変数 | 既定 | 意味 |
|---|---|---|
BAJUTSU_RUN_RETENTION_DAYS |
30 |
ソフトデリートした run を完全削除するまでゴミ箱に置く日数。0 以下にすると自動削除を無効にし、?purge=true で明示的に消すまでゴミ箱を保持します。 |
(行ごとの削除ボタンやゴミ箱ビューといった Web UI 側の導線はこれからですが、上記の API はすでに使えます。)
運用ログ¶
ホスト型の serve は、自身の診断トレースを出力します。構造化された JSON を標準出力に書き出し、秘密情報は マスクします。これにより、1 つのユーザ操作をコントロールプレーンとワーカーをまたいで追跡できます。これは、すでに ある 3 つのログ面とは別物です。テスト対象の証跡(evidence)、ライブの実行出力ストリーム、そして 誰が何をしたかの監査ログのいずれでもありません。出力された行を集約する作業(標準出力をログ基盤へ送る作業)は デプロイ側の責務で、ツールは行を生成するだけです。
形式と詳細度は、起動時に一度だけ読まれる 2 つの環境変数で選びます。
| 変数 | 既定値 | 意味 |
|---|---|---|
BAJUTSU_LOG_FORMAT |
json |
構造化された serve チャネルなら json、人が読みやすい 1 行なら text。 |
BAJUTSU_LOG_LEVEL |
INFO |
標準のレベル名(DEBUG/INFO/WARNING/ERROR/CRITICAL)。 |
決定的な run/CI 経路はこのチャネルを設定しないので、影響を受けません。静かなまま、標準ライブラリだけで動きます。
相関付け。 各 JSON 行は、1 つの操作を端から端まで追うための id を持ちます。リクエスト境界で発番される
request_id と、ワーカーで束縛される job_id/org/actor/run_id です。コントロールプレーンのリクエストと、それが
起動したワーカーの run が、プロセスをまたいで同じ id の値を共有します。行は次のような形です。
{"ts": "2026-06-28T12:00:00+00:00", "level": "INFO", "logger": "bajutsu.serve.operations",
"event": "run.dispatched", "msg": "job dispatched", "request_id": "…", "org": "acme",
"job_id": "…"}
event フィールドは安定したイベント名(run.dispatched、quota.rejected、worker.job.started、
worker.job.finished、artifact.upload.failed、server.startup_warning、oauth.login、
oauth.denied など)を示すので、
これを対象に grep やアラートを設定できます。server.startup_warning は、自由文の msg とは別に、どの起動時
条件が発火したかを示す check フィールド(例:admin_teams_empty)も携えます。アラートは言い回しが変わり
うるメッセージ本文ではなく、この check をキーにしてください。oauth.login はすべての成功したサインイン
を記録し、bypass フィールドを携えます。これは orgs: ではなく構成済みの admin Team がこの login を
許可した場合にだけ true になります。迂回による許可が残す記録はこのフィールドしかありません。迂回の
ほとんどは INFO です。運用専用の organization に置いた admin Team は、設計上すべてのサインインで
迂回するためです。oauth.login が WARNING になるのは、org モデル自体が使えない状態で迂回による
許可が起きたときだけです。どの状態がそれにあたるかは、org モデルの出所によって変わります。orgs:
ブロックを出所とするデプロイでは、config が bind されていない状態、読み込みに失敗した状態、orgs:
ブロックを宣言していない状態の3つです。データベースがメンバーシップを保持するデプロイでは、orgs
テーブルのどの行もまだメンバーシップを宣言していない状態です。テーブルが空の場合だけでなく、どの行の
名簿も空である場合を含みます。迂回によるサインイン自体が作った受動的な行や、管理者が Orgs ページで
作成したまま名簿を埋めていない org が、これにあたります。そのためアラートは WARNING を
キーにし、誰がいつサインインしたかを調べるときは bypass を grep してください。
マスクは構造的です。 1 つのフィルタがルートロガーに置かれるので、書き出される前にすべての行が
スキャンされます。サードパーティのライブラリが出した行も対象です。正しさは、各呼び出し箇所がマスクを
忘れないことに依存しません。既知の秘密の値(オペレータトークン、OAuth クライアントシークレット、
ANTHROPIC_API_KEY、および run の実行中はその run が解決した ${secrets.X})と、機微なフィールド名
(authorization、token、secret、password、cookie、api_key)をマスクし、[REDACTED] に置き換えます。
メトリクスと可観測性(BE-0169)¶
構造化ログ(前節)が記録するのはイベントです。一方のメトリクスは、プールが飽和していないか、いまどの
org が消費しているか、run がふだんより長引いていないか、ワーカーが生きているかを示す時系列です。
コントロールプレーンはこれらを Prometheus のテキスト形式で GET /metrics に公開します。値はすでに
追跡している状態(jobs テーブルとリースおよびハートビートの記録)から導くので、新しい記帳は増えません。
| メトリクス | 種別 | 意味 |
|---|---|---|
bajutsu_in_flight_jobs{org} |
gauge | コントロールプレーン自身が実行中の job 数(ローカル serve)。org ごと。 |
bajutsu_queue_depth{org} |
gauge | キューで待機している job 数(サーバ backend)。org ごと。 |
bajutsu_leased_jobs{org} |
gauge | ワーカーにリースされ実行中の job 数(サーバ backend)。org ごと。 |
bajutsu_worker_heartbeat_age_seconds{worker} |
gauge | 各ワーカーの最後のハートビートからの経過秒。リースタイムアウトを超えて増え続けるとワーカーの停止を意味します。 |
bajutsu_oldest_in_flight_seconds |
gauge | 実行中でもっとも古い job がキューに投入されてからの経過秒(キューでの待機時間を含みます)。run が遅い、または詰まっている兆候です。 |
bajutsu_unroutable_jobs |
gauge | 稼働中のどのワーカーも実行できないキュー中の job。必要な capability がどのワーカーの広告集合にも一致しません(能力に基づくルーティング)。増え続けるときは「不足している capability を持つワーカーを足す」合図です。 |
bajutsu_max_concurrent |
gauge | 同時実行 job 数の上限(0 は無制限)。 |
/metrics は公開の面ではありません。serve の他の面と同じ認証ゲート(BE-0051)の背後に置かれるので、
トークンを設定していればスクレイパは Authorization: Bearer <token> を送る必要があります。出力に含まれるのは
カウント、経過時間、org やワーカーの識別子だけで、job の spec や結果、トークンは一切含みません。したがって
スクレイプが秘密を漏らすことはありません。どのサーバもキューをデータベースに置くので、1台のマシンでも
Tier B でも、実行中と上限の系列に加えてキュー、リース、ワーカーの系列が現れます。
compose スタックには、Prometheus と Grafana の任意のプロファイルを(caddy と同じように)同梱しています。
docker compose --profile metrics up -d
Grafana は :3000 で起動し(admin / GRAFANA_ADMIN_PASSWORD)、Prometheus のデータソースと、初期の
Bajutsu serve ダッシュボードをあらかじめ組み込んだ状態になります。Prometheus は BAJUTSU_SERVE_TOKEN を
使って /metrics をスクレイプします。ホスト型のスクレイパをこのエンドポイントに向けても構いません。compose
スタックの他の部分と同様、このプロファイルは CI ではなく手元で検証します。起動したうえで、Prometheus の
bajutsu-serve ターゲットが UP であること、ダッシュボードが系列を描画することを確認してください。