CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载Forgejo 是一款开源的轻量级 Git 代码托管服务Woodpecker 内置了对它的原生驱动支持built-in Forgejo driver可以让你的 CI/CD 流水线直接对接自托管的 Forgejo 实例。本文以 Forgejo 官方配置文档 为核心骨架结合 Woodpecker 源码深入讲解如何通过环境变量启用 Forgejo 驱动、如何在同一主机上打通容器网络、如何注册用户级与系统级 OAuth 应用、以及全部 FORGEJO 配置项的含义与默认值。读完本文你将能独立完成 Woodpecker Server 与 Forgejo 的完整对接并理解驱动底层的工作原理与常见坑点。快速启用四个环境变量Woodpecker 对 Forgejo 的支持是内置的无需安装任何额外插件。在启动 Woodpecker Server 容器时只需配置下面四个环境变量即可启用WOODPECKER_FORGEJOtrue WOODPECKER_FORGEJO_URLYOUR_FORGEJO_URL WOODPECKER_FORGEJO_CLIENTYOUR_FORGEJO_CLIENT WOODPECKER_FORGEJO_SECRETYOUR_FORGEJO_CLIENT_SECRETWOODPECKER_FORGEJOtrue启用 Forgejo 驱动。对应源码中的forgejoCLI 开关见 cmd/server/flags.go该开关的 Sources 绑定环境变量WOODPECKER_FORGEJO。WOODPECKER_FORGEJO_URL你的 Forgejo 服务器地址。WOODPECKER_FORGEJO_CLIENT/WOODPECKER_FORGEJO_SECRET在 Forgejo 中注册 OAuth 应用后得到的 Client ID 与 Client Secret。从源码看Forgejo 驱动与其他 forgeGitHub、GitLab、Gitea 等共用一套通用的 oauth 配置解析链。在 cmd/server/flags.go 中forge-url、forge-oauth-client、forge-oauth-secret、forge-skip-verify等 Flag 都同时接受多个 forge 的环境变量来源其中就包括WOODPECKER_FORGEJO_*系列因此你也可以直接使用通用的WOODPECKER_FORGE_URL/WOODPECKER_FORGE_CLIENT/WOODPECKER_FORGE_SECRET。在服务端装配时server/forge/setup/setup.go的Forge()函数会依据模型中的ForgeTypeForgejo分支调用setupForgejo()见 setup.go它会解析forge.URL、去掉末尾多余的/并依次把 OAuth Client ID、Client Secret、SkipVerify与 OAuth Host 传入forgejo.Opts见 setup.go。其中OAuth2URL对应WOODPECKER_EXPERT_FORGE_OAUTH_HOST用于指定面向用户的 OAuth 地址若未设置驱动会自动回退到URL本身见 forgejo.go。如果WOODPECKER_FORGEJO_URL为空setupForgejo会直接返回错误WOODPECKER_FORGEJO_URL must be set对应测试见 setup_test.go。Forgejo 与 Woodpecker 容器同主机部署的网络联通如果你把 Forgejo 和 Woodpecker 都跑在同一台主机的容器里必须保证 Agent 能访问到 Forgejo。Agent 在克隆代码时使用的是 Forgejo 通过 API 上报的克隆 URL因此网络不通会导致克隆失败。官方推荐的两种做法把 Woodpecker Agent 加入 Forgejo 所在的 Docker 网络最稳妥。让通信走docker0网关通常为172.17.0.1。假设 Docker 网络名为forgejo在 docker-compose 中给 agent 增加网络配置services: [...] woodpecker-agent: [...] environment: - [...] - WOODPECKER_BACKEND_DOCKER_NETWORKforgejoWOODPECKER_BACKEND_DOCKER_NETWORK是 Agent 侧 Docker 后端pipeline/backend/docker使用的网络配置让 Agent 启动的流水线容器与 Forgejo 处于同一网络从而能解析并访问 Forgejo 容器这是容器化 CI 场景下最常见的联通方式。OAuth 应用注册用户级 OAuth 应用User OAuth Application在 Forgejo 中注册应用以获取 Client ID 与 Secret打开https://forgejo.host/user/settings/你的 Forgejo 实例的用户设置页进入 OAuth 应用管理。创建新的 OAuth 应用授权回调地址authorization callback URL必须与你的 http(s) 协议和主机名完全一致路径固定为/authorize即形如https://host/authorize。回调路径/authorize不是随意约定的驱动在构造 OAuth2 配置时RedirectURL被硬编码为fmt.Sprintf(%s/authorize, server.Config.Server.OAuthHost)见 forgejo.go同时授权端点与令牌端点分别由%s/login/oauth/authorize和%s/login/oauth/access_token拼装见 forgejo.go。回调地址写错例如混用 http/https、漏写主机名是集成失败的最常见原因。系统级 OAuth 应用System-wide OAuth Application如果你同时是 Forgejo 和 Woodpecker 的管理员可以优先考虑注册系统级站点级OAuth 应用而不是用户级应用。系统级应用在 Forgejo 站点管理员层面统一管理对所有用户可见。创建步骤打开站点管理设置https://forgejo.host/admin/settings/applications在 OAuth2 Applications 区域新建一个 OAuth2 应用配置方式与用户级应用一致回调地址等将生成的 Client ID 与 Secret 填入 Woodpecker 配置系统级应用特别适合以下场景共享 CI/CD 环境多个用户都需要访问同一个 Woodpecker需要集中管控 OAuth 应用的组织由管理员统一创建与吊销避免依赖某个个人账号规避用户级应用配额防止个人账号的应用数量配额影响 CI/CD 正常运行。本地连接Local Connections如果 Woodpecker CI Server 与 Forgejo 实例运行在同一台主机上你可能还需要允许 Forgejo 的本地连接否则webhook 会失败。在 Forgejo 配置文件通常位于/etc/forgejo/conf/app.ini中加入[webhook] ALLOWED_HOST_LISTexternal,loopback这里external允许外部主机loopback允许回环地址——当 Woodpecker Server 通过本地地址接收 Forgejo 推送的 webhook 时这一配置必不可少。⚠️API 分页大小警告请确保你的 Forgejo 配置允许以固定的每页 50 条记录请求 API。Forgejo 默认的最大页大小就是 50但如果你把该值调到了 50 以下Woodpecker 的部分功能将无法正常工作。这个警告在源码中有直接体现驱动内置常量defaultPageSize 50并在perPage()方法中通过GetGlobalAPISettings()读取 Forgejo 的MaxResponseItems作为实际分页大小见 forgejo.go在Teams、Repos、Org等列表接口中分页参数均以PageSize: c.perPage(ctx)的形式传入见 forgejo.go。一旦 Forgejo 服务端把最大页大小压到 50 以下列表类功能仓库列表、团队列表等就会因请求页大小超过服务端上限而失效。FORGEJO 配置项全集以下为 Woodpecker Server 中与 Forgejo 相关的全部配置选项。大多数选项都有合理的默认值适用于绝大多数安装场景带_FILE后缀的选项用于从文件中读取敏感值便于配合 Docker Secret 或 Kubernetes Secret 挂载。FORGEJO环境变量名WOODPECKER_FORGEJO默认值false启用 Forgejo 驱动。对应源码中forgejoCLI Flag仅监听WOODPECKER_FORGEJO这一个环境变量来源见 cmd/server/flags.go。FORGEJO_URL环境变量名WOODPECKER_FORGEJO_URL默认值https://next.forgejo.org配置 Forgejo 服务器地址。该值经 URL 解析并去除末尾斜杠后作为驱动内部url字段使用同时被用于拼装授权端点与令牌端点见 forgejo.go。若未设置setupForgejo会直接报错WOODPECKER_FORGEJO_URL must be set。FORGEJO_CLIENT环境变量名WOODPECKER_FORGEJO_CLIENT默认值无配置 Forgejo OAuth Client ID用于授权访问。源码中它属于forge-oauth-client的值来源链之一优先从WOODPECKER_FORGEJO_CLIENT_FILE指定文件读取其次取各 forge 的_CLIENT环境变量再回退到通用的WOODPECKER_FORGE_CLIENT见 cmd/server/flags.go。FORGEJO_CLIENT_FILE环境变量名WOODPECKER_FORGEJO_CLIENT_FILE默认值无从指定文件路径读取WOODPECKER_FORGEJO_CLIENT的值。适合用 Docker Secret / K8s Secret 挂载方式注入凭证避免把敏感信息直接写进环境变量或 docker-compose 文件。FORGEJO_SECRET环境变量名WOODPECKER_FORGEJO_SECRET默认值无配置 Forgejo OAuth Client Secret用于授权访问。解析优先级与 Client 类似WOODPECKER_FORGEJO_SECRET_FILE文件优先其次各 forge 的_SECRET再回退到通用WOODPECKER_FORGE_SECRET见 cmd/server/flags.go。FORGEJO_SECRET_FILE环境变量名WOODPECKER_FORGEJO_SECRET_FILE默认值无从指定文件路径读取WOODPECKER_FORGEJO_SECRET的值用途同FORGEJO_CLIENT_FILE。FORGEJO_SKIP_VERIFY环境变量名WOODPECKER_FORGEJO_SKIP_VERIFY默认值false配置是否跳过 SSL 证书校验。在驱动实现中该值被传入 OAuth2 HTTP Client 的tls.Config{InsecureSkipVerify: ...}见 forgejo.go。仅当你的 Forgejo 使用自签名证书、且你清楚跳过校验的风险时才建议开启生产环境应保持false。源码级的驱动工作方式补充说明除了文档明示的配置项外从源码可以进一步确认 Forgejo 驱动的几个关键实现事实帮助你理解整套对接链路驱动实体server/forge/forgejo/forgejo.go中定义了Forgejo结构体持有 url、oauth2URL、client id/secret、skipVerify、pageSize 等字段与Opts配置结构体New()负责实例化Name()返回驱动标识forgejo见 forgejo.go。OAuth 登录流程Login()先通过AuthCodeURL生成跳转地址收到回调后Exchange换取访问令牌再调用GetMyUserInfo拉取用户信息并组装model.User登录名、邮箱、头像等见 forgejo.goRefresh()负责令牌续期。令牌刷新Refresh使用 oauth2 配置刷新 access token刷新成功后同步更新用户记录保证长周期流水线任务不会因令牌过期而中断见 forgejo.go。克隆凭据netrc测试用例Test_forgejo验证了 netrc 行为——使用用户令牌时生成包含登录名与访问令牌的凭据使用机器账号machine account时则不带用户名密码见 forgejo_test.go这与文档中“Agent 按 Forgejo API 上报的 URL 克隆”的描述相互印证。结语对接 Woodpecker 与 Forgejo 的核心就三件事配好四个环境变量、注册回调路径为/authorize的 OAuth 应用、保证 Agent 与 Forgejo 网络互通。在此基础上善用_FILE系列环境变量注入凭证、保持 Forgejo API 最大页大小不低于 50、按需开启系统级 OAuth 应用即可获得稳定、可扩展的自托管 CI/CD 体验。若在配置过程中遇到驱动行为疑问可直接查阅 server/forge/forgejo/forgejo.go 及其测试文件 forgejo_test.go所有配置项均有对应的解析与装配逻辑可循。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker CI 与 Gitea 集成配置完整指南OAuth 应用注册、容器网络与全部环境变量详解Woodpecker CI 与 Gitea 集成配置完整指南OAuth 应用注册、容器网络与全部环境变量详解 Woodpecker CI 内置了对 GiteaCI/CDDevOpsWoodpecker CI 接入 Forgejo 完全指南OAuth 注册、容器网络配置与参数详解Woodpecker CI 接入 Forgejo 完全指南OAuth 注册、容器网络配置与参数详解 Forgejo 是一款开源自托管的轻量级 Git 服务WCI/CDDevOpsSanity Studio 诊断数据查看器从 Diagnostics 面板到纯前端 JSON 解析报告Sanity Studio 诊断数据查看器从 Diagnostics 面板到纯前端 JSON 解析报告 导读 Studio diagnostics vieweCI/CDDevOps上一篇Windows系统清理终极指南Win11Debloat让你的电脑飞起来下一篇Snap.Hutao版本更新持续迭代与功能增强策略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考