Back to Details

crontap-replace-github-actions-cron

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Replace GitHub Actions cron

替换 GitHub Actions cron

Crontap sends a repository dispatch request. GitHub still runs the workflow.
Crontap 会发送 repository dispatch 请求，GitHub 仍会运行 workflow。

Prerequisites

前置条件

Before using the required tools, check whether they are available. If any are missing, stop and offer the user exactly two choices:
  1. Connect Crontap MCP at 
    https://mcp.crontap.com/mcp
    . MCP access works on every Crontap tier.
  2. Configure 
    $CRONTAP_CLIENT_ID
    and 
    $CRONTAP_API_KEY
    for the raw API. Raw API access requires Ultra.
Do not silently choose a path or continue until the user selects one.
  • Make the workflow safe to dispatch more than once.
  • Create a fine-grained GitHub token restricted to the target repository with the permission required by the repository dispatch endpoint.
  • Store the token in a secure store and plan its expiration and rotation.
  • Confirm the desired IANA timezone.
在使用所需工具之前，先检查它们是否可用。如果缺少任何工具，请停止操作，并向用户提供恰好两个选项：
  1. 连接 Crontap MCP，地址为 
    https://mcp.crontap.com/mcp
    。所有 Crontap 套餐均支持 MCP 访问。
  2. 配置 
    $CRONTAP_CLIENT_ID
    和 
    $CRONTAP_API_KEY
    以使用 raw API。raw API 访问需要 Ultra 套餐。
在用户选择其中一种之前，不要擅自选择方案或继续操作。
  • 确保 workflow 能够安全地被多次 dispatch。
  • 创建一个 fine-grained GitHub token，仅限于目标仓库，并授予 repository dispatch endpoint 所需的权限。
  • 将 token 存放在安全存储中，并规划其过期和轮换机制。
  • 确认所需的 IANA 时区。

Change the workflow

修改 workflow

Replace the scheduled trigger with manual and repository dispatch triggers:
yaml
on:
  workflow_dispatch:
  repository_dispatch:
    types: [scheduled-run]
Keep 
workflow_dispatch
for manual operation. Crontap calls 
repository_dispatch
. Do not leave 
on.schedule
enabled after cutover.
将 schedule 触发器替换为手动触发和 repository dispatch 触发器：
yaml
on:
  workflow_dispatch:
  repository_dispatch:
    types: [scheduled-run]
保留 
workflow_dispatch
以供手动操作。Crontap 会调用 
repository_dispatch
。切换完成后，不要让 
on.schedule
保持启用状态。

Workflow

执行流程

  1. Commit and deploy the dispatch-capable workflow.
  2. Test a repository dispatch with a non-production-safe workflow path.
  3. Remove the old 
    schedule
    trigger at the agreed cutover time.
  4. Create the Crontap schedule.
  5. Verify GitHub returns 204 and one workflow run appears.
  6. Pause the Crontap schedule during maintenance or rollback.
  1. 提交并部署支持 dispatch 的 workflow。
  2. 使用适合非生产环境的 workflow 路径测试 repository dispatch。
  3. 在约定的切换时间移除旧的 
    schedule
    触发器。
  4. 创建 Crontap schedule。
  5. 验证 GitHub 返回 204，并且出现一次 workflow run。
  6. 在维护或回滚期间暂停 Crontap schedule。

MCP examples

MCP 示例

Create the external dispatch:
json
{
  "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"
  }
}
Pause:
json
{
  "tool": "pause_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
Resume:
json
{
  "tool": "resume_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
创建外部 dispatch：
json
{
  "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"
  }
}
暂停：
json
{
  "tool": "pause_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
恢复：
json
{
  "tool": "resume_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}

REST fallback

REST 回退方案

REST creation requires Ultra API access:
bash
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"
  }'
通过 REST 创建需要 Ultra API 访问权限：
bash
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"
  }'

Verification

验证

  • Confirm the deployed workflow no longer contains 
    on.schedule
    .
  • Confirm 
    event_type
    matches the workflow's dispatch type exactly.
  • Verify one Crontap run corresponds to one GitHub workflow run.
  • Confirm a non-expired token is scoped only to the required repository and operation.
  • 确认已部署的 workflow 不再包含 
    on.schedule
    。
  • 确认 
    event_type
    与 workflow 的 dispatch type 完全匹配。
  • 验证一次 Crontap run 对应一次 GitHub workflow run。
  • 确认未过期 token 的作用域仅限所需仓库和操作。

Safety and plan limits

安全与套餐限制

  • Never use a broad classic token when a restricted fine-grained token works.
  • Avoid top-of-hour assumptions when comparing old GitHub timing evidence.
  • Make downstream workflow writes idempotent.
  • If the Crontap create call hits a cap or cadence floor, present the returned four-option ladder and smallest viable option.
  • 如果受限 fine-grained token 可用，绝不要使用权限范围过大的 classic token。
  • 对比旧的 GitHub 计时证据时，不要假定任务一定在整点运行。
  • 确保下游 workflow 写入具备幂等性。
  • 如果 Crontap 创建调用触及配额上限或执行频率下限，请展示返回的四选项阶梯以及最小可行选项。

Troubleshooting

故障排除

  • GitHub 401 means the token is invalid or expired.
  • GitHub 403 usually means repository access or permissions are insufficient.
  • GitHub 404 can intentionally hide a repository the token cannot access.
  • GitHub 422 often means the event type or request body is invalid.
  • Duplicate runs usually mean both the old schedule trigger and Crontap remain active.
  • GitHub 401 表示 token 无效或已过期。
  • GitHub 403 通常表示仓库访问权或权限不足。
  • GitHub 404 可能是有意隐藏 token 无法访问的仓库。
  • GitHub 422 通常表示 event type 或请求体无效。
  • 出现重复 run 通常意味着旧的 schedule 触发器和 Crontap 仍同时处于启用状态。

References

参考