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 に生成物が残っているかを実際に落として中身を見る。

gh run list --repo <owner>/<repo> --workflow <workflow>.yml --limit 20 \
  --json databaseId,createdAt,conclusion,status
gh run download <失敗したrunのid> --repo <owner>/<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倍払う。

# 予定時刻ではなく「実際に起動した時刻」を測ってから閾値を決める
gh run list --repo <owner>/<repo> --workflow <workflow>.yml --limit 30 \
  --json createdAt,conclusion --jq '.[] | "\(.createdAt) \(.conclusion)"'

観測した最大遅延の外側に dispatch の開始時刻を置き、さらに後ろに alarm を置く。 定数に名前を付けて公開し、「定刻直後は wait になる」ことを回帰テストで固定する。

export const DISPATCH_AFTER_HOUR = 11; // 定刻+4時間。観測した最大遅延の外側
export const ALARM_AFTER_HOUR = 14;

再実行には1日あたりの上限を必ず付ける（2回程度）。上限に達したら黙るのではなく鳴らす。 実行回数は日付をキーにした小さな JSON に記録する。

投入したら必ず read-back する

POST が 2xx を返したことは、アプリが保存したことの証拠にならない。 投入後にアプリの保存先（キャッシュファイル・API の GET・DB）を読み直し、 狙った日付のデータになっているかを確認して、違えば非ゼロ終了する。

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 が赤くなること自体は放置してよい。 それは「その日トンネルが落ちていた」という有用な記録になる。監視は鮮度側で行う。