CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载配置扩展Configuration Extension是 Woodpecker 提供的一种 HTTP 扩展机制允许你在流水线触发后、执行前对外部服务发起调用动态修改、生成甚至完全替换仓库中的流水线配置文件。本文以 Woodpecker v3.16 文档与源码为基础完整讲解配置扩展的使用场景、全局与仓库级配置方式、请求/响应协议、安全签名机制以及底层调用链帮助你构建诸如模板预处理、格式转换Starlark / Jsonnet / GitLab CI、默认步骤注入与多仓库集中配置等实战能力。什么是配置扩展在 Woodpecker 中流水线的定义文件默认如.woodpecker.yaml通常直接从代码仓库中获取。配置扩展Configuration Extension则允许你在流水线被触发后将原始配置发送到一个你自建的 HTTP 端点由该端点返回新的、符合 Woodpecker YAML 规范的配置Woodpecker 将使用返回结果执行流水线。你可以在仓库设置Repository Settings的 Extensions 选项卡中为单个仓库配置 HTTP 端点。官方文档列出了使用配置扩展的典型场景使用 Go templating 等工具对原始配置文件进行预处理将自定义属性转换为 Woodpecker 原生属性为配置添加默认值例如注入默认步骤default steps将完全不同的配置格式转换为 Woodpecker 配置例如 GitLab CI 配置、Starlark、Jsonnet 等将多个仓库的配置集中到一处进行统一管理。由于扩展能力极其强大——Woodpecker 会把私有信息如 token传递给它并直接执行其返回的配置——官方在安全上做了专门设计详见下文“安全机制”。安全机制签名请求与主机白名单:::warning Woodpecker 会将 token 等私有信息传递给扩展服务并直接执行扩展返回的流水线配置。因此保护外部扩展服务的安全极端重要。Woodpecker 会对每一次请求进行签名。 :::所有对扩展的 HTTP 请求都使用 HTTP Signatures 规范签名底层使用一对 ed25519 公私钥。扩展服务端必须使用公钥验证每一个请求的签名可借助 httpsign 之类的库实现。公钥的获取方式有两种打开http://my-woodpecker.tld/api/signature/public-key或在 Woodpecker UI 中进入仓库设置打开 Extensions 页面查看。从源码看签名实现位于 server/services/utils/http.gogetHTTPClient使用httpsign.NewEd25519Signer基于 ed25519 私钥签名签名标识为woodpecker-ci-extensions签名覆盖request-target与content-digest两个头content-digest由库自动生成请求的 User-Agent 固定为server-extensions且客户端强制InsecureSkipVerify: false。此外为防止扩展端点被用于访问内网服务SSRF 防护Woodpecker 默认只允许扩展调用外部主机 / IP 地址。可通过WOODPECKER_EXTENSIONS_ALLOWED_HOSTS环境变量修改这一行为该变量的定义位于 cmd/server/flags.go命令行参数名extensions-allowed-hosts默认值为hostmatcher.MatchBuiltinExternal。它接受逗号分隔的列表取值类型包括内置网络loopbackIPv4 的 127.0.0.0/8 与 IPv6 的 ::1/128包含 localhostprivateRFC 191810.0.0.0/8、172.16.0.0/12、192.168.0.0/16与 RFC 4193FC00::/7即 LAN / 内网external合法的非私有单播 IP可访问公网所有主机*允许所有主机。CIDR 列表如 IPv4 的1.2.3.0/8、IPv6 的2001:db8::/32通配主机名如example.com、*.example.com、192.168.100.*。全局配置与仓库级配置配置扩展既可以按仓库配置也可以全局配置。全局配置Server 级别在 Woodpecker 服务器配置中设置全局端点即可让扩展作用于所有仓库。适合希望为全部仓库统一启用扩展的场景但需要注意如果你与其他人共享 Woodpecker 服务器他们同样会使用你的配置扩展。WOODPECKER_CONFIG_EXTENSION_ENDPOINThttps://example.com/ciconfig从源码看全局配置对应三个服务器端环境变量见 cmd/server/flags.go环境变量对应命令行参数说明WOODPECKER_CONFIG_EXTENSION_ENDPOINTconfig-extension-endpoint全局配置扩展端点 URL兼容旧的别名WOODPECKER_CONFIG_SERVICE_ENDPOINT/config-service-endpoint该别名计划在 v4.0.0 移除WOODPECKER_CONFIG_EXTENSION_EXCLUSIVEconfig-extension-exclusive全局扩展是否独占exclusive即完全跳过 forge 取配置WOODPECKER_CONFIG_EXTENSION_NETRCconfig-extension-netrc全局扩展是否在请求中附带 netrc 凭据默认false仓库级配置在每个仓库的设置页面 Extensions 选项卡中可分别配置三个选项Config Extension Endpoint仓库专属的扩展端点Config Extension Exclusive是否启用独占模式跳过 forgeSend netrc credentials是否在请求中附带 netrc 凭据。对应地server/model/repo.go 中仓库模型保存了ConfigExtensionEndpointconfig_extension_endpoint、ConfigExtensionExclusiveconfig_extension_exclusive默认 FALSE与ConfigExtensionNetrcconfig_extension_netrc默认 FALSE三个字段。全局与仓库级的同时生效规则当全局端点和仓库专属端点同时配置时全局配置会先于仓库特定扩展被调用除非该仓库启用了 exclusive 设置。这一编排逻辑在 server/services/manager.go 中实现仓库未启用 exclusive组合为forge 获取原始配置 → 全局扩展 → 仓库扩展config.NewCombined(m.config, config.NewHTTP(repoEndpoint, ...))仓库启用 exclusive仅使用仓库专属 HTTP 扩展config.NewHTTP(...)不再调用 forge 与全局扩展。工作原理请求生命周期当一个流水线被触发时Woodpecker 的执行流程如下从仓库forge获取原始流水线配置文件构造一个 HTTP POST 请求向配置好的扩展端点发送 JSON payloadpayload 中包含仓库信息、流水线信息以及从仓库检索到的当前配置文件扩展服务处理后返回修改后的、甚至全新的流水线配置必须符合 Woodpecker 官方 YAML 格式Woodpecker 使用返回的配置继续后续的解析与执行。如果在全局或仓库级启用了exclusive独占设置Woodpecker 将只调用你的扩展而不再调用 forge 取配置此时发送给扩展的请求中也不会携带配置文件字段configuration为空。对应源码中配置获取被抽象为Service接口server/services/config/service.gotype Service interface { Fetch(ctx context.Context, forge forge.Forge, user *model.User, repo *model.Repo, pipeline *model.Pipeline, oldConfigData []*types.FileMeta, restart bool) (configData []*types.FileMeta, err error) }三个实现各司其职server/services/config/forge.goforgeFetcher按仓库配置路径默认顺序见constant.DefaultConfigOrder从 forge 拉取原始配置文件支持单个文件与目录扫描目录模式按WOODPECKER_DEFAULT_PIPELINE_CONFIG_EXTENSIONS过滤扩展名默认.yaml、.yml并带超时与重试server/services/config/http.gohttpService即本文主题的 HTTP 配置扩展实现server/services/config/combined.gocombined把多个 Service 串联成链前一个的输出作为后一个的输入实现“forge → 全局扩展 → 仓库扩展”的流水线式处理。请求格式Request扩展端点收到的是一个 HTTP POST 请求JSON 载荷结构如下class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // only included when netrc sending is enabled (see above) configuration?: { // list of configurations. Not send if there was none. name: string; // filename of the configuration file data: string; // content of the configuration file }[]; }字段说明repo仓库模型详见 server/model/repo.gopipeline流水线模型详见 server/model/pipeline.gonetrc可选仅当全局环境变量WOODPECKER_CONFIG_EXTENSION_NETRC设为true默认false或仓库勾选了“Send netrc credentials”时才会包含模型见 server/model/netrc.goconfiguration配置文件列表每个元素包含文件名name与文件内容data若没有配置文件如 exclusive 模式则不会发送该字段。:::tipnetrc数据非常强大它包含访问仓库的凭据。你可以利用它克隆仓库甚至调用 forgeGitHub、GitLab 等的 API 获取更多仓库信息。 :::在 server/services/config/http.go 中请求结构被定义为type requestStructure struct { Repo *model.Repo json:repo Pipeline *model.Pipeline json:pipeline Netrc *model.Netrc json:netrc Configuration []*configData json:configuration,omitempty }其中Configuration带omitempty验证了“无配置时不发送该字段”的约定netrc仅在includeNetrc为 true 时由forge.Netrc(user, repo)获取并填充。一个完整的请求示例{ repo: { id: 100, uid: , user_id: 0, namespace: , name: woodpecker-test-pipeline, slug: , scm: git, git_http_url: , git_ssh_url: , link: , default_branch: , private: true, visibility: private, active: true, config: , trusted: false, protected: false, ignore_forks: false, ignore_pulls: false, cancel_pulls: false, timeout: 60, counter: 0, synced: 0, created: 0, updated: 0, version: 0 }, pipeline: { author: myUser, author_avatar: https://myforge.com/avatars/d6b3f7787a685fcdf2a44e2c685c7e03, author_email: myemail.com, branch: main, changed_files: [some-filename.txt], commit: 2fff90f8d288a4640e90f05049fe30e61a14fd50, created_at: 0, deploy_to: , enqueued_at: 0, error: , event: push, finished_at: 0, id: 0, link_url: https://myforge.com/myUser/woodpecker-testpipe/commit/2fff90f8d288a4640e90f05049fe30e61a14fd50, message: test old config\n, number: 0, parent: 0, ref: refs/heads/main, refspec: , clone_url: , reviewed_at: 0, reviewed_by: , sender: myUser, signed: false, started_at: 0, status: , timestamp: 1645962783, title: , updated_at: 0, verified: false }, configuration: [ { name: .woodpecker.yaml, data: steps:\n - name: backend\n image: alpine\n commands:\n - echo \Hello there from Repo (.woodpecker.yaml)\\n } ], netrc: { machine: myforge.com, login: myUser, password: forge-access-token } }注意configuration[].data中的\n为 JSON 转义后的换行符实际内容是标准 YAML 文本。响应格式Response扩展服务应返回一个 JSON payload其中包含新的配置文件列表格式必须符合 Woodpecker 官方 YAML 规范。如果扩展希望保留仓库中的现有配置即不做任何修改则可以响应 HTTP 状态码204 No Content。class Response { configs: { name: string; // filename of the configuration file data: string; // content of the configuration file }[]; }一个完整的响应示例{ configs: [ { name: central-override, data: steps:\n - name: backend\n image: alpine\n commands:\n - echo \Hello there from ConfigAPI\\n } ] }从 server/services/config/http.go 的Fetch实现可以梳理出完整的响应处理逻辑发送 POST 后若状态码为204记录 debug 日志并原样返回旧配置return oldConfigData, nil流水线继续按仓库原始配置执行若状态码为200将响应中的configs数组转换为FileMeta列表返回作为后续解析执行的配置其他状态码既不是 200 也不是 204会返回错误例如unexpected status code %d from config endpoint (expected 200 or 204)。HTTP 客户端server/services/utils/http.go还内置了请求增强逻辑单次请求超时 10 秒指数退避重试最多 3 次网络超时、连接被拒、连接重置、DNS 解析失败、TLS 握手超时等瞬时错误可重试5xx 服务端错误也会触发重试而 4xx 客户端错误直接失败不再重试请求与响应均通过 JSON 编解码Content-Type 为application/json。实战要点与最佳实践结合文档与源码以下要点可帮助你正确落地配置扩展验证签名生产环境中务必使用从/api/signature/public-key获取的公钥验证每个请求的 HTTP 签名ed25519 / HTTP Signatures防止伪造请求。签名头覆盖request-target与content-digest。控制主机访问范围默认只能访问公网主机。若扩展部署在内网需通过WOODPECKER_EXTENSIONS_ALLOWED_HOSTS显式放行例如WOODPECKER_EXTENSIONS_ALLOWED_HOSTS10.0.0.8,*.internal.example.com如无必要不要设置为*。利用 netrc 做深度集成勾选发送 netrc 后扩展可获得 forge 凭据可用于克隆仓库、调用 forge API 获取 MR 元数据、变更文件列表等实现基于上下文的智能配置生成但请务必谨慎保管该凭据。区分全局与仓库级全局端点在仓库端点之前执行全局共享服务器时要考虑所有用户都会受影响。exclusive 模式可完全脱离 forge适合配置完全由外部系统如 CMDB、内部 GitOps 平台生成且无需仓库配置文件的场景。返回值必须合法返回的configs必须为 Woodpecker 官方 YAML 格式否则流水线解析会失败不确定时优先返回204 No Content保留原配置。注意重试幂等性客户端会最多重试 3 次扩展端点应保证幂等同一请求重复处理结果一致避免因网络抖动导致配置被重复生成或产生副作用。通过组合 forge 拉取、全局扩展与仓库扩展三级处理链Woodpecker 配置扩展可以在不修改各仓库文件的前提下将模板化、集中式、跨格式的流水线配置能力统一收敛到你的服务端是大型团队与平台化 CI 建设中非常实用的扩展点。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker 配置扩展Configuration Extension完全指南通过 HTTP 端点按需修改与生成流水线配置Woodpecker 配置扩展Configuration Extension完全指南通过 HTTP 端点按需修改与生成流水线配置 配置扩展ConfiguCI/CDDevOpsWoodpecker 插件体系完全指南从流水线配置到自定义插件开发Woodpecker 插件体系完全指南从流水线配置到自定义插件开发 Woodpecker 的插件Plugin本质上是执行预定义任务的流水线步骤pipelCI/CDDevOpsEasyWeChat 3.x 配置完全指南Application 初始化、全部配置项与动态修改EasyWeChat 3.x 配置完全指南Application 初始化、全部配置项与动态修改 本指南以 EasyWeChat 3.x 官方配置文档为核心系后端即时通讯上一篇CANN/ge图引擎API获取自定义值下一篇Nimporter使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
