定期実行が「手動なら動く」まま何週間も止まっているのを見抜いて直す

GitHub Actions の定期ジョブ（schedule）が止まっていても、手で叩くと成功するので壊れて見えないことがある。この状態は数週間気付かれずに放置されやすい。実際に週次の自動配信が3週間、日次の自動配信は一度も成功しないまま放置されていた事例をもとに、検知・修復・再発防止までを手順化する。

1. まず「手動実行が通ること」を生存証明にしない

これが最大の落とし穴。多くのワークフローは冒頭に「今日すでに成功した実行があればスキップする」といった preflight を持ち、そこで自分自身の実行履歴を API で問い合わせる。この preflight は

if [ "$EVENT_NAME" != "schedule" ]; then
  echo "should_run=true"; exit 0
fi
# ここから下は schedule のときだけ通る（API 問い合わせ）

という形になっていることが多く、手動実行は API を叩かずに素通りする。つまり API 側の権限が壊れていても手動だけは成功し続ける。

生存確認は必ずイベント種別を絞って行う。

gh run list --repo <owner>/<repo> --workflow <name>.yml \
  --event=schedule --limit 15 --json createdAt,conclusion

--event=schedule を外すと手動実行の成功が混ざり、判定が甘くなる。

2. 典型的な真因: トークンの既定権限に actions が無い

preflight が実行履歴を問い合わせると、既定のトークン権限では次で落ちる。

HTTP 403: Resource not accessible by integration
  (https://api.github.com/repos/<owner>/<repo>/actions/workflows/<name>.yml)
##[error]Process completed with exit code 1

既定で付くのは Contents / Metadata / Packages の read だけで、Actions API は含まれない。shell: bash -e なら 403 の時点で即 exit 1 になり、needs: preflight の本体ジョブは一切実行されない（＝配信ゼロ、成果物ゼロ）。

修正は該当ジョブに最小権限を明示するだけ。

jobs:
  preflight:
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read

権限が効いたかは次の schedule を待たずに確認できる。 手動実行のログにある ##[group]GITHUB_TOKEN Permissions グループに Actions: read が出るかを見ればよい（権限ブロックはイベント種別に関係なく適用されるため）。

3. 403 を直すと「次の層」が出てくる

権限を直したら今度は本体ジョブが動き出し、そこで別の障害が露出することがある。実例では必須の環境変数が渡し忘れられており、起動直後にクラッシュした。

RuntimeError: 環境変数 <VAR_NAME> が未設定
  config.py:62  _require("<VAR_NAME>")

同じ設定読み込みを共有する別のワークフローには渡してあり、片方だけ抜けていた。同一の設定ローダを使うワークフローが複数あるなら、env ブロックを機械的に差分比較する。

grep -E "^\s+[A-Z_]+:" .github/workflows/a.yml | sed 's/:.*//' | tr -d ' ' | sort > /tmp/a
grep -E "^\s+[A-Z_]+:" .github/workflows/b.yml | sed 's/:.*//' | tr -d ' ' | sort > /tmp/b
comm -23 /tmp/a /tmp/b   # a にあって b に無いもの

教訓: 1層直した時点で「直った」と言わない。 実際に最後まで完走する実行（副作用の無い dry-run モードがあればそれ）を1回通してから完了とする。

4. 二度と気付けない状態を作らない — 死活監視を仕組みにする

人間の記憶に頼らず、毎日読むもの（AI エージェントの起動時コンテキスト、朝のダッシュボード、通知など）に自動で出す。

監視対象の定義（設定ファイル）

[
  {"label": "週次レポート", "repo": "<owner>/<repo>", "workflow": "weekly.yml", "everyDays": 7},
  {"label": "日次サマリ",  "repo": "<owner>/<repo>", "workflow": "daily.yml",  "everyDays": 1}
]

判定は純関数に切り出す（テストできる形にする）

// status: never(成功履歴なし) / stale(想定間隔×1.5 超) / unknown(取得失敗) / ok
export function evaluate(entries, lastSuccessByKey, nowMs) {
  return entries.map((entry) => {
    const key = `${entry.repo}#${entry.workflow}`;
    const raw = lastSuccessByKey[key];
    if (raw === undefined) return { key, status: 'unknown' };
    if (raw === null)      return { key, status: 'never' };
    const ageDays = Math.max(0, (nowMs - Date.parse(raw)) / 864e5);
    return { key, ageDays, status: ageDays > entry.everyDays * 1.5 ? 'stale' : 'ok' };
  });
}

外部コマンド実行と判定ロジックを分けておくと、gh を呼ばずに境界値までテストできる。

実データ取得

const r = spawnSync('gh', ['run','list','--repo',entry.repo,'--workflow',entry.workflow,
  '--event=schedule','--status','success','--limit','1','--json','updatedAt'],
  { encoding: 'utf8' });
// 失敗しても throw せず undefined（=unknown）にする。監視が本体を止めてはいけない

stale か never が1件でもあれば終了コードを非ゼロにし、呼び出し側が反応できるようにする。

設計上のポイント

• unknown を ok に丸めない。 取得失敗を正常扱いにすると監視が静かに無意味になる
• しきい値は「想定間隔 × 1.5」程度に緩める。実行が数時間ずれる程度で誤報を出すと無視されるようになる
• 監視自体の未実行も検知する（結果ファイルのタイムスタンプが N 日以上古ければ警告）

5. 併せて入れる2つのガード

送信前ガード

自動配信は「壊れた成果物をそのまま配る」事故が起きる。読めない/欠けた内容を配るくらいなら、送らずにジョブを失敗させる方がよい（失敗すれば気付ける）。

• 出力が想定言語を1文字も含まない、空、テンプレのプレースホルダが残っている → 送信せず例外
• 生成 AI を使うなら stop_reason を必ず記録し、トークン上限で打ち切られていたら例外にして再試行

配信リポジトリに最小 CI

定期実行の当日ではなく push / PR の時点で壊れを止める。テストが数本あるだけでも、回帰を配信日まで持ち越さずに済む。

on: { push: { branches: ["**"] }, pull_request: }

6. 付随して踏みやすい罠

• 成果物（artifact）の保存期限: 他システムが定期実行の artifact を読んでいると、配信停止＋保存期限切れの二重で「取得できない」状態になる（no valid artifacts found to download）。配信が止まった影響は下流にも波及する
• 保存期限は配信間隔より十分長く取る

チェックリスト

• --event=schedule の直近成功日時で生存判定しているか（手動実行の成功で判断していないか）
• 実行履歴 API を叩くジョブに permissions: {actions: read} があるか
• 1層直したあと、最後まで完走する実行を1回通したか
• 死活監視が毎日読むものに出ているか。unknown を握りつぶしていないか
• 監視自体が動いていないことを検知できるか
• 壊れた成果物を配らないガードがあるか
• push / PR で回る最小 CI があるか