CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Woodpecker 是一个简单而强大的 CI/CD 引擎其官方 Go 客户端库woodpecker-go位于仓库 woodpecker-go/ 目录下为开发者提供了一套类型安全的 API 封装用于在 Go 应用中查询用户、管理仓库、触发与审批流水线、操作密钥Secrets、镜像仓库Registries、Cron 定时任务以及 Agent 等资源。本文以 woodpecker-go/README.md 的入门示例为主线结合woodpecker-go/woodpecker包源码完整讲解客户端的创建、认证、请求执行原理与全量 API 能力读完后你可以直接在自己的 Go 项目中集成 Woodpecker 服务端接口。一、包结构与导入方式woodpecker-go是一个独立的 Go 模块核心代码位于 woodpecker-go/woodpecker/ 目录包含以下关键文件文件职责client.go客户端核心实现构造器、HTTP 请求辅助函数、日志级别接口interface.goClient接口定义声明全部 API 方法types.go用户、仓库、流水线、Secret、Registry、Cron、Agent 等全部数据类型repo.go仓库、流水线、Secret、Registry、Cron 相关 API 的实现与查询参数编码user.go用户与仓库列表相关 API 的实现pipeline.go流水线队列与元数据接口queue.go队列状态查询接口agent.go、org.go、global_secret.go、global_registry.go其余领域接口list_options.go分页参数ListOptions及查询串编码const.go事件、状态、日志类型、步骤类型等常量httputil/useragent.goUser-Agent 注入的RoundTripper封装client_test.go、repo_test.go 等单元测试验证各 API 的请求路径与解析在 Go 代码中按以下方式导入import ( go.woodpecker-ci.org/woodpecker/v3/woodpecker-go/woodpecker golang.org/x/oauth2 )二、快速开始创建客户端并调用 APIwoodpecker-go/README.md 给出了一个完整的入门示例使用 OAuth2 Token 创建客户端然后查询当前用户与指定仓库信息。import ( go.woodpecker-ci.org/woodpecker/v3/woodpecker-go/woodpecker golang.org/x/oauth2 ) const ( token dummyToken host http://woodpecker.company.tld ) func main() { // create an http client with oauth authentication. config : new(oauth2.Config) authenticator : config.Client( oauth2.NoContext, oauth2.Token{ AccessToken: token, }, ) // create the woodpecker client with authenticator client : woodpecker.NewClient(host, authenticator) // gets the current user user, err : client.Self() fmt.Println(user, err) // gets the named repository information repo, err : client.RepoLookup(woodpecker-ci/woodpecker) fmt.Println(repo, err) }示例要点host是 Woodpecker 服务端地址如http://woodpecker.company.tld末尾的/会被自动去除authenticator是一个携带AccessToken的标准*http.Client所有后续请求的Authorization头都由 OAuth2 机制注入client.Self()返回当前认证用户*Userclient.RepoLookup(owner/name)按完整名称owner/name查找仓库*Repo。两种构造器从 client.go 源码可以看到 SDK 提供了两个构造器// New returns a client at the specified url. func New(uri string) Client { wrappedClient : httputil.WrapClient(http.DefaultClient, go-client) return client{wrappedClient, strings.TrimSuffix(uri, /)} } // NewClient returns a client at the specified url. func NewClient(uri string, cli *http.Client) Client { wrappedClient : httputil.WrapClient(cli, go-client) return client{wrappedClient, strings.TrimSuffix(uri, /)} }woodpecker.New(host)使用http.DefaultClient适合无认证或已在其他环节注入凭证的场景woodpecker.NewClient(host, httpClient)传入自定义*http.Client是 README 示例采用的带 OAuth2 认证的方式也是接入任意认证/中间件如代理、TLS 配置、限流的推荐入口。两者都会调用httputil.WrapClient为客户端注入名为go-client的 User-Agent 标识。从 httputil/useragent.go 的实现看WrapClient会用一个UserAgentRoundTripper包装原有Transport在请求头未设置时补上形如Woodpecker/version (go-client)的 User-AgentuserAgent : fmt.Sprintf(Woodpecker/%s, version.String()) if component ! { userAgent fmt.Sprintf(%s (%s), userAgent, component) }此外客户端还提供SetClient(*http.Client)与SetAddress(string)两个方法可在运行时动态替换 HTTP 客户端或服务端地址见 interface.go。三、底层实现HTTP 请求如何被构造与解析所有 API 最终都汇聚到 client.go 中的do/open两个私有方法理解它们有助于排查认证、参数与错误处理问题。func (c *client) do(rawURL, method string, in, out any) error { body, err : c.open(rawURL, method, in) if err ! nil { return err } defer body.Close() if out ! nil { return json.NewDecoder(body).Decode(out) } return nil } func (c *client) open(rawURL, method string, in any) (io.ReadCloser, error) { uri, err : url.Parse(rawURL) ... req, err : http.NewRequest(method, uri.String(), nil) ... if in ! nil { decoded, decodeErr : json.Marshal(in) ... req.Body io.NopCloser(buf) req.ContentLength int64(len(decoded)) req.Header.Set(Content-Length, strconv.Itoa(len(decoded))) req.Header.Set(Content-Type, application/json) } resp, err : c.client.Do(req) ... if resp.StatusCode http.StatusPartialContent { // 即 206 defer resp.Body.Close() out, _ : io.ReadAll(resp.Body) return nil, ClientError{ StatusCode: resp.StatusCode, Message: string(out), } } return resp.Body, nil }关键行为说明请求序列化传入的in如*RepoPatch、*Secret、*Cron会被json.Marshal序列化为请求体并自动设置Content-Type: application/json与Content-Length响应反序列化out参数接收响应体通过json.NewDecoder(body).Decode(out)直接解码为目标结构体错误处理当服务端返回状态码大于 206即 207 及以上覆盖 3xx/4xx/5xx时SDK 会读取响应体并包装为ClientError{StatusCode, Message}其Error()输出形如client error 404: body便于定位失败原因查询参数各类 Options 通过各自的QueryEncode()或getURLQuery()生成查询串。分页参数Page/PerPage在 list_options.go 中被编码为page与perPage且仅在大于 0 时才会加入查询串。四、客户端 API 全景按领域划分的能力清单interface.go 中的Client接口是 SDK 的功能地图几乎所有管理操作都能通过它完成。4.1 用户与认证user.goSelf() (*User, error)返回当前认证用户对应GET /api/user即 README 示例中的第一个调用User(login string, forgeID ...int64)/UserDel(login, forgeID ...int64)按登录名查询或删除用户。forgeID为可选参数缺省时使用常量defaultForgeID 1见 const.goUserList(opt UserListOptions)分页列出全部注册用户管理员接口UserPost(*User)/UserPatch(*User)创建/更新用户账号UserPatch在ForgeID 1时也会自动回退到默认forgeID。4.2 仓库管理repo.goRepo(repoID int64)按 ID 获取仓库RepoLookup(fullName)按owner/name获取仓库README 示例中的第二个调用RepoList(opt RepoListOptions)列出当前用户有权访问的仓库RepoListOptions{All: true}可额外包含未激活仓库RepoPost(opt RepoPostOptions)激活仓库ForgeRemoteID必填编码为forge_remote_id查询参数RepoPatch(repoID, *RepoPatch)更新仓库配置见下文 4.5RepoMove(repoID, RepoMoveOptions{To})迁移仓库到新路径RepoChown(repoID)/RepoRepair(repoID)/RepoDel(repoID)转移所有权、修复 Webhook、删除仓库。4.3 流水线Pipeline生命周期查询Pipeline(repoID, num)按编号获取PipelineList(repoID, PipelineListOptions)分页列出PipelineLast(repoID, PipelineLastOptions)获取最近一次流水线branch可指定分支留空使用默认分支PipelineQueue()返回队列中的流水线 Feed见 pipeline.go操作PipelineCreate(repoID, *PipelineOptions)手动触发可携带Branch与VariablesPipelineStart(repoID, num, PipelineStartOptions{Params})重启PipelineStop(repoID, num)取消PipelineDelete(repoID, num)删除审批PipelineApprove(repoID, num)与PipelineDecline(repoID, num)用于处理需要人工审批gated的流水线部署Deploy(repoID, num, DeployOptions{DeployTo, Params})触发部署事件QueryEncode()会自动追加eventdeployment查询参数见 repo.go 中DeployOptions.QueryEncode日志与元数据StepLogEntries(repoID, pipeline, stepID)读取指定 Step 的日志条目LogsPurge/StepLogsPurge清理日志PipelineMetadata(repoID, pipelineNumber)返回元数据原始字节由 pipeline.go 实现直接读取响应体而不做 JSON 解码。其中PipelineListOptions支持相当丰富的过滤条件QueryEncode()的实现位于 repo.go字段查询参数说明Page/PerPagepage/perPage分页控制Before/Afterbefore/after时间范围按 RFC3339 格式化Branchbranch按分支过滤Eventsevent事件类型逗号分隔多个值RefContainsref按引用ref包含关系过滤Statusstatus按状态过滤如success、failure事件与状态常量定义在 const.go事件包括push、pull_request、tag、release、deployment、cron、manual等状态包括blocked、skipped、pending、running、success、failure、killed、error。4.4 密钥、镜像仓库与 CronSecret密钥Secret*系列方法按仓库维度管理如Secret(repoID, name)、SecretList、SecretCreate、SecretUpdate、SecretDeleteSecret结构体见 types.go包含Name、Value、Images允许使用的镜像白名单、Events、Note等字段Registry镜像仓库凭据Registry*系列按仓库管理 Docker 镜像仓库账号密码Cron定时任务CronList、CronGet、CronCreate、CronUpdate、CronDeleteCron结构体包含Schedulecron 表达式、Branch、Enabled、NextExec等字段。4.5 组织与全局资源组织Org(orgID)、OrgLookup(name)、OrgList以及OrgSecret*组织级密钥与OrgRegistry*组织级镜像仓库系列全局资源GlobalSecret*与GlobalRegistry*系列见 global_secret.go、global_registry.go用于管理员配置全局共享的密钥与镜像仓库凭据。4.6 队列、Agent 与日志级别QueueInfo()获取队列统计与任务明细Info结构体含Pending/WaitingOnDeps/Running任务列表与QueueStats计数见 queue.go 与 types.goAgentListWithOpts(opt AgentListOptions)分页获取注册的 Agent旧版AgentList()已标记 DeprecatedAgentCreate/AgentUpdate/AgentDelete/AgentTasksList等用于 Agent 管理LogLevel()/SetLogLevel(*LogLevel)查询或动态调整服务端日志级别对应/api/log-level端点见 client.go 中的pathLogLevel。五、数据模型速览理解 API 返回的对象types.go 定义了所有 API 返回的数据结构与 Woodpecker 服务端 API 的 JSON 字段一一对应UserID、ForgeID、ForgeRemoteID、Login、Email、Avatar、Active、AdminRepoOwner、Name、FullName、Clone、Branch、Timeout、Visibility、RequireApproval审批模式、Trusted网络/卷/安全三项受信配置、Config配置文件路径、CancelPreviousPipelineEvents等PipelineNumber、Parent、Event、Status、Errors含Type/Message/IsWarning、时间戳系列、Commit、Branch、Ref、Author、Reviewer、Workflows等Workflow下又挂载Children []*Step构成流水线/工作流/步骤三层结构Secret/Registry分别对应密钥与镜像仓库凭据Password/Value字段在 JSON 输出中带omitempty服务端通常不回传明文Cron、Agent、Task、Feed、LogEntry分别用于定时任务、Agent、队列任务、时间线条目与步骤日志。审批模式ApprovalMode的合法取值在 types.go 中有明确的Valid()校验none、forks仅 fork 来的 PR 需要审批、pull_requests默认所有 PR 需要审批、all_events所有事件都需要审批。六、进阶实战一个完整的流水线操作示例把 README 示例扩展为一次完整的“查询仓库 → 触发流水线 → 轮询状态 → 拉取步骤日志”流程package main import ( fmt time go.woodpecker-ci.org/woodpecker/v3/woodpecker-go/woodpecker golang.org/x/oauth2 ) func main() { const ( token dummyToken host http://woodpecker.company.tld ) // 1. 构造带认证的 HTTP 客户端 authenticator : new(oauth2.Config).Client( oauth2.NoContext, oauth2.Token{AccessToken: token}, ) client : woodpecker.NewClient(host, authenticator) // 2. 按完整名称查找仓库 repo, err : client.RepoLookup(woodpecker-ci/woodpecker) if err ! nil { panic(err) } // 3. 手动触发一条流水线可指定分支与自定义变量 created, err : client.PipelineCreate(repo.ID, woodpecker.PipelineOptions{ Branch: main, Variables: map[string]string{FOO: bar}, }) if err ! nil { panic(err) } // 4. 轮询流水线状态直到结束 for { pl, err : client.Pipeline(repo.ID, created.Number) if err ! nil { panic(err) } fmt.Println(status:, pl.Status) if pl.Status woodpecker.StatusSuccess || pl.Status woodpecker.StatusFailure || pl.Status woodpecker.StatusKilled || pl.Status woodpecker.StatusError { break } time.Sleep(5 * time.Second) } }注意事项PipelineCreate的触发目标仓库必须已通过RepoPost激活或已在 Woodpecker UI 中激活否则服务端会拒绝创建需要审批的流水线RequireApproval为pull_requests等模式会停留在blocked状态此时应用应调用PipelineApprove或PipelineDecline而不是一直轮询遍历多页数据时利用ListOptions{Page, PerPage}逐页请求服务端对 Agent 列表等接口不会一次返回多于一页AgentListWithOpts的注释也提示调用方需要自行翻页直到返回不足一页为止。七、测试与验证方式woodpecker-go包内附带了覆盖主要 API 的单元测试可作为接口用法的权威参考client_test.go验证客户端构造、User-Agent 注入与请求行为repo_test.go验证仓库/流水线/Secret/Registry/Cron 各接口的 URL 路径与查询参数编码queue_test.go、agent_test.go、user_test.go分别覆盖队列、Agent 与用户接口list_options_test.go验证分页参数page/perPage的编码行为。在接入真实服务端前建议先用woodpecker.New(host)配合Self()做一次连通性与 Token 有效性冒烟测试再逐步扩展到仓库与流水线操作。八、小结woodpecker-go以极小的学习成本提供了一整层类型安全的 Woodpecker API 封装New/NewClient两个构造器负责初始化与认证接入Client接口覆盖用户、仓库、流水线、Secret、Registry、Cron、组织、Agent、队列等全部常用管理能力底层统一的do/open请求管道保证 JSON 序列化、错误包装与查询参数编码行为一致。无论是编写运维脚本、构建自动化平台还是为团队封装内部 CI 工具链这套 SDK 都是与 Woodpecker 服务端交互的推荐入口。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker CI 本地开发环境搭建指南从安装 Go 到调试 Server 与 AgentWoodpecker CI 本地开发环境搭建指南从安装 Go 到调试 Server 与 Agent 本文是 Woodpecker CI/CD 引擎开发入门指南CI/CDDevOpsWoodpecker 本地流水线执行指南用 woodpecker-cli exec 调试与回放工作流Woodpecker 本地流水线执行指南用 woodpecker cli exec 调试与回放工作流 woodpecker cli exec 是 WoodpeCI/CDDevOpsWoodpecker Volumes 使用指南在 CI 流水线中挂载宿主机文件与 Docker 卷Woodpecker Volumes 使用指南在 CI 流水线中挂载宿主机文件与 Docker 卷 本篇技术指南聚焦 Woodpecker CI/CD 引擎CI/CDDevOps上一篇不会播放的NCM变MP3/FLACNCMconverter 免费批量转换完整指南下一篇Python通达信数据接口 MOOTDX三步拉通 A股K线数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考