cron-schedule-planner

Cron スケジュールプランナー

リポジトリ全体から GitHub Actions の on.schedule cron 式を収集し、 各ワークフローのリソース負荷を分類して、UTC の cron 時刻をローカルの タイムゾーンに変換し、時間別ヒストグラム、重複、具体的な分散案を含む Markdown レポートを作成します。

読み取り専用です。このスクリプトがワークフローを編集することはありません。提案を適用するのは、 ユーザーが確認した後だけです。

手順

ステップ 1：対象リポジトリを決める

• デフォルト：認証済みの gh ユーザーのすべてのリポジトリ（ローカルへのチェックアウトは 不要です）。
• --owner <owner> で別のオーナーをスキャンします。
• --repo <owner/repo>（繰り返し指定可能）で対象を明示します。
• --local <dir> で GitHub API の代わりにローカルのチェックアウトをスキャンします。

ステップ 2：スクリプトを実行する

bash scripts/cron-schedule-planner.sh

よく使うバリエーション：

# Specific owner, Swiss local time, report in target/
bash scripts/cron-schedule-planner.sh --owner dboeckli --tz Europe/Zurich

# Local checkouts (no GitHub API)
bash scripts/cron-schedule-planner.sh --local ~/projects/referenzen

# A few explicit repos
bash scripts/cron-schedule-planner.sh --repo dboeckli/ai-agent-skills --repo dboeckli/camel-first

ステップ 3：結果を提示する

スクリプトは時間別ヒストグラム、重複、提案を出力し、 target/cron-schedule-overview.md に書き込みます。次の内容を要約してください。

• 見つかったリポジトリ数／スケジュール済みエントリー数
• 最も集中している UTC の時間帯（重複）
• 集中している時間帯にある高負荷のジョブ

ステップ 4：確認後にのみ提案を適用する

分散案はヒューリスティックなものです（高負荷のジョブを集中している時間帯から 空いている時間帯に移動し、分と日付のフィールドは維持します）。差分として提示し、 明示的な確認を得た後にのみワークフローファイルを変更してください。 自動で編集してはいけません。

オプション

オプション	説明
--owner <owner>	スキャン対象の GitHub オーナー（デフォルト：認証済みユーザー）
--repo <owner/repo>	リポジトリを明示（繰り返し指定可能）。オーナーのスキャンを無効化
--local <dir>	GitHub の代わりに<dir>以下のローカルチェックアウトをスキャン
--tz <zone>	Local列に表示するローカルタイムゾーン（デフォルト Europe/Zurich）
--limit <n>	オーナーのスキャンで取得するリポジトリの最大数（デフォルト 200）
--out <file>	Markdown レポート（デフォルト target/cron-schedule-overview.md）
--no-report	コンソールにのみ出力し、レポートファイルは作成しない
--top <n>	分散案の最大数（デフォルト 5）
--queue-stats	UTC の時間帯ごとの観測キュー時間を追加（gh run list経由）
--runs <n>	キュー統計で取得するリポジトリごとの最大実行数（デフォルト 50）

出力

target/cron-schedule-overview.md：

• スケジュール済みワークフローテーブル：リポジトリ、ワークフロー、cron（UTC）、UTC 時刻、ローカル 時刻、頻度、負荷、根拠。
• UTC の時間帯ごとの実行数ヒストグラム（バー）。
• 頻度／曜日ごとの実行数。
• 重複 — スケジュールされた実行が 2 件以上ある UTC の時間帯。
• UTC の時間帯ごとの観測キュー時間（--queue-stats指定時）— 最近の実行について、 createdAtからstartedAtまでの平均および最大待ち時間。実測に基づく競合の指標です。
• 分散案 — 集中している時間帯の高負荷ジョブを空いている時間帯に移動します。--queue-stats指定時は、 観測されたキュー時間が最も短い空き時間帯を優先します。

分類

負荷はワークフローの内容からヒューリスティックに判定されます。正確なパターンと UTC／タイムゾーンのルールについては、references/classification-and-timezones.mdを参照してください。

• high — Docker Compose、Testcontainers、サービスコンテナー（services:）、 Kind／k3s クラスター、マトリックスビルド。
• medium — Maven／Gradle のフルビルド、Docker イメージのビルド。
• low — lint／format／validate およびその他のメタワークフロー。

例

例 1：スケジュールされたビルドが競合していますか？

ユーザーの発言：「スケジュールされた GitHub Actions のビルドは競合していますか？」

操作：

1. bash scripts/cron-schedule-planner.sh --owner <owner> を実行します
2. UTC で混み合っている時間帯と、その時間帯の高負荷なジョブを報告します
3. target/cron-schedule-overview.md を案内します

結果：具体的な根拠を示した、すべてのリポジトリにわたる競合の概要です。

例 2：Testcontainers のビルドはいつ実行するべきですか？

ユーザーの発言：「Testcontainers のビルドはいつスケジュールすればよいですか？」

操作：

1. プランナーを実行して、混み合っている時間帯（競合）を特定します
2. 候補の中から空いている時間帯を 1 つ提案します
3. 具体的な cron の差分を提示し、確認後にのみ適用します

結果：競合の少ない時間帯と、適用可能な cron の変更案です。

トラブルシューティング

gh: not found または認証エラー

スクリプトには認証済みの gh が必要です。gh auth status を実行してください。失敗する場合は、ユーザーによる認証が必要です。または、ローカルのチェックアウトで --local <dir> を使用してください。

レポートが空

対象範囲内のワークフローに on.schedule エントリがありません。リポジトリの対象範囲（--owner、--repo、--local）と、ワークフローで schedule: の cron が実際に定義されていることを確認してください。

時刻が 1 時間ずれているように見える

cron は常に UTC です。現地時刻は現在の日付に基づいて計算されるため、夏時間への移行時に 1 時間ずれることがあります。夏時間の変更後に再実行するか、手動で調整してください。

--queue-stats に表示されるデータが少ない、または何もない

ほとんどの実行で GitHub が startedAt と createdAt を同じ時刻として報告するため（キュー待ち時間が記録されないため）、得られる情報は限られています。古い実行も含めるには、--runs を増やしてください。大きな差については注意して解釈してください。ランナーの競合だけでなく、承認ゲート、同時実行の制限、手動実行が原因の場合もあります。