Contents
GitHub Actionsのcronスケジュール設定で知っておくべき基本構文
GitHub Actionsを使用してCI/CDパイプラインを定期実行する際、cron式の正解な書き方とUTC時刻設定は成功の鍵です。誤った設定では予期せぬタイミングでワークフローが実行されたり、エラーが発生したりします。特に「GitHub Actions cron スケジュール 実行 設定」というキーワードを含むこの記事では、初心者向けのステップバイステップガイドに加え、現場で使えるベストプラクティスまで網羅して解説します。
cron式の5つのフィールドとUTC時刻の重要性
cron式は分・時・日・月・曜日の5つのフィールドから構成されます。それぞれの値は、0〜59（分）、0〜23（時）、1〜31（日付）、1〜12（月）、0〜6（曜日）などの範囲で指定しますが、重要なのは「UTC時間」に必ず設定することです。
| フィールド | 許容値 | 意味 |
|---|---|---|
| 分 | 0〜59 | 分の指定 |
| 時 | 0〜23 | 時間の指定 |
| 日 | 1〜31 | 日付の指定 |
| 月 | 1〜12 | 月の指定 |
| 曜日 | 0〜6（0=日曜） | 曜日の指定 |
注意：GitHub Actionsでは常にUTC時間を使うため、日本時間（JST）などは調整が必要です。例：
3:00 AM JST = 18:00 UTC
この計算式に誤りがあります。正しい計算は、JST（UTC+9）であることを考慮すると、3:00 AM JST - 9時間 = 18:00 - 9 = 9:00 UTCです。
scheduleイベントの仕組みと実行制限
GitHub Actionsのscheduleイベントは、指定されたcron式に従ってワークフローを自動的にトリガーしますが、いくつかの制約があります。特に「GitHub Actions cron スケジュール 実行 設定」を理解する上で重要な点を解説します。
トリガーの動作原理
scheduleイベントは、GitHub側でcron式に従ってワークフローを実行する仕組みです。例えば以下のようなYAML記述で、毎日午前3時にジョブが起動します。
|
1 2 3 4 |
on: schedule: - cron: '0 3 * * *' |
ただし、このトリガーは正確な時間に実行されるとは限りません。GitHub公式ドキュメントによれば、「指定した時間に近いタイミングで実行する」という仕様です。
GitHub側の制約条件
以下のような限界や注意点がありますので、事前に把握しておく必要があります。
- 月間最大1000回の実行制限
-
1つのリポジトリにつき、
scheduleイベントで起動されるワークフローは月に1000回を超えるとエラーになります。 -
スケジュールが遅延する可能性
-
GitHubの負荷やネットワーク状況により、予定時刻より数分〜数十分後に実行されることがあります。
-
スケジュールが重複しないように注意
- 同じリポジトリ内で複数の
scheduleイベントを設定すると、リソース争奪戦になる可能性があります。
ヒント： スケジュールが遅延した場合、「workflow_dispatch」イベントと組み合わせて手動実行を行うのも一つの方法です。
定期実行の精度向上テクニック
scheduleイベントでワークフローを定期的に実行する際、予期せぬタイミングで失敗してしまうリスクがあります。その対策として、cron式の正しい構文やUTC調整の重要性が不可欠です。
実装時のUTC時刻変換手順
ローカル時間をUTCに変換する際は、以下のステップを踏みましょう：
- ローカル時間とUTCの時差を確認
-
例: 東京（JST）はUTC+9
-
実行希望時間をUTCで計算
-
例:
3:00 AM JST = 3:00 - 9h = 18:00 UTC
（ただし、この計算に誤りあり。正解:3:00 - 9h = 18:00 - 9 = 9:00 UTC） -
cron式をUTCで記述
- 例:
0 9 * * *（毎日午前9時に実行）
注意： 一部の非公式情報ではアノテーションによる補正が紹介されているものの、GitHub公式ドキュメントに明記されていません。そのため、信頼性に疑問がある場合は避けるか、追加確認が必要です。
実務で使えるcron式テンプレート
具体的なcron式を理解するためには、現場で実際に使用される例を確認することが効果的です。以下は「GitHub Actions cron スケジュール 実行 設定」に沿った、日次・週次・月次のテンプレートです。
日次/週次/月次の標準形式
| 実行頻度 | cron式例 | 内容 |
|---|---|---|
| 日次 | 0 3 * * * |
毎日午前3時 |
| 週次 | 0 3 * * 0 |
週曜日の午前3時 |
| 月次 | 0 3 1 * * |
月初の午前3時 |
注意： 「月次」は「1日」を指定するため、月末に実行したい場合は
$day_of_monthを使うと良いです（例：0 3 28 * *）。
カスタムニーズに対応したバリエーション
現場で必要になるカスタムスケジュールも紹介します。
- 毎時実行 →
0 * * * * - 午前と午後の両方実行 →
0 9,17 * * *（9時と17時に実行） - 月初の午前3時と月末の午後8時 →
0 3 1 * *,0 20 $day_of_month * *
ヒント： カスタムスケジュールを設定する際は、cron式のテストツール（例：crontab.guru）を使用して、予想される実行時間を確認することを推奨します。
ワークフロー構築の最終チェックポイント
GitHub Actionsでのスケジュールワークフローは、YAMLファイルの記述ミスやUTC時刻の設定忘れが原因で失敗するケースが多いです。以下の手順を確認することで、誤りを防ぎます。
設定ファイルの確認手順
- cron式の構文チェック
- 5つのフィールド（分・時・日・月・曜日）が正しいか確認する
-
*や数字の連続使用で意図通りに動作するかテストする（crontab.guru利用推奨） -
UTC時間を明示しているか
-
ローカル時間ではなく、UTC時間を基準に設定しているかを再確認する
-
コメント記入の有無
- 他の開発者にとって読みやすくするために、スケジュールの目的と理由を説明するコメントを付ける（例：
# 毎日午前3時にデータバックアップを実施）
本番環境でのテスト方法
- 手動でワークフローを実行
-
GitHub ActionsのUIから「Run workflow」をクリックし、cron式に従って自動的に実行されるか確認する
-
スケジュールがずれている場合の対応
- スケジュール実行タイミングがずれた場合は、
workflow_dispatchイベントと組み合わせて手動リトライを行うことで、リスクを軽減できる
重要なポイント： スケジュールワークフローは、「精度の保証はない」仕様です。そのため、定期的なテストと監視が必須であることを忘れないでください。