crontap-replace-github-actions-cron

GitHub Actions cron を置き換える

Crontap はリポジトリディスパッチリクエストを送信します。ワークフローの実行は引き続き GitHub が担います。

前提条件

必要なツールを使用する前に、利用可能かどうかを確認してください。いずれかが利用できない場合は、作業を中止し、ユーザーに次の2つの選択肢をそのまま提示してください。

1. Crontap MCP を https://mcp.crontap.com/mcp で接続する。MCP のアクセスはすべての Crontap プランで利用できます。
2. 生 API を利用するために $CRONTAP_CLIENT_ID と $CRONTAP_API_KEY を設定する。生 API のアクセスには Ultra が必要です。

ユーザーが選択するまで、どちらかを勝手に選んだり、作業を続けたりしないでください。

• ワークフローを複数回ディスパッチしても安全な状態にします。
• 対象リポジトリに制限し、リポジトリディスパッチエンドポイントに必要な権限を付与したファイングレイン PAT を作成します。
• トークンを安全なストアに保存し、有効期限とローテーションを計画します。
• 希望する IANA タイムゾーンを確認します。

ワークフローを変更する

スケジュール済みトリガーを、手動トリガーとリポジトリディスパッチトリガーに置き換えます。

on:
  workflow_dispatch:
  repository_dispatch:
    types: [scheduled-run]

手動実行のために workflow_dispatch は残します。Crontap は repository_dispatch を呼び出します。切り替え後は on.schedule を有効なまま残さないでください。

ワークフロー

1. ディスパッチに対応したワークフローをコミットしてデプロイします。
2. 本番環境で安全でないワークフローのパスを使って、リポジトリディスパッチをテストします。
3. 合意した切り替え時刻に、以前の schedule トリガーを削除します。
4. Crontap のスケジュールを作成します。
5. GitHub が 204 を返し、ワークフローの実行が1件開始されることを確認します。
6. メンテナンス時またはロールバック時は、Crontap のスケジュールを一時停止します。

MCP の例

外部ディスパッチを作成します。

{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://api.github.com/repos/example-org/example-repo/dispatches",
    "text": "every weekday at 09:00",
    "timezone": "Europe/London",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <fine-grained-token-from-secure-store>",
      "Accept": "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      "Content-Type": "application/json"
    },
    "body": {
      "event_type": "scheduled-run"
    },
    "label": "GitHub scheduled run"
  }
}

一時停止：

{
  "tool": "pause_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}

再開：

{
  "tool": "resume_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}

REST の代替手段

REST による作成には Ultra API アクセスが必要です。

curl --fail-with-body https://api.crontap.com/v1/schedule \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://api.github.com/repos/example-org/example-repo/dispatches",
    "interval": "0 9 * * 1-5",
    "timezone": "Europe/London",
    "verb": "POST",
    "headers": {
      "Authorization": "Bearer <fine-grained-token-from-secure-store>",
      "Accept": "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      "Content-Type": "application/json"
    },
    "data": {"event_type": "scheduled-run"},
    "label": "GitHub scheduled run"
  }'

検証

• デプロイ済みのワークフローに on.schedule が含まれていないことを確認します。
• event_type がワークフローのディスパッチタイプと完全に一致することを確認します。
• Crontap の1回の実行につき、GitHub ワークフローの実行が1回対応していることを確認します。
• 有効期限が切れていないトークンのスコープが、必要なリポジトリと操作だけに限定されていることを確認します。

安全性とプランの制限

• 制限付きのファイングレイン PAT が使える場合は、広範な権限を持つクラシックトークンを決して使用しないでください。
• GitHub の以前の実行タイミングの証跡と比較するとき、時刻が正時であることを前提にしないでください。
• 下流のワークフローによる書き込みを冪等にします。
• Crontap の作成呼び出しが上限または実行間隔の下限に達した場合は、返された4つの選択肢と、実行可能な最小の選択肢を提示してください。

トラブルシューティング

• GitHub 401 は、トークンが無効または期限切れであることを意味します。
• GitHub 403 は通常、リポジトリへのアクセスまたは権限が不足していることを意味します。
• GitHub 404 は、トークンでアクセスできないリポジトリを意図的に隠している場合があります。
• GitHub 422 は、多くの場合、イベントタイプまたはリクエストボディが無効であることを意味します。
• 実行が重複する場合、通常は以前のスケジュールトリガーと Crontap の両方が有効なままになっています。

参考資料

• Crontap エージェントスキルのカタログ
• GitHub Actions cron のずれ
• Crontap と GitHub Actions cron の比較
• GitHub リポジトリディスパッチ API
• cron のトラブルシューティング