コンテンツへスキップ

GitHub Actions の Cron スケジュール: UTC、遅延、注意点

最終更新日

スケジュールワークフローは単純に見えますが、いくつかの規則で戸惑うことが多くあります。時刻はUTCで扱われ、実行が遅れたりスキップされたりすることがあり、スケジュールはデフォルトブランチでのみ動作します。このガイドでは、構文と、計画時に考慮すべき動作について説明します。

構文

on:
  schedule:
    - cron: "30 5 * * 1-5"   # 05:30 UTC, Monday to Friday
    - cron: "0 */6 * * *"    # every 6 hours, on the hour
  workflow_dispatch:         # lets you run it by hand too

cron式は5つのフィールドで構成されます:

 minute (0-59)
 | hour (0-23)
 | | day of month (1-31)
 | | | month (1-12 or JAN-DEC)
 | | | | day of week (0-6 or SUN-SAT)
 | | | | |
 * * * * *

Supported operators: (any), , (list), - (range), / (step). GitHub uses POSIX cron syntax. Extensions from other systems, like @daily, L, ? or a seconds field, do not work. Quote the expression in YAML, because a leading is otherwise parsed as a YAML alias and the file is invalid.

cronビルダーを使うと、平易な言葉で書いたスケジュールをcron式に変換し、次回の実行時刻を表示できます。間違いを防ぐ最も簡単な方法です。

既定ではすべてUTCです

既定では、GitHubはスケジュールをUTCで評価します。GitHubの最新ドキュメントでは、IANAタイムゾーン名(例: America/New_York)を指定できる任意のtimezoneキーについても説明されているため、以下の2つのスケジュールを使う回避策に頼る前に、イベントのリファレンスを確認してください。設定しない場合、夏時間による調整はありません。0 9 * * *に設定したジョブは09:00 UTCに実行されます。これはニューヨークでは夏は05:00、冬は04:00にあたります。「現地時間の09:00を一年中維持したい」場合は、次の2つの方法があります:

  • 一致する可能性のあるUTCの2つの時刻にスケジュールを設定し、誤っている方の実行は早期に終了させます:
on:
  schedule:
    - cron: "0 13 * * 1-5"   # 09:00 EDT
    - cron: "0 14 * * 1-5"   # 09:00 EST
jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - name: Only proceed at 09:00 New York time
        id: gate
        run: |
          hour=$(TZ=America/New_York date +%H)
          [ "$hour" = "09" ] && echo "go=true" >> "$GITHUB_OUTPUT" || echo "go=false" >> "$GITHUB_OUTPUT"
      - if: steps.gate.outputs.go == 'true'
        run: ./send-report.sh
  • 年に2回、1時間のずれを受け入れ、その旨をコメントに書いておきます。

スケジュールは正確ではありません

GitHubのドキュメントによると、負荷の高い時間帯にはスケジュールワークフローが遅延することがあり、高負荷の時間帯には毎時の開始時刻が含まれます。実際には、0 * * * *のジョブが数分遅れて開始することがよくあり、負荷が高いときには実行が欠落することもあります。そのため:

  • 毎時の開始時刻は避けてください。17 3 * * *のように奇数の分を使います。遅延を減らす最も簡単な方法です。
  • 正確なタイミングを前提にしないでください。正確に09:00に実行しなければならないワークフローは、クラウドスケジューラーからworkflow_dispatchのAPIを呼び出すなど、別の仕組みでトリガーすることをおすすめします。
  • ジョブを冪等にしてください。「現在時刻から1時間前」ではなく、実行のイベント時刻から計算した処理ウィンドウを使うと、遅延や重複した実行があっても同じ結果になります。
  • 最小間隔:GitHubがサポートする最短の間隔は5分ごとです。それより頻繁な実行が必要な場合は、別のトリガーや常時稼働のサービスを使ってください。

スケジュールが実行される場所

  • スケジュールワークフローは、デフォルトブランチの最新のコミットで実行されます。他のブランチにあるワークフローファイルは、スケジュールでは無視されます。変更をテストするには、デフォルトブランチにプッシュするか、ブランチを対象にworkflow_dispatchで手動実行してください。
  • スケジュール実行では、GITHUB_REFにリポジトリのデフォルトブランチが使われます。そのため、別途指定しない限り、チェックアウトではデフォルトブランチが取得されます。
  • 実行の主体は、ファイル内のcron行を最後に変更したユーザーです。そのユーザーが組織から削除されると、実行が停止する場合があります。必要に応じて、サービスアカウントでcron行に軽微な編集をコミットしてください。

60日ルール

パブリックリポジトリでは、リポジトリのアクティビティがない状態が60日続くと、GitHubはスケジュールワークフローを自動的に無効にします。メールで通知が届くので、Actionsの画面、または次のコマンドから再度有効にする必要があります:

gh workflow enable schedule-workflow.yml

GitHubのドキュメントによると、プライベートリポジトリはこのルールの影響を受けません。アクティビティの少ないパブリックリポジトリでスケジュールに依存している場合は、ボットによる定期的なコミットなど、リポジトリを維持するステップを追加するか、外部のスケジューラーを使ってください。

GitHub Actionsのスケジュールが実行されない

