Woodpecker 定时任务（Cron）配置指南：从 pipeline 事件过滤到定时调度实战

CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Cron 定时任务是 Woodpecker CI/CD 中实现周期化自动构建的核心机制它允许你按预定义的时间表如每天、每 5 分钟自动触发 pipeline而无需任何代码提交。本文以 Woodpecker 官方文档 为主体结合仓库源码调度器、API、配置解析与 CLI 实现完整讲解定时任务的配置流程、调度语法、事件过滤、权限要求与底层工作原理读完即可在自己的仓库中落地一套可用的定时流水线。前置要求谁能配置定时任务在开始之前需要明确一个权限门槛配置 Cron 任务要求你对该仓库至少拥有 push推送权限。这是因为定时任务本质上是一种按时间触发的特殊 pipeline 事件涉及仓库级别的运行策略设置普通只读协作者无法修改。从仓库源码可以印证这一点——Cron 的创建与修改均通过仓库设置类 API 完成服务端在处理请求时会通过session.Repo(c)校验当前会话用户对目标仓库的权限见 server/api/cron.go 中的PostCron、PatchCron处理器权限不足的请求会被会话中间件直接拦截。第一步在 pipeline 配置中添加事件过滤创建定时任务的第一步是修改你的 pipeline 配置文件如.woodpecker.yml让相关步骤在cron事件下才会被执行。Woodpecker 的配置使用when约束constraint机制来声明步骤的运行条件。官方文档给出的示例是为一个原本只由其他事件触发的步骤追加event: cron过滤条件steps: - name: sync_locales image: weblate_sync settings: url: example.com token: from_secret: weblate_token when: event: cron # 仅由定时任务触发时执行 cron: name of the cron job # 可选只由指定名称的 cron job 触发这段配置的含义是when.event: cron该步骤只在事件类型为cron时运行when.cron: name of the cron job可选的进一步过滤——只有当触发这次 pipeline 的定时任务名称匹配时步骤才会执行。如果不写这一行那么所有cron 事件触发时该步骤都会运行。事件过滤的底层实现在源码层面cron被定义为一种独立的 Webhook 事件类型。在 server/model/const.go 中可以看到EventCron WebhookEvent cron它与其他事件push、pull_request、tag、deployment等一起被Validate()校验是合法的 pipeline 事件之一。事件与 cron 名称的双重匹配逻辑实现在 pipeline/frontend/yaml/constraint/constraint.go 中当元数据中的事件为EventCron时约束匹配会额外校验当前 pipeline 的 Cron 名称是否命中cron约束列表对应源码第 192-193 行if m.Curr.Event metadata.EventCron { match match c.Cron.Match(m.Curr.Cron) }也就是说Woodpecker 在解析 pipeline 配置时会把你写在when.cron里的名称列表与本次触发 pipeline 的 Cron 任务名做精确匹配两者同时满足步骤才会进入执行队列。仓库中对应的测试用例见 pipeline/frontend/yaml/constraint/constraint_test.go也验证了事件为 cron、名称匹配/不匹配两种场景下的命中结果。提示如果你希望定时任务只跑部分步骤就用when.cron按名称精确圈定如果你希望所有 cron 触发时都跑这些步骤只写when.event: cron即可。第二步在仓库设置中创建定时任务修改完 pipeline 配置并推送到仓库后进入仓库设置页面Repository Settings中的 Cron 区域点击创建新任务填写以下字段名称Name定时任务的名字必须是唯一的且会作为when.cron的匹配依据分支Branch要针对哪个分支的代码执行留空则默认使用仓库的默认分支源码中cron.Branch 时会回退到repo.Branch见 server/cron/cron.go 的CreatePipeline调度表达式Schedulecron 表达式决定触发时间时区Timezone调度表达式解析所基于的时区默认为UTC对应源码中PostCron处理器的默认值赋值逻辑启用开关Enabled控制任务是否参与调度。创建时服务端会做如下校验见 server/model/cron.go 的Validate()名称与调度表达式均不能为空调度表达式必须能被标准 cron 解析器解析时区必须能被 Go 的time.LoadLocation加载。同时如果指定了分支服务端还会调用对应 Forge 的BranchHead接口确认该分支真实存在见 server/api/cron.go 的PostCron。调度语法详解Woodpecker 的调度表达式遵循github.com/gdgvda/cron库的 CRON 表达式格式该格式同时支持标准的 5 字段 cron 表达式与若干扩展标准 5 字段格式分 时 日 月 星期例如30 * * * *表示每小时的第 30 分钟执行一次6 字段格式可带秒秒 分 时 日 月 星期描述符Descriptorsdaily、hourly、weekly、monthly、yearly等例如daily表示每天零点执行间隔Intervalsevery duration例如every 5m表示每 5 分钟执行一次这是定时测试、缓存刷新类任务最常用的写法。官方文档给出的示例every 5m # 每 5 分钟 daily # 每天 30 * * * * # 每小时的第 30 分钟如果需要系统学习 cron 语法本身而不只是 Woodpecker 的封装可以借助在线的 crontab 生成器工具进行实验调试。调度时间的计算与更新每个定时任务在数据库中都会维护一个NextExec字段下一次执行时间戳。创建、修改调度表达式、切换时区或重新启用任务时服务端都会调用CalcNewNext实现在 server/cron/cron.go重新计算下一次执行时间func CalcNewNext(schedule, tzLoc string, now time.Time) (time.Time, error) { zone, err : time.LoadLocation(tzLoc) ... c, err : parser.Parse(schedule) ... next : c.Next(now) ... }从实现可以看到计算是基于当前时刻推算下一个未来执行点c.Next(now)如果表达式在指定时区下没有任何未来执行时间会返回明确的错误——这也解释了为什么创建任务时必须保证表达式合法。第三步调度器如何触发 pipeline运行原理创建好定时任务后服务端的调度循环会负责按时触发。调度器实现在 server/cron/cron.go 的Run函数中运行机制如下轮询检查调度器每1 分钟常量checkTime time.Minute向数据库查询一次已到执行时间的定时任务每次最多取 10 条常量checkItems 10加锁防重对每个到期的任务调用CronGetLock获取分布式锁并将新的NextExec写入数据库——如果锁已被其他实例获取则本次跳过从而保证在多副本部署时同一任务不会重复执行创建 pipeline调用CreatePipeline读取仓库与 Forge 信息刷新用户令牌后获取指定分支的最新 commitBranchHead据此构造一个Event: EventCron的 pipeline相关字段见 server/model/pipeline.go入队执行将 pipeline 交给pipeline.Create创建并进入调度队列随后按普通 pipeline 流程分发到 Agent 执行。值得注意的细节定时任务触发的 pipeline 会携带Cron字段任务名称以及AdditionalVariables任务附加变量见下文这正是步骤级when.cron过滤和变量注入能够生效的数据来源。手动触发与附加变量除了等待调度器自动触发你还可以在界面或通过 API立即手动运行某个定时任务对应POST /repos/{repo_id}/cron/{cron}处理器为 server/api/cron.go 中的RunCron。它会跳过调度等待直接基于当前分支头部分支创建并执行一次 cron 事件 pipeline——适合改了配置想立刻验证的场景。另外Cron 模型还支持Variables map[string]string字段见 server/model/cron.go你可以为定时任务附加自定义变量这些变量会作为AdditionalVariables注入到 pipeline 中供步骤内的环境变量/设置使用实现同一个 pipeline 配置、不同定时参数的复用。使用 CLI 管理定时任务除了 Web 界面Woodpecker CLI 也提供了完整的 Cron 管理命令源码位于 cli/repo/cron。常用操作如下列出仓库的定时任务需要仓库 ID 或完整名称作为参数woodpecker-cli cron ls repo-id|repo-full-name输出默认使用模板展示任务 ID、名称、分支、调度表达式与下一次执行时间模板定义见 cli/repo/cron/cron_list.go。添加定时任务woodpecker-cli cron add repo-id|repo-full-name \ --name cron-name \ --schedule daily \ --branch main \ --enabled其中--name与--schedule为必填参数--branch指定执行分支--enabled控制是否启用默认启用参数定义见 cli/repo/cron/cron_add.go。其他管理命令cron update修改名称、调度、分支、启用状态、cron show查看单个任务详情、cron rm删除任务分别对应 cli/repo/cron/cron_update.go、cli/repo/cron/cron_show.go、cli/repo/cron/cron_rm.go。说明CLI 通过 woodpecker-go 客户端调用服务端 REST API/repos/{repo_id}/cron系列接口因此以上命令与 Web 界面操作完全等价适合脚本化运维。常见使用场景与建议基于上述机制Cron 定时任务在 Woodpecker 中常见的落地场景包括定时数据同步/导入导出如文档开头的sync_locales示例每天定时从上游同步翻译文案定时测试与巡检every 5m或hourly对主干分支跑冒烟测试、健康检查定时依赖升级/缓存刷新利用daily、weekly等描述符定期重建镜像或刷新缓存多任务分流通过when.cron名称过滤让不同定时任务各跑各自专属的步骤集合。配置时建议注意以下几点分支留空时任务会跟随仓库默认分支的最新提交执行若想固定某个发布分支请显式指定branch调度表达式建议先在本地/在线工具中验证正确性创建时服务端虽会校验语法但不会校验业务语义如凌晨跑是否是你想要的时刻时区默认是 UTC国内时间场景下记得显式设置时区如Asia/Shanghai否则每天执行的实际时刻会与预期相差 8 小时修改 pipeline 配置后需要让when.event: cron的步骤真正在配置解析阶段生效配置推送后定时任务才会按新规则执行。小结本文围绕 Woodpecker 官方 Cron 文档 展开完整覆盖了从pipeline 配置事件过滤 → 仓库设置创建任务 → 调度器自动触发的全链路when.event: cron与when.cron双条件过滤决定了哪些步骤在定时触发时执行every 5m、daily、30 * * * *等表达式由 gdgvda/cron 解析器驱动调度器每分钟轮询、加锁防重并基于分支最新 commit 创建 cron 事件 pipeline。配合 Web 界面、REST API 与 CLI 三种管理入口你可以在保持 push 权限的前提下快速搭建稳定可靠的定时 CI 流水线。如需深入源码可从 server/cron/cron.go调度循环、server/model/cron.go数据模型与校验、server/api/cron.goREST API与 pipeline/frontend/yaml/constraint/constraint.go事件/名称过滤四个文件继续阅读。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker CI/CD 定时任务Cron完整配置指南从事件过滤到调度原理Woodpecker CI/CD 定时任务Cron完整配置指南从事件过滤到调度原理 Woodpecker 内置了与 CI 流水线深度集成的定时任务CroCI/CDDevOpsFlashMLA深度解析突破性大模型注意力计算优化技术实现原理FlashMLA深度解析突破性大模型注意力计算优化技术实现原理 FlashMLA是DeepSeek团队开发的高性能注意力计算内核库为DeepSeek V3系算子库大模型Enable Screenshot vs 同类工具为什么它是最佳选择Enable Screenshot vs 同类工具为什么它是最佳选择 在数字生活中我们经常遇到无法截图的场景——银行APP的支付界面、视频平台的版权内容、移动开发上一篇网盘直链下载助手2025八大主流网盘高速下载终极解决方案下一篇LinkSwift专业级网盘直链解析工具完整技术指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考