# CI から自ホストへ push する連携が「届かない日」を、artifact からの pull で埋める ## 誰のための手順か CI（GitHub Actions 等）で毎日データを生成し、**自分たちのマシンやオンプレのアプリへ HTTP POST で 届けている**連携がある。その配達先が家庭内 PC・社内 PC・トンネル公開（Tailscale Funnel / ngrok / Cloudflare Tunnel 等）で、**たまに到達できず job ごと赤くなる**。 この手順は「配達先を常時稼働にする」以外の道で、**データの欠落をゼロにする**ためのもの。 配達先の可用性を上げられない（自宅PC・個人のトンネル・予算の制約）状況で効く。 ## 最初に確かめる — 失われたのは「生成」か「配達」か ここを取り違えると直し方を丸ごと間違える。次を実測する。 1. 失敗した run のログで、落ちているのが**生成処理か POST か**を特定する。 POST の例外（DNS 解決失敗・接続拒否・タイムアウト）なら配達側。 2. **失敗した run の artifact に生成物が残っているか**を実際に落として中身を見る。 ```bash gh run list --repo / --workflow .yml --limit 20 \ --json databaseId,createdAt,conclusion,status gh run download <失敗したrunのid> --repo / --dir ./_check find ./_check -type f | head ``` 多くのワークフローは `actions/upload-artifact` を `if: always()` で置いているので、 **POST が落ちた run でも生成物は GitHub に残っている**。残っていれば 「失われたのは配達だけ」であり、**配達先から取りに行けば欠落は埋まる**。 > 生成処理の前に artifact を書いていない場合は、まず「生成物をファイルに書く → POST」の順に > 分解し、`upload-artifact` を `if: always()` で足すところから始める。これが回収の前提になる。 ## 直し方 — 配達先に「取りこぼし回収」を置く CI 側は触らない。**配達先のマシンで定期的に走るツール**を1本足す。 ### 判定表を先に決める 実装より先に、状態と行動の対応を表にする。ここを曖昧にすると必ず暴走する。 | 状態 | 行動 | |---|---| | ローカルに当日ぶんが既にある | `noop`（何もしない） | | 当日ぶんの artifact が見つかった | `ingest`（取得して投入し、read-back で確認） | | artifact が無い・**遅延の許容時刻より前** | `wait`（待つ） | | artifact が無い・許容時刻を過ぎた・再実行が上限未満 | `dispatch`（CI を手動起動）| | artifact が無い・再実行も打ち止め・警戒時刻を過ぎた | `alarm`（**非ゼロ終了**）| この判定を**純関数として切り出し**、表の各行をそのままテストにする。 ネットワークも CI も叩かないので、テストは速く、壊れたら必ず気づく。 ### スケジュールの遅延を必ず織り込む **CI の定時実行は遅れる。** 実測で1〜3時間ずれることがある。 定刻を「もう走ったはず」の根拠にすると、遅れて到着する本来の run と自分の `dispatch` が **二重に走り、生成コスト（LLM API 等）を毎日2倍払う**。 ```bash # 予定時刻ではなく「実際に起動した時刻」を測ってから閾値を決める gh run list --repo / --workflow .yml --limit 30 \ --json createdAt,conclusion --jq '.[] | "\(.createdAt) \(.conclusion)"' ``` 観測した最大遅延の**外側**に `dispatch` の開始時刻を置き、さらに後ろに `alarm` を置く。 定数に名前を付けて公開し、「定刻直後は `wait` になる」ことを回帰テストで固定する。 ```js export const DISPATCH_AFTER_HOUR = 11; // 定刻+4時間。観測した最大遅延の外側 export const ALARM_AFTER_HOUR = 14; ``` 再実行には**1日あたりの上限**を必ず付ける（2回程度）。上限に達したら黙るのではなく鳴らす。 実行回数は日付をキーにした小さな JSON に記録する。 ### 投入したら必ず read-back する POST が 2xx を返したことは、**アプリが保存したことの証拠にならない**。 投入後にアプリの保存先（キャッシュファイル・API の GET・DB）を読み直し、 狙った日付のデータになっているかを確認して、違えば非ゼロ終了する。 ```js const res = await fetch(url, { method: 'POST', headers, body, signal: AbortSignal.timeout(30_000) }); if (!res.ok) fail(`POST が非2xx: ${res.status}`); const after = readLocalState(statePath); if (after?.asOf !== targetDay) fail(`POST は2xxだが反映されていない（期待=${targetDay} 実際=${after?.asOf}）`); ``` ### 定期実行への登録は「自己同期する起動器」を経由させる ツールのパスを直接タスクに登録すると、**改修のたびに再登録が要る**。 起動のたびにリポジトリを同期してから対象を実行する薄い起動器を1枚挟むと、 以後コードを直しても再登録が不要になり、終了コードもログに残る。 ## 監視の指標を「配達の真実」に付け替える 回収を入れると、**CI の run は赤いがデータは届いている**という状態が生まれる。 「workflow が成功したか」を監視し続けると、届いているのに警報が鳴り続け、 やがて誰も見なくなる。 - 監視対象を**配達先のデータの鮮度**（保存されたレコードの日付）に変える。 - 逆方向（workflow は緑だが届いていない）は、POST 失敗が job 失敗になる設計なら起きない。 そこを先に確認してから付け替える。 - 生成が完全に壊れた場合も配達が止まるので、鮮度の指標ひとつで両方を検出できる。 ## 原因が分からないまま終わりそうなときは、計測を残す 配達先が落ちた**真因が特定できない**ことがある。仮説を潰しても足跡が残っていない場合、 推測で埋めずに**次回確定できる記録**を仕込んで終える。到達性は層に分けて記録する。 | 層 | 見るもの | |---|---| | DNS | 公開リゾルバを明示して名前が引けるか | | 外部 HTTPS | 公開URLに実際に到達できるか（ステータスは問わない。応答が返れば到達） | | ローカル | アプリ自身が生きているか | `verdict` は **`ローカル停止` > `DNS不在` > `HTTPS到達不可` > `ok`** の優先で決める。 アプリが落ちているだけの時にトンネルの障害と誤読しないための順序。 1行 JSON を追記していけば、後から「障害の開始と終了の時刻」をそのまま言える。 ### 落とし穴: 計測ツール自身の偽陽性を先に潰す **新しく作った計測は、まず「正常時に正常と言うか」を実機で確かめる。** 3回連続で `ok` が 出るまで信用しない。異常検知の前に偽陽性を潰す。自分の観測装置が壊れていることは、 観測装置自身では気づけない。 実例（Node.js）: **`dns` の `Resolver` を1つ作って `resolve4` と `resolve6` を並行に投げると、 応答があるのに片方が `ETIMEOUT` になる。** | 実行形 | 結果（実測） | |---|---| | 同一 Resolver で並行 | 片方が `ETIMEOUT` — **5050ms** | | 別 Resolver で並行 | 両方成功 — 30ms | | 同一 Resolver で逐次 | 両方成功 — 22ms | `nslookup` や単発呼び出しでは 6〜7ms で返るので**手叩きの確認では絶対に再現しない**。 これを踏むと「毎時 DNS 不在を記録し続ける常時赤の監視」になり、指標として死ぬ。 - **`Resolver` は問い合わせごとに新しく作る**（共有するなら逐次に落とす）。 - 全体タイムアウトは個別のタイムアウトより**必ず長くする**。同値だとレースになり、 成功した側まで巻き添えで落ちる。 - 疑うときはコードと同じ形を再現して測る。単発の手叩きが通ることは根拠にならない。 ## 完了の確かめ方 テストが緑なだけでは終わっていない。次まで実測する。 1. 保存先の状態を退避のうえ**わざと古い日付に書き換え**、「届かなかった日」を再現する。 2. ツールを実行し、artifact 取得 → POST → read-back まで通ることを確認する。 3. 復元されたデータが退避したものと**フィールド単位で一致**することを確認する。 4. 定期実行の登録後、**実際に1回起動して終了コードとログを読む**。登録できたことは動作の証拠ではない。 ## 何をしないか - **POST のリトライ追加は、配達先が長時間落ちる型の障害には効かない。** 数分のリトライは数時間〜数日の不通を埋められない。赤くなる時刻を遅らせて可視性を下げるだけになる。 短時間のゆらぎが実測できている場合にだけ足す。 - 回収が入ったあとも、CI の run が赤くなること自体は放置してよい。 それは「その日トンネルが落ちていた」という有用な記録になる。監視は鮮度側で行う。 ---