CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本指南以 Woodpecker CI 官方文档docs/versioned_docs/version-3.16/20-usage/72-extensions/index.md为骨架结合当前仓库源码系统讲解 Woodpecker 的扩展体系如何通过预定义的 HTTP 端点替换内部逻辑实现管道配置的运行时生成/改写、容器镜像仓库凭据的外部化获取、以及密钥Secret的集中管理。读完本文你将掌握三类扩展的接入方式、请求/响应协议、签名验签机制与主机访问白名单配置并能在自己的部署中安全地开发和部署扩展服务。一、扩展机制概述用 HTTP 端点替换内部逻辑Woodpecker 允许你通过预定义的 HTTP 端点pre-defined http endpoints将内部逻辑替换为外部扩展extension。这是一条典型的“插件化”路径核心引擎保留调度与执行能力而配置解析、凭据获取、密钥注入等周边逻辑可以交给独立的、由你掌控的外部服务。当前版本v3.16 文档对应版本提供三类扩展扩展类型文档作用配置扩展Configuration extension40-configuration-extension.md在运行前修改或生成管道配置Registry 扩展Registry extension50-registry-extension.md从外部服务获取镜像仓库凭据密钥扩展Secret extension55-secret-extension.md从外部服务获取密钥Secrets三类扩展的接入入口一致在仓库设置的 Extensions扩展标签页中配置一个 HTTP 端点同时也可以在服务器级配置中设置全局端点作用于所有仓库。权限模型提醒务必阅读:::note Woodpecker 的权限处理与 forge代码托管平台绑定在你的 forge 上对仓库拥有管理员权限的用户在 Woodpecker 中也会拥有该仓库的管理员权限从而可以修改已配置的扩展。这可能被利用来获取 forge 用户的凭据。请确保你信任所有可以登录 Woodpecker 的仓库管理员。 :::这一条提醒出自官方文档属于部署安全基线扩展端点的可写权限与 forge 管理员权限强耦合因此在共享服务器上必须谨慎评估仓库管理员的信任边界。二、安全机制ed25519 HTTP 签名与公钥获取为什么必须签名:::warning 你必须信任扩展服务因为它们会接收到 secrets、tokens 等私有信息并可能返回恶意管道配置例如会被执行的危险命令。扩展返回的配置是会被 Woodpecker 实际执行的。 :::签名实现HTTP Signatures ed25519为防止扩展被攻击/篡改Woodpecker 使用 HTTP signatures 对所有发往扩展的 HTTP 请求进行签名采用公钥-私钥 ed25519 密钥对。扩展端必须使用公钥验证所有请求的签名可借助如httpsign之类的库。从源码看这一机制实现在 server/services/utils/http.gosigner, err : httpsign.NewEd25519Signer(ed25519Key, httpsign.NewSignConfig(), httpsign.Headers(request-target, content-digest)) // The Content-Digest header will be auto-generated关键细节签名名称key id为woodpecker-ci-extensions见 server/services/utils/http.go被签名的头部为request-target与content-digest后者由客户端自动生成即请求目标与请求体摘要都被纳入签名范围可有效防止请求被重放、改写客户端通过httpsign.NewClient包装标准http.Client整个调用链路封装在Client类型中server/services/utils/http.go。获取 Woodpecker 公钥你可以通过两种方式获取公钥HTTP API直接访问http://my-woodpecker.tld/api/signature/public-keyUI 界面打开仓库设置 → Extensions扩展页面查看。该 API 由 server/api/signature_public_key.go 实现返回 PKIX 格式的 ed25519 公钥x509.MarshalPKIXPublicKey路由注册于 server/router/api.goGET /signature/public-key。扩展端拿到公钥后需在每次收到请求时校验签名头。参考实现可参见 woodpecker-ci 官方的example-extensions示例仓库在扩展服务开发时可作为起点注意其中的地址指向外部 GitHub本文不展开。客户端调用行为源码级补充从 server/services/utils/http.go 的Send方法可以确认扩展调用的网络行为这对扩展服务端设计很重要请求超时10 * time.Secondhttp.go重试机制最多重试 3 次使用指数退避backoff.NewExponentialBackOff()网络超时、连接拒绝、连接重置、主机不存在、TLS 握手超时等视为可重试错误5xx 状态码会重试4xx 客户端错误不重试http.goUser-Agentserver-extensionshttp.goTLS 校验默认开启证书校验InsecureSkipVerify: false。这意味着扩展服务端应当对请求做幂等设计因为同一请求可能被重试多次。三、主机访问白名单WOODPECKER_EXTENSIONS_ALLOWED_HOSTS出于安全考虑默认只允许扩展调用外部主机/IP防止扩展端点被用来访问本地内部服务。要放宽限制设置环境变量WOODPECKER_EXTENSIONS_ALLOWED_HOSTS支持逗号分隔的多种取值1. 内置网络Built-in networks取值含义loopback127.0.0.0/8IPv4与 ::1/128IPv6包含 localhostprivateRFC 191810.0.0.0/8、172.16.0.0/12、192.168.0.0/16与 RFC 4193FC00::/7即 LAN/内网external合法的非私有单播 IP可访问公网上的所有主机*允许所有主机2. CIDR 列表例如 IPv4 的1.2.3.0/8、IPv6 的2001:db8::/32。3. 通配主机名例如example.com、*.example.com、192.168.100.*。源码佐证默认值即hostmatcher.MatchBuiltinExternal当环境变量为空时并通过hostmatcher.ParseHostMatchList(WOODPECKER_EXTENSIONS_ALLOWED_HOSTS, allowedHostListValue)解析最终由hostmatcher.NewDialContext注入到http.Transport.DialContext在 TCP 拨号层直接拦截非法目标server/services/utils/http.go。典型场景示例# 允许访问内网仓库服务和本地开发机 WOODPECKER_EXTENSIONS_ALLOWED_HOSTSprivate,192.168.100.*,extensions.internal.example.com四、配置扩展Configuration Extension运行时生成与改写管道配置适用场景配置扩展用于修改或生成 Woodpecker 管道配置在仓库设置 → Extensions 标签页配置 HTTP 端点即可启用。典型用途包括用 Go templating 等方式预处理原始配置文件将自定义属性转换为 Woodpecker 属性为配置添加默认值如默认步骤将完全不同格式的配置文件如 GitLab CI 配置、Starlark、Jsonnet 等转换为 Woodpecker 格式集中管理多个仓库的配置在单一位置统一维护。安全警告:::warning Woodpecker 会向扩展传递 tokens 等私有信息并会执行扩展返回的配置因此保护外部扩展极其重要。Woodpecker 会对每个请求签名详见前文 安全机制。 :::全局配置除了按仓库配置还可在服务器配置中设置全局端点让所有仓库共用。注意如果与别人共享 Woodpecker 服务器他们也会使用你的配置扩展。WOODPECKER_CONFIG_EXTENSION_ENDPOINThttps://example.com/ciconfig调用顺序若同时配置了全局端点与仓库级端点且仓库未启用 exclusive独占设置则先调用全局扩展再调用仓库级扩展。工作原理管道触发后Woodpecker 从仓库拉取管道配置文件然后向配置的扩展发送 HTTPPOST请求JSON 载荷中包含仓库信息、管道信息及从仓库取回的配置文件扩展可以返回修改后的、甚至是全新的管道配置遵循 Woodpecker 官方 YAML 格式。如果启用exclusive独占设置全局或仓库级均可Woodpecker只调用你的扩展而不做其他事从而可以完全跳过 forge此时发送给扩展的请求中不会附带配置文件。请求格式Request扩展收到一个 HTTP POST 请求JSON 载荷结构如下class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用 netrc 发送时包含见下 configuration?: { // 配置文件列表若仓库没有配置文件则不发送 name: string; // 配置文件名 data: string; // 配置文件内容 }[]; }各模型对应源码位置repo 模型server/model/repo.gopipeline 模型server/model/pipeline.gonetrc 模型server/model/netrc.go:::infonetrc字段仅在全局WOODPECKER_CONFIG_EXTENSION_NETRC设为true默认false或仓库勾选了 “Send netrc credentials” 时才会包含在请求中。 ::::::tipnetrc数据非常强大它包含访问仓库所需的凭据。你可以用它克隆仓库甚至调用 forgeGitHub、GitLab 等API 获取更多仓库信息。 :::示例请求{ 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 } }响应格式Response扩展应返回 JSON 载荷包含遵循 Woodpecker 官方 YAML 格式的新配置文件。若希望保留现有配置文件可返回 HTTP 状态码204 No Content。class Response { configs: { name: string; // 配置文件名 data: string; // 配置文件内容 }[]; }示例响应{ configs: [ { name: central-override, data: steps:\n - name: backend\n image: alpine\n commands:\n - echo \Hello there from ConfigAPI\\n } ] }五、Registry 扩展外部化镜像仓库凭据适用场景Woodpecker 使用 Registry 扩展获取镜像仓库凭据在仓库设置 → Extensions 标签页配置 HTTP 端点。典型用途集中管理仓库凭据使用外部存储存放凭据动态决定 Woodpecker 应使用哪组凭据。安全警告:::warning 同上Woodpecker 会传递 tokens 等私有信息并执行返回的配置必须保护好外部扩展并验证每个请求的签名。 :::全局配置WOODPECKER_REGISTRY_EXTENSION_ENDPOINThttps://example.com/ciconfig优先级规则若全局扩展与仓库级扩展都返回了同一仓库的凭据则使用仓库级扩展的凭据。工作原理管道触发时Woodpecker 先从你的扩展服务获取凭据作为回退fallback使用直接配置在 Woodpecker 中的凭据。请求/响应结构Repo、Pipeline、Netrc 模型同上文class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用 netrc 发送时包含 }class Response { registries: { address: string; // Docker 仓库地址 username: string; // 仓库用户名 password: string; // 仓库密码 }[]; }示例响应{ registries: [ { address: docker.io, username: woodpecker-bot, password: your-pass-word-123 } ] }源码佐证在 server/services/manager.go 中当仓库配置了RegistryExtensionEndpoint时会构造registry.NewWithExtension(m.registry, registry.NewHTTP(...))即本地配置凭据作为底层的回退来源扩展凭据优先叠加其上——这与文档中“先查扩展、回退到本地配置”的描述一致。同时WOODPECKER_REGISTRY_EXTENSION_NETRC控制是否发送 netrc 凭据默认false。六、密钥扩展Secret Extension集中管理与动态生成 Secrets适用场景Woodpecker 使用 Secret 扩展从外部服务获取密钥在仓库设置 → Extensions 标签页配置 HTTP 端点。典型用途集中管理密钥例如 HashiCorp Vault、AWS Secrets Manager 等外部系统按管道动态生成密钥。全局配置WOODPECKER_SECRET_EXTENSION_ENDPOINThttps://example.com/secrets WOODPECKER_SECRET_EXTENSION_NETRCfalse优先级规则若全局扩展与仓库级扩展返回同名密钥则使用仓库级扩展的密钥。工作原理管道触发时Woodpecker 从你的服务获取密钥与直接配置在 Woodpecker 中的密钥合并扩展密钥按名称优先若扩展不可用则回退到本地配置的密钥。请求格式class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用 netrc 发送时包含 }请求示例中的字段结构可参考上文配置扩展的示例netrc字段在未启用发送时会被省略文档同时提示请以 server/model/repo.go、server/model/pipeline.go、server/model/netrc.go 中的最新模型为准示例可能过时。响应格式扩展应返回包含secrets数组的 JSON 对象若不想添加任何密钥、仅保留现有密钥可返回204 No Content。class Response { secrets: { name: string; // 密钥名与管道配置中的 from_secret 对应 value: string; // 密钥值 images?: string[]; // 可选限制仅用于特定插件 events?: string[]; // 可选限制仅用于特定管道事件 }[]; }示例响应{ secrets: [ { name: docker_password, value: your-secret-password-123 }, { name: deploy_token, value: super-secret-token, events: [push, tag] } ] }其中events可选值对应 Woodpecker 的管道事件类型如push、tag等配合images可实现“某个密钥只对某插件、某事件可见”的细粒度控制。管道配置中通过from_secret: 密钥名引用扩展返回的密钥。源码佐证在 server/services/manager.go 中仓库配置了SecretExtensionEndpoint时构造secret.NewCombined(m.secret, secret.NewHTTP(...))同样以本地 secret 服务为底层、扩展为叠加层印证了“扩展密钥按名称优先、本地密钥兜底”的行为。七、第三方扩展与生态注意事项:::danger 以下列出的第三方扩展既不是 Woodpecker CI 开发也未经过其验证。使用前请确保你信任它们。 :::Secret 扩展文档的 “3rd Party Extensions” 一节明确提示任何第三方扩展均未被 Woodpecker CI 开发或验证使用前必须自行审计其安全性。官方同时欢迎社区将自研扩展补充进该列表_Add your extension here!_。结合前文的签名机制所有扩展无论是自研还是第三方都应在服务端验证每次请求的 ed25519 签名公钥来自/api/signature/public-key或仓库设置页面对响应中返回的配置内容保持高度警惕因为配置会被实际执行将自身部署在可信任的隔离环境中限制其出网能力与数据访问范围。八、仓库级扩展配置的底层模型在仓库层面扩展的端点与 netrc 开关作为仓库模型的字段持久化见 server/model/repo.go字段JSON 字段名说明ConfigExtensionEndpointconfig_extension_endpoint配置扩展端点varchar 500ConfigExtensionNetrcconfig_extension_netrc是否向配置扩展发送 netrc默认 falseRegistryExtensionEndpointregistry_extension_endpointRegistry 扩展端点RegistryExtensionNetrcregistry_extension_netrc是否发送 netrc默认 falseSecretExtensionEndpointsecret_extension_endpointSecret 扩展端点SecretExtensionNetrcsecret_extension_netrc是否发送 netrc默认 false仓库 API 更新接口 server/api/repo.go 支持通过PATCH修改这些字段即你在 UI 的 Extensions 标签页上的操作最终会写入这些字段并由 server/services/manager.go 在服务装配阶段据此构造对应的扩展客户端config.NewCombined/registry.NewWithExtension/secret.NewCombined端点均经过strings.TrimRight(endpoint, /)规范化。九、开发扩展的检查清单综合以上内容开发一个 Woodpecker 扩展服务的最小清单如下端点协议提供 HTTP POST 端点按扩展类型解析对应的RequestJSONRepo Pipeline [ Netrc] [ Configuration]并按类型返回configs/registries/secretsJSON不需要变更时返回204 No Content签名验证从http://my-woodpecker.tld/api/signature/public-key获取公钥用httpsign等库校验每个请求的request-target与content-digest签名幂等与超时请求可能被重试至多 3 次5xx/网络错误时处理逻辑需幂等响应应在 10 秒超时窗口内完成主机白名单若扩展部署在内网/本地记得通过WOODPECKER_EXTENSIONS_ALLOWED_HOSTS显式放行默认仅允许 external权限与信任牢记 forge 管理员等同于仓库扩展配置管理员在共享服务器上谨慎启用全局扩展配置生成安全配置扩展返回的 YAML 会被实际执行务必只生成可信内容。扩展体系的这三大组件让 Woodpecker 在不修改核心引擎的情况下即可对接企业自有的配置中心、凭据库与密钥管理基础设施是 Woodpecker“简单但强大、扩展性出色”定位的关键实现之一。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Akka Classic Extensions 扩展机制完全指南从自定义扩展到配置加载与库扩展Akka Classic Extensions 扩展机制完全指南从自定义扩展到配置加载与库扩展 Akka Extensions 是 Akka 提供的官方扩展机后端并发编程异步编程Woodpecker 扩展机制完全指南用 HTTP 端点替换内部逻辑配置、注册表与密钥扩展Woodpecker 扩展机制完全指南用 HTTP 端点替换内部逻辑配置、注册表与密钥扩展 Woodpecker 允许通过预定义的 HTTP 端点将内部逻CI/CDDevOpsdeck.gl Layer Extensions 扩展机制完全指南从 deck.gl/extensions 内置扩展到自定义扩展开发deck.gl Layer Extensions 扩展机制完全指南从 deck.gl/extensions 内置扩展到自定义扩展开发 deck.gl/ex前端数据可视化3D渲染图形学上一篇Qt Go蓝牙通信bluetooth模块设备发现与数据传输下一篇effect-smol HttpApi 中间件认证、授权与安全完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Woodpecker 扩展机制（Extensions）完全指南：配置、Registry 与 Secret 三类 HTTP 扩展的接入与安全实践
CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本指南以 Woodpecker CI 官方文档docs/versioned_docs/version-3.16/20-usage/72-extensions/index.md为骨架结合当前仓库源码系统讲解 Woodpecker 的扩展体系如何通过预定义的 HTTP 端点替换内部逻辑实现管道配置的运行时生成/改写、容器镜像仓库凭据的外部化获取、以及密钥Secret的集中管理。读完本文你将掌握三类扩展的接入方式、请求/响应协议、签名验签机制与主机访问白名单配置并能在自己的部署中安全地开发和部署扩展服务。一、扩展机制概述用 HTTP 端点替换内部逻辑Woodpecker 允许你通过预定义的 HTTP 端点pre-defined http endpoints将内部逻辑替换为外部扩展extension。这是一条典型的“插件化”路径核心引擎保留调度与执行能力而配置解析、凭据获取、密钥注入等周边逻辑可以交给独立的、由你掌控的外部服务。当前版本v3.16 文档对应版本提供三类扩展扩展类型文档作用配置扩展Configuration extension40-configuration-extension.md在运行前修改或生成管道配置Registry 扩展Registry extension50-registry-extension.md从外部服务获取镜像仓库凭据密钥扩展Secret extension55-secret-extension.md从外部服务获取密钥Secrets三类扩展的接入入口一致在仓库设置的 Extensions扩展标签页中配置一个 HTTP 端点同时也可以在服务器级配置中设置全局端点作用于所有仓库。权限模型提醒务必阅读:::note Woodpecker 的权限处理与 forge代码托管平台绑定在你的 forge 上对仓库拥有管理员权限的用户在 Woodpecker 中也会拥有该仓库的管理员权限从而可以修改已配置的扩展。这可能被利用来获取 forge 用户的凭据。请确保你信任所有可以登录 Woodpecker 的仓库管理员。 :::这一条提醒出自官方文档属于部署安全基线扩展端点的可写权限与 forge 管理员权限强耦合因此在共享服务器上必须谨慎评估仓库管理员的信任边界。二、安全机制ed25519 HTTP 签名与公钥获取为什么必须签名:::warning 你必须信任扩展服务因为它们会接收到 secrets、tokens 等私有信息并可能返回恶意管道配置例如会被执行的危险命令。扩展返回的配置是会被 Woodpecker 实际执行的。 :::签名实现HTTP Signatures ed25519为防止扩展被攻击/篡改Woodpecker 使用 HTTP signatures 对所有发往扩展的 HTTP 请求进行签名采用公钥-私钥 ed25519 密钥对。扩展端必须使用公钥验证所有请求的签名可借助如httpsign之类的库。从源码看这一机制实现在 server/services/utils/http.gosigner, err : httpsign.NewEd25519Signer(ed25519Key, httpsign.NewSignConfig(), httpsign.Headers(request-target, content-digest)) // The Content-Digest header will be auto-generated关键细节签名名称key id为woodpecker-ci-extensions见 server/services/utils/http.go被签名的头部为request-target与content-digest后者由客户端自动生成即请求目标与请求体摘要都被纳入签名范围可有效防止请求被重放、改写客户端通过httpsign.NewClient包装标准http.Client整个调用链路封装在Client类型中server/services/utils/http.go。获取 Woodpecker 公钥你可以通过两种方式获取公钥HTTP API直接访问http://my-woodpecker.tld/api/signature/public-keyUI 界面打开仓库设置 → Extensions扩展页面查看。该 API 由 server/api/signature_public_key.go 实现返回 PKIX 格式的 ed25519 公钥x509.MarshalPKIXPublicKey路由注册于 server/router/api.goGET /signature/public-key。扩展端拿到公钥后需在每次收到请求时校验签名头。参考实现可参见 woodpecker-ci 官方的example-extensions示例仓库在扩展服务开发时可作为起点注意其中的地址指向外部 GitHub本文不展开。客户端调用行为源码级补充从 server/services/utils/http.go 的Send方法可以确认扩展调用的网络行为这对扩展服务端设计很重要请求超时10 * time.Secondhttp.go重试机制最多重试 3 次使用指数退避backoff.NewExponentialBackOff()网络超时、连接拒绝、连接重置、主机不存在、TLS 握手超时等视为可重试错误5xx 状态码会重试4xx 客户端错误不重试http.goUser-Agentserver-extensionshttp.goTLS 校验默认开启证书校验InsecureSkipVerify: false。这意味着扩展服务端应当对请求做幂等设计因为同一请求可能被重试多次。三、主机访问白名单WOODPECKER_EXTENSIONS_ALLOWED_HOSTS出于安全考虑默认只允许扩展调用外部主机/IP防止扩展端点被用来访问本地内部服务。要放宽限制设置环境变量WOODPECKER_EXTENSIONS_ALLOWED_HOSTS支持逗号分隔的多种取值1. 内置网络Built-in networks取值含义loopback127.0.0.0/8IPv4与 ::1/128IPv6包含 localhostprivateRFC 191810.0.0.0/8、172.16.0.0/12、192.168.0.0/16与 RFC 4193FC00::/7即 LAN/内网external合法的非私有单播 IP可访问公网上的所有主机*允许所有主机2. CIDR 列表例如 IPv4 的1.2.3.0/8、IPv6 的2001:db8::/32。3. 通配主机名例如example.com、*.example.com、192.168.100.*。源码佐证默认值即hostmatcher.MatchBuiltinExternal当环境变量为空时并通过hostmatcher.ParseHostMatchList(WOODPECKER_EXTENSIONS_ALLOWED_HOSTS, allowedHostListValue)解析最终由hostmatcher.NewDialContext注入到http.Transport.DialContext在 TCP 拨号层直接拦截非法目标server/services/utils/http.go。典型场景示例# 允许访问内网仓库服务和本地开发机 WOODPECKER_EXTENSIONS_ALLOWED_HOSTSprivate,192.168.100.*,extensions.internal.example.com四、配置扩展Configuration Extension运行时生成与改写管道配置适用场景配置扩展用于修改或生成 Woodpecker 管道配置在仓库设置 → Extensions 标签页配置 HTTP 端点即可启用。典型用途包括用 Go templating 等方式预处理原始配置文件将自定义属性转换为 Woodpecker 属性为配置添加默认值如默认步骤将完全不同格式的配置文件如 GitLab CI 配置、Starlark、Jsonnet 等转换为 Woodpecker 格式集中管理多个仓库的配置在单一位置统一维护。安全警告:::warning Woodpecker 会向扩展传递 tokens 等私有信息并会执行扩展返回的配置因此保护外部扩展极其重要。Woodpecker 会对每个请求签名详见前文 安全机制。 :::全局配置除了按仓库配置还可在服务器配置中设置全局端点让所有仓库共用。注意如果与别人共享 Woodpecker 服务器他们也会使用你的配置扩展。WOODPECKER_CONFIG_EXTENSION_ENDPOINThttps://example.com/ciconfig调用顺序若同时配置了全局端点与仓库级端点且仓库未启用 exclusive独占设置则先调用全局扩展再调用仓库级扩展。工作原理管道触发后Woodpecker 从仓库拉取管道配置文件然后向配置的扩展发送 HTTPPOST请求JSON 载荷中包含仓库信息、管道信息及从仓库取回的配置文件扩展可以返回修改后的、甚至是全新的管道配置遵循 Woodpecker 官方 YAML 格式。如果启用exclusive独占设置全局或仓库级均可Woodpecker只调用你的扩展而不做其他事从而可以完全跳过 forge此时发送给扩展的请求中不会附带配置文件。请求格式Request扩展收到一个 HTTP POST 请求JSON 载荷结构如下class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用 netrc 发送时包含见下 configuration?: { // 配置文件列表若仓库没有配置文件则不发送 name: string; // 配置文件名 data: string; // 配置文件内容 }[]; }各模型对应源码位置repo 模型server/model/repo.gopipeline 模型server/model/pipeline.gonetrc 模型server/model/netrc.go:::infonetrc字段仅在全局WOODPECKER_CONFIG_EXTENSION_NETRC设为true默认false或仓库勾选了 “Send netrc credentials” 时才会包含在请求中。 ::::::tipnetrc数据非常强大它包含访问仓库所需的凭据。你可以用它克隆仓库甚至调用 forgeGitHub、GitLab 等API 获取更多仓库信息。 :::示例请求{ 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 } }响应格式Response扩展应返回 JSON 载荷包含遵循 Woodpecker 官方 YAML 格式的新配置文件。若希望保留现有配置文件可返回 HTTP 状态码204 No Content。class Response { configs: { name: string; // 配置文件名 data: string; // 配置文件内容 }[]; }示例响应{ configs: [ { name: central-override, data: steps:\n - name: backend\n image: alpine\n commands:\n - echo \Hello there from ConfigAPI\\n } ] }五、Registry 扩展外部化镜像仓库凭据适用场景Woodpecker 使用 Registry 扩展获取镜像仓库凭据在仓库设置 → Extensions 标签页配置 HTTP 端点。典型用途集中管理仓库凭据使用外部存储存放凭据动态决定 Woodpecker 应使用哪组凭据。安全警告:::warning 同上Woodpecker 会传递 tokens 等私有信息并执行返回的配置必须保护好外部扩展并验证每个请求的签名。 :::全局配置WOODPECKER_REGISTRY_EXTENSION_ENDPOINThttps://example.com/ciconfig优先级规则若全局扩展与仓库级扩展都返回了同一仓库的凭据则使用仓库级扩展的凭据。工作原理管道触发时Woodpecker 先从你的扩展服务获取凭据作为回退fallback使用直接配置在 Woodpecker 中的凭据。请求/响应结构Repo、Pipeline、Netrc 模型同上文class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用 netrc 发送时包含 }class Response { registries: { address: string; // Docker 仓库地址 username: string; // 仓库用户名 password: string; // 仓库密码 }[]; }示例响应{ registries: [ { address: docker.io, username: woodpecker-bot, password: your-pass-word-123 } ] }源码佐证在 server/services/manager.go 中当仓库配置了RegistryExtensionEndpoint时会构造registry.NewWithExtension(m.registry, registry.NewHTTP(...))即本地配置凭据作为底层的回退来源扩展凭据优先叠加其上——这与文档中“先查扩展、回退到本地配置”的描述一致。同时WOODPECKER_REGISTRY_EXTENSION_NETRC控制是否发送 netrc 凭据默认false。六、密钥扩展Secret Extension集中管理与动态生成 Secrets适用场景Woodpecker 使用 Secret 扩展从外部服务获取密钥在仓库设置 → Extensions 标签页配置 HTTP 端点。典型用途集中管理密钥例如 HashiCorp Vault、AWS Secrets Manager 等外部系统按管道动态生成密钥。全局配置WOODPECKER_SECRET_EXTENSION_ENDPOINThttps://example.com/secrets WOODPECKER_SECRET_EXTENSION_NETRCfalse优先级规则若全局扩展与仓库级扩展返回同名密钥则使用仓库级扩展的密钥。工作原理管道触发时Woodpecker 从你的服务获取密钥与直接配置在 Woodpecker 中的密钥合并扩展密钥按名称优先若扩展不可用则回退到本地配置的密钥。请求格式class Request { repo: Repo; pipeline: Pipeline; netrc?: Netrc; // 仅当启用 netrc 发送时包含 }请求示例中的字段结构可参考上文配置扩展的示例netrc字段在未启用发送时会被省略文档同时提示请以 server/model/repo.go、server/model/pipeline.go、server/model/netrc.go 中的最新模型为准示例可能过时。响应格式扩展应返回包含secrets数组的 JSON 对象若不想添加任何密钥、仅保留现有密钥可返回204 No Content。class Response { secrets: { name: string; // 密钥名与管道配置中的 from_secret 对应 value: string; // 密钥值 images?: string[]; // 可选限制仅用于特定插件 events?: string[]; // 可选限制仅用于特定管道事件 }[]; }示例响应{ secrets: [ { name: docker_password, value: your-secret-password-123 }, { name: deploy_token, value: super-secret-token, events: [push, tag] } ] }其中events可选值对应 Woodpecker 的管道事件类型如push、tag等配合images可实现“某个密钥只对某插件、某事件可见”的细粒度控制。管道配置中通过from_secret: 密钥名引用扩展返回的密钥。源码佐证在 server/services/manager.go 中仓库配置了SecretExtensionEndpoint时构造secret.NewCombined(m.secret, secret.NewHTTP(...))同样以本地 secret 服务为底层、扩展为叠加层印证了“扩展密钥按名称优先、本地密钥兜底”的行为。七、第三方扩展与生态注意事项:::danger 以下列出的第三方扩展既不是 Woodpecker CI 开发也未经过其验证。使用前请确保你信任它们。 :::Secret 扩展文档的 “3rd Party Extensions” 一节明确提示任何第三方扩展均未被 Woodpecker CI 开发或验证使用前必须自行审计其安全性。官方同时欢迎社区将自研扩展补充进该列表_Add your extension here!_。结合前文的签名机制所有扩展无论是自研还是第三方都应在服务端验证每次请求的 ed25519 签名公钥来自/api/signature/public-key或仓库设置页面对响应中返回的配置内容保持高度警惕因为配置会被实际执行将自身部署在可信任的隔离环境中限制其出网能力与数据访问范围。八、仓库级扩展配置的底层模型在仓库层面扩展的端点与 netrc 开关作为仓库模型的字段持久化见 server/model/repo.go字段JSON 字段名说明ConfigExtensionEndpointconfig_extension_endpoint配置扩展端点varchar 500ConfigExtensionNetrcconfig_extension_netrc是否向配置扩展发送 netrc默认 falseRegistryExtensionEndpointregistry_extension_endpointRegistry 扩展端点RegistryExtensionNetrcregistry_extension_netrc是否发送 netrc默认 falseSecretExtensionEndpointsecret_extension_endpointSecret 扩展端点SecretExtensionNetrcsecret_extension_netrc是否发送 netrc默认 false仓库 API 更新接口 server/api/repo.go 支持通过PATCH修改这些字段即你在 UI 的 Extensions 标签页上的操作最终会写入这些字段并由 server/services/manager.go 在服务装配阶段据此构造对应的扩展客户端config.NewCombined/registry.NewWithExtension/secret.NewCombined端点均经过strings.TrimRight(endpoint, /)规范化。九、开发扩展的检查清单综合以上内容开发一个 Woodpecker 扩展服务的最小清单如下端点协议提供 HTTP POST 端点按扩展类型解析对应的RequestJSONRepo Pipeline [ Netrc] [ Configuration]并按类型返回configs/registries/secretsJSON不需要变更时返回204 No Content签名验证从http://my-woodpecker.tld/api/signature/public-key获取公钥用httpsign等库校验每个请求的request-target与content-digest签名幂等与超时请求可能被重试至多 3 次5xx/网络错误时处理逻辑需幂等响应应在 10 秒超时窗口内完成主机白名单若扩展部署在内网/本地记得通过WOODPECKER_EXTENSIONS_ALLOWED_HOSTS显式放行默认仅允许 external权限与信任牢记 forge 管理员等同于仓库扩展配置管理员在共享服务器上谨慎启用全局扩展配置生成安全配置扩展返回的 YAML 会被实际执行务必只生成可信内容。扩展体系的这三大组件让 Woodpecker 在不修改核心引擎的情况下即可对接企业自有的配置中心、凭据库与密钥管理基础设施是 Woodpecker“简单但强大、扩展性出色”定位的关键实现之一。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Akka Classic Extensions 扩展机制完全指南从自定义扩展到配置加载与库扩展Akka Classic Extensions 扩展机制完全指南从自定义扩展到配置加载与库扩展 Akka Extensions 是 Akka 提供的官方扩展机后端并发编程异步编程Woodpecker 扩展机制完全指南用 HTTP 端点替换内部逻辑配置、注册表与密钥扩展Woodpecker 扩展机制完全指南用 HTTP 端点替换内部逻辑配置、注册表与密钥扩展 Woodpecker 允许通过预定义的 HTTP 端点将内部逻CI/CDDevOpsdeck.gl Layer Extensions 扩展机制完全指南从 deck.gl/extensions 内置扩展到自定义扩展开发deck.gl Layer Extensions 扩展机制完全指南从 deck.gl/extensions 内置扩展到自定义扩展开发 deck.gl/ex前端数据可视化3D渲染图形学上一篇Qt Go蓝牙通信bluetooth模块设备发现与数据传输下一篇effect-smol HttpApi 中间件认证、授权与安全完全指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考