スケジュールが実行されない場合や、「GitHub Actionsのスケジュールが動かない」という症状が断続的に起きる場合は、次の項目を順に確認してください:

  1. デフォルトブランチのみ。スケジュールワークフローは、デフォルトブランチの最新のコミットから実行されます。機能ブランチにしか存在しないワークフローは、決して起動しません。
  2. 60日ルール。パブリックリポジトリでは、60日間リポジトリのアクティビティがないと、スケジュールワークフローは自動的に無効になります。Actionsタブから再度有効にしてください。
  3. 構文と引用符。cron式が不正な場合や、先頭の*を引用符で囲んでいない場合、ワークフローは無効になります。cronビルダーとYAMLチェッカーで確認してください。
  4. 最小間隔。最短の間隔は5分に1回です。
  5. 負荷による遅延。負荷が高いと、特に毎時の開始時刻に実行が遅れたり欠落したりすることがあります。17のような奇数の分を使ってください。
  6. Actionsまたはワークフローが無効になっている。特にフォークでは、有効にするまでスケジュールワークフローはオフのままです。
  7. UTCの混同。実行は、現地時間ではなくUTCの時刻に行われていた可能性があります。

変更後にGitHub Actionsのスケジュールが動かない

cron行の編集は、マージafter後にデフォルトブランチから反映され、次の実行は新しい式に従います。待たずにジョブ本体をテストできるように、workflow_dispatch:を追加してください。

よくある間違い

ミス結果対処
引用符なしの/5 * * *YAMLの解析エラー文字列を引用符で囲む
現地時間だと思い込む実行時刻が数時間ずれ、夏時間で変動するUTCに変換
0 0 31 * *31日ある月にのみ実行されます0 0 1 * * を使うか、ジョブ内で月末日を計算してください
日付と曜日の両方が指定されています両者はANDではなくOR条件で組み合わされます(POSIXの動作)どちらか一方だけを指定し、もう一方はジョブ内で確認してください
フィーチャーブランチでのテストスケジュールが一度も実行されませんデフォルトブランチにマージするか、workflow_dispatch を使用してください
毎時0分に実行される重いジョブ開始の遅延とリソースの急増奇数の分を使用してください
concurrencyの設定を忘れる実行に時間がかかると並行実行が重なるグループを指定して concurrency を追加してください

実行が遅くても次の実行と重ならないよう、concurrencyグループを追加してください:

concurrency:
  group: nightly-report
  cancel-in-progress: false

スケジュールのコスト

スケジュール実行も、失敗した実行を含め、他の実行と同様に課金されます。15分ごとに実行される5分のジョブは、Linuxで月480分の課金となり、$0.006/分で約$2.88になります。多数のリポジトリにまたがると、この額は積み重なります。何かをポーリングするcronジョブは、多くの場合イベントトリガー(push、release、repository_dispatch、Webhook)に置き換えられます。また timeout-minutes を使用し、軽量な事前チェックを先頭に置いて、処理対象がない場合はジョブが数秒で終了するようにしてください。GitHub Actionsの料金を抑える方法を参照し、Actionsコスト計算ツールで利用量を見積もってください。

スケジュールの適切な使い方

  • 夜間の完全なテスト実行や不安定なテストの調査(不安定なテストへの対処を参照)。
  • 依存関係とセキュリティのスキャン。
  • デフォルトブランチ向けのキャッシュ準備。PRがウォームなキャッシュから始まるようにします(キャッシュのガイド)。
  • 古いIssueの整理とレポートの生成。

よくある質問

自分のタイムゾーンでスケジュールを設定できますか?

GitHubは、スケジュールエントリにIANAゾーン名を指定する任意の timezone フィールドを文書化していますが、ご利用のプランで現在のドキュメントを確認してください。指定しない場合は、UTCに変換するか、上記のように2つのUTC時刻を設定してローカル時刻で条件分岐させてください。

GitHub Actionsのスケジュールが実行されないのはなぜですか?

多くの場合、ワークフローがデフォルトブランチにないか、リポジトリが60日間非アクティブだったか(公開リポジトリの場合)、YAMLが無効か、または負荷により実行が遅延しています。上記のチェックリストを参照してください。

GitHub Actionsのスケジュールが時々しか動作しないのはなぜですか?

GitHubは、特に毎時の開始時点では、高負荷時にスケジュールイベントが遅延または欠落する可能性があると警告しています。負荷の少ない分に変更し、遅延や欠落した実行にも耐えられるようジョブを設計してください。

スケジュールの実行が遅れたり、実行がスキップされたりしたのはなぜですか?

GitHubは、特に毎時の開始時点では、負荷によりスケジュール実行が遅れる可能性があると警告しています。負荷の少ない分を使用し、遅延を許容する設計にしてください。

1つのワークフローに複数のスケジュールを設定できますか?

はい、複数の cron エントリを列挙できます。どのスケジュールで起動したかを判別するには github.event.schedule を使用してください。

同じワークフローを手動で実行するにはどうすればよいですか?

workflow_dispatch: を追加し、Actionsタブの「Run workflow」または gh workflow run を使用してください。

試してみる

無料の cronビルダー を使えば、コミット前に次の実行時刻を確認できます。スケジュールされたジョブが重い場合、compiler.devの比較モードで、同じ夜間ジョブを高速なランナーで実行した場合のコストを確認できます。

このワークフローを compiler.dev で実行する カード登録不要 · 200 無料分

無料で試す