CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载状态徽章Status Badge是 Woodpecker CI/CD 内置的仓库状态展示能力可通过一个 SVG 图片端点把默认分支上最近一次流水线的构建结果直接嵌入到网站首页或项目 README 中。本文将以 80-badges.md 为主线结合 server/api/badge.go、server/badges/badges.go 等源码完整讲解徽章端点的 URL 结构、branch/events/workflow/step等查询参数、状态与颜色映射规则以及后端从取数到渲染 SVG 的完整调用链帮助你快速把 Woodpecker 流水线状态接入任何外部页面。什么是状态徽章Woodpecker 为每个仓库内置了状态徽章status badge支持。徽章本质上是一张由服务端动态生成的 SVG 图片展示仓库代码的流水线构建状态可以方便地嵌入到你的网站或项目 README 文件中。与直接查看 Web UI 相比徽章是一种轻量、可分享、可嵌入的实时状态展示方式非常适合开源项目首页、文档站点或团队内部看板。徽章由服务端渲染并即时返回其内容始终反映当前仓库最近一次流水线的真实结果而不是一张静态图片因此无需手动更新。徽章端点Badge Endpoint状态徽章的访问端点为scheme://hostname/api/badges/repo-id/status.svg其中scheme与hostname是你部署的 Woodpecker 服务地址repo-id是仓库在 Woodpecker 中的数字 ID。例如如果你的服务部署在https://ci.example.com仓库 ID 为42则徽章 URL 为https://ci.example.com/api/badges/42/status.svg在 README 中通常这样嵌入值得注意的是路由的实际注册方式支持两种形式。从 server/router/api.go 可以看到徽章端点同时注册了按仓库 ID 和按「所有者 仓库名」两种路径badges : apiBase.Group(/badges/:repo_id_or_owner) { badges.GET(/status.svg, api.GetBadge) badges.GET(/cc.xml, api.GetCC) } _badges : apiBase.Group(/badges/:repo_id_or_owner/:repo_name) { _badges.GET(/status.svg, api.GetBadge) _badges.GET(/cc.xml, api.GetCC) }对应到 server/api/badge.go 中的处理逻辑如果 URL 中带有repo_name参数则按owner/repo名称查询仓库否则将repo_id_or_owner解析为数字仓库 ID。也就是说除了数字 ID你也可以用可读的仓库名形式scheme://hostname/api/badges/owner/repo/status.svg例如https://ci.example.com/api/badges/woodpecker-ci/woodpecker/status.svg。需要提醒的是数字 ID 形式要求传入合法整数否则接口会直接返回400 Bad Request。指定分支branch 参数状态徽章默认展示默认分支例如main上最近一次构建的状态。你可以在查询字符串中追加branch参数来指定其他分支-scheme://hostname/api/badges/repo-id/status.svg scheme://hostname/api/badges/repo-id/status.svg?branchbranch例如展示develop分支的状态https://ci.example.com/api/badges/42/status.svg?branchdevelop从源码看branch参数的默认值取自仓库配置的默认分支。在 server/api/badge.go 中branch : c.Query(branch) if len(branch) 0 { branch repo.Branch }也就是说显式传入branch时使用传入值否则回退到仓库的默认分支。查询底层落在 server/store/datastore/pipeline.go 的GetPipelineBadgefunc (s storage) GetPipelineBadge(repo *model.Repo, branch string, events []model.WebhookEvent) (*model.Pipeline, error) { pipeline : new(model.Pipeline) return pipeline, wrapGet(s.engine. Desc(number). Where(builder.Eq{repo_id: repo.ID, branch: branch}). Where(builder.In(event, events)). Where(builder.Neq{status: model.StatusBlocked}). Get(pipeline)) }可见徽章取的是该分支上number最大的流水线同时要求其事件类型在指定集合内、且状态不是blocked例如因审批门控被阻塞的流水线不会被计入。限定事件类型events 参数默认情况下状态徽章不包含拉取请求pull request的结果因为 PR 的构建状态并不能准确代表仓库主干代码的真实状态。默认徽章只反映最近一次push 事件的状态。如果你希望纳入其他或更多事件类型可以追加events查询参数多个事件用逗号分隔-scheme://hostname/api/badges/repo-id/status.svg scheme://hostname/api/badges/repo-id/status.svg?eventsmanual,cron例如同时统计push、tag与manual事件https://ci.example.com/api/badges/42/status.svg?eventspush,tag,manualevents参数可用的合法取值定义在 server/model/const.go 中完整枚举如下事件值含义push代码推送默认pull_request拉取请求pull_request_closed拉取请求关闭pull_request_metadata拉取请求元数据变更tag标签推送release发布deployment部署cron定时任务触发manual手动触发在 server/api/badge.go 中未传events时默认使用push传入了则按逗号切分并逐一对事件值调用Validate()校验遇到非法值会返回400 Bad Requestvar events []model.WebhookEvent eventsQuery : c.Query(events) // If none given, fallback to default push if len(eventsQuery) 0 { events []model.WebhookEvent{model.EventPush} } else { strEvents : strings.Split(eventsQuery, ,) events make([]model.WebhookEvent, len(strEvents)) for i, strEvent : range strEvents { event : model.WebhookEvent(strEvent) if err : event.Validate(); err nil { events[i] event } else { _ c.AbortWithError(http.StatusBadRequest, err) return } } }更细粒度workflow 与 step 参数除了文档中提到的branch与eventsserver/api/badge.go 还支持按工作流workflow甚至按具体步骤step生成徽章这在多工作流配置中非常实用workflowname徽章只统计指定工作流的运行状态文案subject从默认的pipeline变为工作流名称在指定workflow的基础上追加stepname文案变为workflow: step只反映该步骤的状态。实现上GetBadge会先取出该流水线的完整工作流树WorkflowGetTree再按名称匹配工作流及其子步骤并将多个匹配结果通过pipeline.MergeStatusValues合并成一个聚合状态。多工作流配置的写法可参考 25-workflows.md。状态标签与颜色映射徽章右侧的状态文案与颜色由 server/badges/badges.go 中的getBadgeStatusLabelAndColor决定流水线状态徽章文案徽章颜色successsuccess绿色#44cc11failurefailure红色#e05d44pending/runningstarted黄色#dfb317error/killederror灰色#9f9f9f其他 / 无记录none灰色#9f9f9f值得注意的细节是当仓库里查不到符合条件的流水线时徽章不会报错而是显示灰色的none。这一点在 server/api/badge.go 中有明确注释“display the none badge, instead of throwing an error response”且ErrRecordNotExist之外的查询错误只会被记录日志而不会导致 5xx。后端渲染链路从请求到 SVG一次徽章请求的完整链路如下路由匹配/api/badges/:repo_id_or_owner[/:repo_name]/status.svg命中api.GetBadge见 server/router/api.go仓库解析按 ID 或owner/repo名称加载仓库server/api/badge.go参数归一解析branch、events必要时解析workflow、step取最新流水线GetPipelineBadge按repo_id、branch、事件集合查询number最大的流水线server/store/datastore/pipeline.go生成 SVGbadges.Generate(name, status)根据状态映射文案与颜色调用RenderBytes渲染出 SVGserver/badges/badges.go返回响应响应头设置为Content-Type: image/svgxml返回 200 与 SVG 内容server/api/badge.go。SVG 的绘制实现在 server/badges/drawer.go 中它使用内置的DejaVuSans字体测量文案宽度字号 11、DPI 72再通过 HTML 模板flat 风格、圆角矩形、平滑渐变拼出最终的扁平徽章字体资源内嵌在 server/badges/fonts 目录中因此徽章服务不依赖外部字体或图片资源。由于渲染器内部使用互斥锁与sync.Once单例初始化drawer.go并发请求下依然线程安全。验证与测试仓库自带一组徽章渲染的单元测试位于 server/badges/badges_test.go其中TestGenerate覆盖了success、failure、error、killed、pending、running及未知状态共 7 种场景并逐字节断言生成的 SVG 与预期一致TestBadgeDrawerRender则验证了文案宽度测量与模板渲染的坐标计算结果。你也可以直接通过命令行验证徽章端点的实际输出curl -s https://hostname/api/badges/repo-id/status.svg?branchmain返回的即是一段image/svgxml文本。若返回的 XML 中状态为none说明该分支上还没有符合条件的流水线记录。延伸CCMenu 徽章cc.xml除status.svg外server/router/api.go 还注册了/api/badges/repo_id/cc.xml端点对应 server/api/badge.go 中的GetCC。它按 CCTray v1 规范输出 XML 格式的流水线状态供 macOS 菜单栏工具 CCMenu 订阅展示。虽然本文档未展开讲解但它与状态徽章共用同一批路由与仓库解析逻辑可作为需要桌面端状态通知时的补充方案。小结Woodpecker 的状态徽章开箱即用、无需额外配置只需拼接/api/badges/repo-id/status.svg即可嵌入任意页面。核心要点可归纳为默认展示默认分支最近一次 push 事件的流水线状态用?branch切换分支用?events纳入更多事件类型如manual、cron、tag进阶可用?workflow与?step做更细粒度的状态展示无记录时优雅降级为灰色none不会破坏页面布局整个功能由 server/api/badge.go → server/store/datastore/pipeline.go → server/badges 三段代码协同完成状态映射与 SVG 渲染均有测试用例可查。将徽章放入 README 的第一屏或嵌入团队文档站点即可让所有访问者一眼看到主干代码的最新构建健康状况。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 仓库状态徽章Status Badges完全指南端点、参数与 SVG 渲染原理Woodpecker 仓库状态徽章Status Badges完全指南端点、参数与 SVG 渲染原理 Woodpecker 内置了仓库状态徽章StatusCI/CDDevOpsWoodpecker 状态徽章Status Badges使用指南端点、查询参数与源码级原理Woodpecker 状态徽章Status Badges使用指南端点、查询参数与源码级原理 Woodpecker CI/CD 引擎内置了对仓库状态徽章SCI/CDDevOps3 步跑通 browser-use 自动下载让 AI 替你批量保存网页文件的完整指南3 步跑通 browser use 自动下载让 AI 替你批量保存网页文件的完整指南 周一早上九点你要从三个平台后台各导一份上月流水老规矩打开页面、找按人工智能AI Agent浏览器控制GUI 自动化MCP 服务上一篇AWS CLI 实战用 describe-alarms-for-metric 按指标精准查询 CloudWatch 告警下一篇RuboCop v0.52.1 发布说明源码级解读25 项缺陷修复与 4 项行为变更全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考