Woodpecker Forge 对接完全指南：GitHub、Gitea、GitLab 等六类代码托管平台配置与能力对比

CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本篇指南以 Woodpecker CI/CD 引擎当前文档对应 v2.8 版本线内置的 Forge代码托管平台驱动体系为线索系统讲解如何将 Woodpecker Server 与 GitHub、Gitea、Forgejo、GitLab、Bitbucket Cloud、Bitbucket Datacenter 六类 Forge 对接从 OAuth 应用注册、环境变量配置到各平台能力差异矩阵。读完本文你将能按需为实例选择并配置正确的 Forge 驱动理解 Webhook 回环、Agent 网络连通性等关键坑点并了解如何通过 Addon Forge 扩展官方未覆盖的平台。Forge 在 Woodpecker 中的角色Woodpecker 是采用Server / Agent 分离架构的 CI/CD 引擎Server 负责与代码托管平台Forge通信、接收 Webhook、调度流水线Agent 负责实际执行构建。这里所说的 Forge指的就是 Server 对接的代码托管平台——它是 Woodpecker 感知推送到仓库、创建 PR、打 Tag、发布 Release等事件并触发流水线的唯一入口。Woodpecker 内置了六类 Forge 驱动官方管理文档集中在docs/versioned_docs/version-2.8/30-administration/11-forges/目录驱动说明GitHub支持 GitHub 与 GitHub EnterpriseGitea支持自托管 GiteaForgejoForgejo 支持仍处于实验阶段GitLab支持 GitLab 8.2 及以上版本Bitbucket支持 Bitbucket CloudBitbucket Datacenter支持 Bitbucket Datacenter / Server原 Atlassian Stash实验阶段若以上平台均不满足需求还可以编写 Addon Forge 扩展后文有专门小节说明。Forge 功能对比矩阵不同 Forge 对 Woodpecker 功能特性的支持程度并不一致。官方在 11-overview.md 中给出了完整的支持矩阵这是选型时必须先看的表FeatureGitHubGiteaForgejoGitlabBitbucketBitbucket DatacenterEvent: Push✅✅✅✅✅✅Event: Tag✅✅✅✅✅✅Event: Pull-Request✅✅✅✅✅✅Event: Release✅✅✅✅❌❌Event: Deploy✅❌❌❌❌❌Multiple workflows✅✅✅✅✅✅when.path filter✅✅✅✅❌❌几点解读事件支持六类 Forge 都支持 Push、Tag、Pull-Request 三种基础事件Release 事件仅在 GitHub、Gitea、Forgejo、GitLab 上可用Deploy 事件是 GitHub 独有能力Gitea、Forgejo、GitLab、Bitbucket 系均不支持。多工作流所有 Forge 均支持 Multiple workflows。when.path过滤GitHub、Gitea、Forgejo、GitLab 支持按变更文件路径过滤流水线Bitbucket Cloud 与 Bitbucket Datacenter 不支持详见 workflow syntax 中的 path 一节。官方在 Bitbucket 文档中明确表示欢迎社区提交补丁补齐该功能。对接前的通用认知OAuth 与回调地址六类 Forge 的对接方式高度一致先在平台侧注册一个OAuth 应用拿到client id部分平台叫 Key与client secret再通过环境变量注入 Woodpecker Server 容器。所有平台的Authorization callback URL 均统一为https://your-woodpecker-instance/authorize回调路径/authorize是 Woodpecker Server 内置的 OAuth 回调端点。注册时必须保证回调 URL 的 http(s) scheme 与主机名和真实访问地址完全一致否则授权流程会失败。以下各节按官方文档顺序给出每个平台的完整配置清单。对接 GitHub 与 GitHub EnterpriseWoodpecker 内置对 GitHub 与 GitHub Enterprise 的支持。为 Server 组件设置以下环境变量即可启用WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTYOUR_GITHUB_CLIENT_ID WOODPECKER_GITHUB_SECRETYOUR_GITHUB_CLIENT_SECRET注册 OAuth 应用Client ID 与 Client Secret 来自 GitHub 的 OAuth 应用注册进入Settings - Developer Settings - GitHub Apps - New Oauth2 App创建。关键字段Name任意应用名称Homepage URL你的 Woodpecker 实例地址Callback URLhttps://your-woodpecker-instance/authorize可选上传 Woodpecker Logo 作为应用图标。创建完成后在应用详情页生成Client Secret将该值填入WOODPECKER_GITHUB_SECRET。重要警告不要用 GitHub App 代替 OAuth2 App——GitHub App 目前无法与 Woodpecker 正确协同其用户访问令牌不会自动刷新。GitHub 完整配置项环境变量默认值作用WOODPECKER_GITHUBfalse启用 GitHub 驱动WOODPECKER_GITHUB_URLhttps://github.com配置 GitHub 服务器地址自建 GitHub Enterprise 时改为企业实例地址WOODPECKER_GITHUB_CLIENT空GitHub OAuth client id用于授权访问WOODPECKER_GITHUB_CLIENT_FILE空从指定文件路径读取WOODPECKER_GITHUB_CLIENT的值适合密钥文件挂载场景WOODPECKER_GITHUB_SECRET空GitHub OAuth client secret用于授权访问WOODPECKER_GITHUB_SECRET_FILE空从指定文件路径读取WOODPECKER_GITHUB_SECRET的值WOODPECKER_GITHUB_MERGE_REFtrue是否使用 merge ref合并引用触发构建WOODPECKER_GITHUB_SKIP_VERIFYfalse是否跳过 SSL 证书校验自签名证书场景WOODPECKER_GITHUB_PUBLIC_ONLYfalse仅申请可管理公共仓库的 OAuth token其中WOODPECKER_GITHUB_MERGE_REF与WOODPECKER_GITHUB_PUBLIC_ONLY两个选项在源码装配层面对应github.Opts中的MergeRef与OnlyPublic字段见 server/forge/setup/setup.go#L143-L168默认均按false处理。对接 Gitea启用 Gitea 需要如下环境变量WOODPECKER_GITEAtrue WOODPECKER_GITEA_URLYOUR_GITEA_URL WOODPECKER_GITEA_CLIENTYOUR_GITEA_CLIENT WOODPECKER_GITEA_SECRETYOUR_GITEA_CLIENT_SECRETGitea 与容器同主机时的网络配置若 Gitea 与 Woodpecker Agent 运行在同一台宿主机的容器中必须保证 Agent 能访问到 Gitea。Agent 使用Gitea 通过 API 上报的克隆 URL来拉取代码因此最稳妥的做法是把 Woodpecker Agent 加入 Gitea 所在的 Docker 网络否则通信需经docker0网关通常是172.17.0.1。若网络名为gitea在 docker-compose 中为 agent 增加version: 3 services: [...] woodpecker-agent: [...] environment: - [...] - WOODPECKER_BACKEND_DOCKER_NETWORKgitea注册 OAuth 应用在 Gitea 的https://gitea.host/user/settings/中找到 OAuth applications 设置并注册应用。回调 URL 必须与 http(s) scheme、主机名完全一致路径为https://host/authorize。如果 Woodpecker Server 与 Gitea 同主机运行自 Giteav1.16起还需在 Gitea 配置中允许本地连接通常位于/etc/gitea/conf/app.ini否则 Webhook 会发送失败[webhook] ALLOWED_HOST_LISTexternal,loopbackGitea 完整配置项环境变量默认值作用WOODPECKER_GITEAfalse启用 Gitea 驱动WOODPECKER_GITEA_URLhttps://try.gitea.io配置 Gitea 服务器地址WOODPECKER_GITEA_CLIENT空Gitea OAuth client id用于授权访问WOODPECKER_GITEA_CLIENT_FILE空从文件读取WOODPECKER_GITEA_CLIENT的值WOODPECKER_GITEA_SECRET空Gitea OAuth client secret用于授权访问WOODPECKER_GITEA_SECRET_FILE空从文件读取WOODPECKER_GITEA_SECRET的值WOODPECKER_GITEA_SKIP_VERIFYfalse是否跳过 SSL 校验高级选项环境变量默认值作用WOODPECKER_DEV_GITEA_OAUTH_URLWOODPECKER_GITEA_URL的值配置面向用户的 Gitea 地址。当WOODPECKER_GITEA_URL指向仅用于 API 请求的内网地址时使用后一个选项在源码中对应gitea.Opts的OAuthHost字段见 server/forge/setup/setup.go#L70-L95实现API 走内网、用户授权跳转走公网的分离。对接 ForgejoForgejo 支持当前仍标记为experimental实验性。启用方式与 Gitea 几乎一致WOODPECKER_FORGEJOtrue WOODPECKER_FORGEJO_URLYOUR_FORGEJO_URL WOODPECKER_FORGEJO_CLIENTYOUR_FORGEJO_CLIENT WOODPECKER_FORGEJO_SECRETYOUR_FORGEJO_CLIENT_SECRET容器同主机时的网络配置、注册步骤与 Webhook 回环放行逻辑与 Gitea 相同把 Agent 加入 Forgejo 所在 Docker 网络并在 Forgejo 配置通常/etc/forgejo/conf/app.ini中允许本地 Webhook[webhook] ALLOWED_HOST_LISTexternal,loopbackForgejo 完整配置项环境变量默认值作用WOODPECKER_FORGEJOfalse启用 Forgejo 驱动WOODPECKER_FORGEJO_URLhttps://next.forgejo.org配置 Forgejo 服务器地址WOODPECKER_FORGEJO_CLIENT空Forgejo OAuth client idWOODPECKER_FORGEJO_CLIENT_FILE空从文件读取 client idWOODPECKER_FORGEJO_SECRET空Forgejo OAuth client secretWOODPECKER_FORGEJO_SECRET_FILE空从文件读取 client secretWOODPECKER_FORGEJO_SKIP_VERIFYfalse是否跳过 SSL 校验对接 GitLabWoodpecker 支持GitLab 8.2 及以上版本。启用配置示例WOODPECKER_GITLABtrue WOODPECKER_GITLAB_URLhttp://gitlab.mycompany.com WOODPECKER_GITLAB_CLIENT95c0282573633eb25e82 WOODPECKER_GITLAB_SECRET30f5064039e6b359e075注册应用与授权范围在 GitLab 账户设置中选择Applications点击New Application创建应用Authorization callback URLhttp://woodpecker.mycompany.com/authorize与实例实际地址一致Scope授权范围必须授予api。私有网络场景的额外配置若 Woodpecker Server 运行在私有 IPRFC1918 地址上或 GitLab 使用了非标准 TLD如.local、.internGitLab 默认会拒绝来自本地网络的 API 请求。此时需进入 GitLab Admin 面板的Settings Network Outbound requests开启Allow requests to the local network from web hooks and services。GitLab 完整配置项环境变量默认值作用WOODPECKER_GITLABfalse启用 GitLab 驱动WOODPECKER_GITLAB_URLhttps://gitlab.com配置 GitLab 服务器地址自托管实例改为内部地址WOODPECKER_GITLAB_CLIENT空GitLab OAuth client idWOODPECKER_GITLAB_CLIENT_FILE空从文件读取 client idWOODPECKER_GITLAB_SECRET空GitLab OAuth client secretWOODPECKER_GITLAB_SECRET_FILE空从文件读取 client secretWOODPECKER_GITLAB_SKIP_VERIFYfalse是否跳过 SSL 校验对接 Bitbucket Cloud启用 Bitbucket Cloud 需要WOODPECKER_BITBUCKETtrue WOODPECKER_BITBUCKET_CLIENT... # 在 Bitbucket 中称为 Key WOODPECKER_BITBUCKET_SECRET...注册 OAuth Consumer在 Bitbucket 的 workspace settings 中选择OAuth consumers点击Add Consumer地址形如https://bitbucket.org/[your-project-name]/workspace/settings/api。设置名称与回调地址https://your-woodpecker-address/authorize必须勾选的权限请务必为 Consumer 勾选以下权限否则 Woodpecker 无法完整读取仓库信息与接收 WebhookAccountEmail、ReadWorkspace membershipReadProjectsReadRepositoriesReadPull requestsReadWebhooksRead and WriteBitbucket Cloud 完整配置项环境变量默认值作用WOODPECKER_BITBUCKETfalse启用 Bitbucket 驱动WOODPECKER_BITBUCKET_CLIENT空Bitbucket OAuth client key即 Consumer KeyWOODPECKER_BITBUCKET_CLIENT_FILE空从文件读取 client keyWOODPECKER_BITBUCKET_SECRET空Bitbucket OAuth client secretWOODPECKER_BITBUCKET_SECRET_FILE空从文件读取 client secret已知缺失功能Bitbucket 目前不支持 PR 的 path 过滤即when.path对 Pull Request 场景无效。官方欢迎社区提交补丁补齐该能力。对接 Bitbucket Datacenter / ServerBitbucket Datacenter / Server原 Atlassian Stash支持同样标记为experimental。在 docker-compose 中通过以下环境变量启用注意变量名带_DC后缀且多了 Git 账号配置version: 3 services: woodpecker-server: [...] environment: - [...] - WOODPECKER_BITBUCKET_DCtrue - WOODPECKER_BITBUCKET_DC_GIT_USERNAMEfoo - WOODPECKER_BITBUCKET_DC_GIT_PASSWORDbar - WOODPECKER_BITBUCKET_DC_CLIENT_IDxxx - WOODPECKER_BITBUCKET_DC_CLIENT_SECRETyyy - WOODPECKER_BITBUCKET_DC_URLhttp://stash.mycompany.com woodpecker-agent: [...]服务账号Service Account机制Woodpecker 使用githttps协议克隆仓库而Bitbucket Server 目前不支持用 OAuth token 克隆仓库。因此必须创建一个服务账号Service Account将其用户名与密码交给 Woodpecker用于克隆私有仓库时认证。这正是WOODPECKER_BITBUCKET_DC_GIT_USERNAME/WOODPECKER_BITBUCKET_DC_GIT_PASSWORD存在的意义缺少任一值驱动装配会直接报错源码中分别以missing git-username、missing git-password返回错误见 server/forge/setup/setup.go#L170-L178。注册 Incoming Link在 Bitbucket Datacenter / Server 的管理后台选择Application Links点击Create link将 Woodpecker 登记为External Application方向direction设为Incomming。记下注册生成的 client id 与 client secret填入 Woodpecker 配置。Bitbucket Datacenter 完整配置项环境变量默认值作用WOODPECKER_BITBUCKET_DCfalse启用 Bitbucket Server 驱动WOODPECKER_BITBUCKET_DC_URL空配置 Bitbucket Server 地址WOODPECKER_BITBUCKET_DC_CLIENT_ID空Bitbucket Server OAuth 2.0 client idWOODPECKER_BITBUCKET_DC_CLIENT_SECRET空Bitbucket Server OAuth 2.0 client secretWOODPECKER_BITBUCKET_DC_GIT_USERNAME空用于认证并克隆所有私有仓库的用户名WOODPECKER_BITBUCKET_DC_GIT_USERNAME_FILE空从文件读取 git 用户名WOODPECKER_BITBUCKET_DC_GIT_PASSWORD空用于认证并克隆所有私有仓库的密码WOODPECKER_BITBUCKET_DC_GIT_PASSWORD_FILE空从文件读取 git 密码WOODPECKER_BITBUCKET_DC_SKIP_VERIFYfalse是否跳过 SSL 校验从源码看 Forge 驱动如何被装配阅读当前仓库源码 server/forge/setup/setup.go 可以印证上述配置的真实装配逻辑。该文件是 Server 侧 Forge 驱动的统一工厂入口Forge()函数根据model.Forge的类型字段做分发switch forge.Type { case model.ForgeTypeAddon: return setupAddon(forge) case model.ForgeTypeGithub: return setupGitHub(forge) case model.ForgeTypeGitlab: return setupGitLab(forge) case model.ForgeTypeBitbucket: return setupBitbucket(forge) case model.ForgeTypeGitea: return setupGitea(forge) case model.ForgeTypeForgejo: return setupForgejo(forge) case model.ForgeTypeBitbucketDatacenter: return setupBitbucketDatacenter(forge) default: return nil, fmt.Errorf(forge not configured) }从中可以确认几个实现细节Gitea / Forgejo 的 URL 必填校验setupGitea与setupForgejo在URL为空时会分别返回WOODPECKER_GITEA_URL must be set、WOODPECKER_FORGEJO_URL must be set错误setup.go#L83-L84、setup.go#L110-L111因此这两个平台即使使用默认公共实例也建议显式设置 URL。URL 规范化Gitea / Forgejo 的 URL 会经url.Parse并TrimRight(/)去除尾部斜杠后再传给驱动。GitHub 的两个布尔选项merge-ref与public-only从AdditionalOptions中读取并映射到github.Opts.MergeRef/OnlyPublic对应环境变量WOODPECKER_GITHUB_MERGE_REF与WOODPECKER_GITHUB_PUBLIC_ONLY。Bitbucket DC 的强校验git-username、git-password、oauth-enable-project-admin-scope三个附加选项缺失或类型错误时直接装配失败说明该驱动对服务账号的依赖是硬性的。调试日志每个驱动装配都会输出包含url、oauth-host、skip-verify、oauth-client-id-set、oauth-client-secret-set等字段的 Debug 日志排查对接问题时可通过这些日志判断凭据是否成功注入。注意当前仓库源码基于更新的 v3 模块路径go.woodpecker-ci.org/woodpecker/v3变量语义与本文档v2.8 文档线保持一致部署时请以你所安装版本的官方文档为准。扩展为未覆盖的平台编写 Addon Forge如果所用平台不符合 Woodpecker 的 Forge 要求如平台能力过于特殊或你的场景过于定制化可以编写Addon Forge接入配置方式下载与版本匹配的 addon 二进制设置WOODPECKER_ADDON_FORGE/path/to/your/addon/forge/file容器场景建议将 addon 挂载到/opt/addons/。通信机制Addon 通过RPC与 Server 通信底层基于go-plugin库实现官方文档给出的是外部链接这里仅引用其机制描述。实现方式直接引入 Woodpecker 的 Go 包go.woodpecker-ci.org/woodpecker/woodpecker/v2让config类型实现server/forge包的Forge接口然后在main中调用go.woodpecker-ci.org/woodpecker/v2/server/forge/addon.Serve由它负责与 Server 建连package main import ( context net/http go.woodpecker-ci.org/woodpecker/v2/server/forge/addon forgeTypes go.woodpecker-ci.org/woodpecker/v2/server/forge/types go.woodpecker-ci.org/woodpecker/v2/server/model ) func main() { addon.Serve(config{}) } type config struct { }两点重要提醒摘自官方文档原文Addon Forge 仍为实验性实现可能随时变更必须信任所使用 addon 的作者——它能够接触授权码等敏感信息Bug 排查时先看日志区分责任组件addon 的日志带有特殊字段addon值为其文件名若问题出在 addon应到独立的 addon 仓库提 issue而不是主仓库。常见问题与排错要点汇总官方文档中反复强调的几个坑供对接时对照检查回调 URL 不一致/authorize路径前的 scheme 与主机名必须与用户实际访问 Woodpecker 的地址完全一致否则 OAuth 授权失败。Webhook 发不出去同主机部署Giteav1.16与 Forgejo在app.ini的[webhook]段设置ALLOWED_HOST_LISTexternal,loopbackGitLab私有 IP / 非标准 TLD 场景下在 Admin 的Settings Network Outbound requests开启允许本地网络请求。Agent 克隆不到代码容器同主机将 Agent 加入 Forge 所在 Docker 网络WOODPECKER_BACKEND_DOCKER_NETWORKnetwork否则通信只能绕行docker0网关。Bitbucket DC 克隆失败确认已配置服务账号WOODPECKER_BITBUCKET_DC_GIT_USERNAME/WOODPECKER_BITBUCKET_DC_GIT_PASSWORD因为 Bitbucket Server 不接受 OAuth token 克隆。凭据泄露风险*_FILE系列变量如WOODPECKER_GITHUB_SECRET_FILE允许将 client secret 从外部文件读取适合容器密钥挂载场景避免把敏感值写死在环境变量里。小结Woodpecker 通过统一的环境变量约定和一致的/authorize回调机制让 GitHub、Gitea、Forgejo、GitLab、Bitbucket Cloud、Bitbucket Datacenter 六类代码托管平台都能在数分钟内完成对接。选型时应优先核对功能对比矩阵Release / Deploy 事件、when.path过滤是主要差异点部署时重点检查 OAuth 回调一致性、Webhook 回环放行与 Agent 网络连通性三个环节。深入 server/forge/setup/setup.go 的装配逻辑还能在出现 forge not configured 或missing git-username这类报错时快速定位根因。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Sourcebot配置教程连接GitHub、GitLab等代码托管平台的完整指南Sourcebot配置教程连接GitHub、GitLab等代码托管平台的完整指南 想要在多个代码仓库中快速搜索代码Sourcebot作为开源的SourcegOneDev vs GitLab轻量级自托管DevOps平台性能对比与选型指南OneDev vs GitLab轻量级自托管DevOps平台性能对比与选型指南 在当今DevOps工具选择中OneDev和GitLab都是优秀的自托管解决方后端开发工具DevOps代码托管CI/CD研发协作项目管理Soft Serve vs GitLab vs Gitea终极自托管Git服务器对比指南Soft Serve vs GitLab vs Gitea终极自托管Git服务器对比指南 在当今软件开发领域选择合适的自托管Git服务器至关重要。Soft代码托管后端上一篇JSX-Email最佳实践性能优化、可访问性与安全考量下一篇RVC 语音转换完整教程用 10 分钟音频训练可用音色克隆模型创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考