# GitHub Actions のジョブ実行時間を実測ベースで削る手順書 AI エージェントにそのまま読ませて実行させる前提の指示書。 対象は「定期実行（cron）のジョブが長くて Actions 課金が増えている」リポジトリ。 ## 前提知識（ここを外すと的を外す） GitHub Actions は **ジョブ単位で分単位の切り上げ**課金。したがってコストは次の2種類に分かれる。 | 型 | 例 | 効く対策 | |---|---|---| | 短時間・高頻度 | 8秒の処理を15分毎 | **既存ジョブへステップとして統合**（起動オーバーヘッドを1回に集約） | | 長時間・低頻度 | 40分の日次バッチ | **中身の往復回数を削る**（統合しても意味がない） | 「8秒の処理を15分毎」は実計算3時間でも **月766分**課金される。新しい cron を作る前にこの表で分類する。 ## 手順1: 実測を取る（推測で着手しない） ```bash # ワークフロー別の直近 run（必ず event=schedule に絞る。手動実行は条件が違う） gh api "repos///actions/workflows/.yml/runs?event=schedule&per_page=5" \ --jq '.workflow_runs[]|"\(.id) \(.created_at) \(.conclusion)"' # 実行時間（一覧APIには無い。timing でしか取れない） gh api "repos///actions/runs//timing" --jq '.run_duration_ms' # ステップ別の所要時間（どこが遅いかはこれで確定する） gh api "repos///actions/runs//jobs" \ --jq '.jobs[].steps[]|"\((( (.completed_at|fromdateiso8601) - (.started_at|fromdateiso8601) )))s \(.conclusion) \(.name)"' ``` **⚠ 最重要の落とし穴: baseline は「変更直前の schedule 実行」から取る。** 古い run を1本だけ見て「この処理は○秒」と決めると桁を間違える。実例では、 古い run で 696秒/526秒だったステップが、直前の run では 264秒/**7秒**だった。 7秒の処理を「526秒だから」と最適化しても効果はゼロで、実際にそういう変更がマージされた。 最低2〜3本の schedule run を並べ、ばらつきを見てから決める。 - `billable.UBUNTU.total_ms` は 0 を返すことがある。`run_duration_ms` を使う。 - `continue-on-error: true` のステップは **API 上の conclusion が success** になる。 失敗を見たいなら後続の `if: steps.X.outcome == 'failure'` ステップの結果とログを見る。 - 10秒未満で終わっている run は「起動していない」可能性（支出上限・権限）。集計から除外する。 ## 手順2: 効くレバーを選ぶ ### レバーA: 短時間・高頻度ジョブを統合する 統合先は **cron 式ではなく実発火時刻を実測して選ぶ**。GitHub は schedule を大量に間引く。 ```bash gh api "repos///actions/workflows/.yml/runs?event=schedule&created=&per_page=100" \ --jq '.workflow_runs[].created_at' ``` 実例では `*/15 * * * *` の実発火は **41回/日・間隔ランダム（最大90分空く）**で、分は事実上ランダムだった。 だから「15分毎のジョブ内で `MIN=$(date -u '+%-M'); [ "$MIN" -ge 15 ] && exit 0` して hourly を維持」は成立しない （`:00-:14` に入るのは約23%だけ＝発火回数が半分以下になる）。**同じ cron 式を持つジョブ同士だけ**を統合する。 統合後の注意: - 前ステップが失敗すると後続が **silent skip** される。全ステップに `if: ${{ !cancelled() }}` を付ける - 旧ファイルは `workflow_dispatch` だけ残し、`schedule` を消す（二重発火の防止） ### レバーB: per-row の往復をバルク化する（長時間ジョブの本命） 「1行ずつ `await`」を潰す。典型は次の3つ。 1. 行ごとの INSERT/UPDATE → **500件チャンクのバルク** 2. 行ごとの SELECT（存在確認・突合） → **事前に一括取得してメモリ上の Map/Set で突合** 3. 同じ値に更新する行 → **1回の `IN (...)` にまとめる**（500件ずつ分割） **エラー分離を落とさないこと。** 1行ずつ書いていた頃は「1行の不正データでも他は入る」性質があった。 バルク化で「1行の不正データで500行が丸ごと落ちる」のは**劣化**なので、 **チャンクが失敗したらそのチャンクだけ従来の per-row 実行にフォールバック**する形にする。 フォールバックした件数はログに出す（出さないと効いているか分からない）。 ### レバーC: 外部API律速ならレート制御を入れる 並列度を上げても、外部APIのクォータが天井なら意味がない。実例では並列度を 5→12 に上げても 2,830秒→2,973秒で**改善ゼロ**だった（クォータ律速だったため）。 効いたのは「固定バッチ → ワーカープール」＋「共有トークンバケットで平準化」＋「呼び出し回数自体を半減」で、 **49.6分 → 30.6分**になった。 - 固定バッチ（`for i += N { await Promise.all(batch) }`）は**バッチ内の最遅1件を待つ**。 共有インデックスから次の仕事を取る N ワーカーに置き換える - クォータの単位を確認する（「1ユーザーあたり毎分」なのか「プロジェクトあたり」なのか）。 ユーザー単位なら、1ユーザーで代理アクセスしている限りそれが天井 - 同じリソースを2回叩いていないか確認する（例: 候補名を順に試して外れたらもう1回叩く実装は、 当たった名前を永続キャッシュすれば呼び出しが半減する） ## 手順3: 実装時の落とし穴（実測で踏んだもの） 1. **`ON CONFLICT` は同一statement内に同じキーが2回あるとチャンク全体を落とす** （`cannot affect row a second time`）。溜めてから投げる設計では**キーで dedupe しないと 全件フォールバックして効果ゼロ**になる。実例では 1,347行すべてがフォールバックし、 バルク化の効果が完全に消えていた。dedupe は「同一キーは最後の1件を残す」＝逐次 upsert と同じ結果にする。 2. **トークンバケットは初期トークンを 0 にする**。`tokens = capacity` で初期化すると 開始直後に capacity 件を一斉発射してレート上限を超える（実例では 429 が43件中33件、最初の2分に集中）。 3. **`order` の無い LIMIT/OFFSET ページングは行を取りこぼす**。 `.range(from, to)` 系で全件取得するなら必ず `.order("id")` を付ける。 取りこぼした行は「存在しない」と判定され、**重複レコードを毎回作る**バグになる。 4. **テストのために本番経路へエントリポイントガードを足さない**。 `if (import.meta.url === pathToFileURL(process.argv[1]).href) { main() }` は、判定が環境差で false になると **成功扱いで何もせず終了**する。ヘルパーを共有モジュールへ切り出してテストする。 5. **DDL を伴う最適化（キャッシュ表の追加など）は、表が無い時に警告して続行**する作りにする。 コードのマージと DDL 適用は別タイミングになるため、必須にすると定期実行が丸ごと落ちる。 ## 手順4: 「処理が欠けていないこと」を検証する 速くなったかだけでなく、**同じ仕事をしたか**を機械照合する。 - スクリプトの最終行に `結果: {"processed":N,"inserted":N,"updated":N,"skipped":N,...}` のような **カウンタ JSON を出す**。最適化の前後で**キーと意味を変えない**（比較できなくなる） - 変更前の run のカウンタをログから取り、変更後と突き合わせる - 合計が対象件数と一致するか（例: `対象=799` に対し `成功269 + 変更なし528 + エラー2 = 799`） - フォールバック件数が想定内か（`fallbackRows: ... = 0` が理想） ## 手順5: 効果を「請求」で確認する 見積りで完了と言わない。月あたりの課金分は **「1回の実時間を分に切り上げ × 月の実発火回数」**で再計算し、 実額は**次の請求サイクル**で確認する。 ## 発注テンプレ（AI に渡す形） ``` 対象: / の .yml 目的: ジョブ実行時間の短縮（機能・出力形式は変えない） 実測: 直前の schedule run のステップ別時間を timing/jobs API で取得し、 最も長いステップから着手する 制約: - 挙動を変えない（判定条件・対象の絞り込み・カウンタの意味） - エラー分離を落とさない（チャンク失敗時は per-row フォールバック） - ページングには order を付ける - 外部APIのクォータ単位を確認し、レート制御を入れる（初期トークン0） - ON CONFLICT に投げる前にキーで dedupe する 完了条件: 1. 型検査・ユニットテスト・ビルドが通る 2. 実行後のカウンタが変更前と整合（処理欠落なし） 3. run_duration_ms の前後を数値で示す ``` ---