CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载:::info 导读 本文围绕 Woodpecker 对 Bitbucket Datacenter / Server前身为 Atlassian Stash的实验性支持讲解从环境变量配置、Service Account 创建、OAuth 2.0 应用注册到组织级权限PROJECT_ADMINscope的完整接入流程。读完本文你将掌握如何在 Woodpecker 中启用bitbucket_dc驱动、理解 Git 机器账号与 OAuth 凭证各自的分工并知晓该集成当前的功能边界与源码层面的实现依据。 :::概览为什么 Bitbucket Server 需要一套特殊的接入方式Bitbucket Datacenter / Server 是 Atlassian 提供的企业版自托管 Git 托管平台。Woodpecker 通过 server/forge/bitbucketdatacenter 下的驱动与其集成驱动内部基于github.com/neticdk/go-bitbucket客户端库调用 Bitbucket Server 的 REST API。从源码看该驱动有几个鲜明特点驱动注册名为bitbucket_dc见 bitbucketdatacenter.go 的Name()方法对应模型层枚举ForgeTypeBitbucketDatacenterserver/model/forge.go与 Bitbucket Cloud 不同Server 版不支持用 OAuth Token 直接 clone 仓库因此驱动强制要求配置独立的 Git 机器账号Service Account并在New()时校验其必须存在bitbucketdatacenter.go该驱动目前标记为实验性官方文档明确提示功能仍在完善中。接入前请注意适用前提Bitbucket Server 必须已安装且可从 Woodpecker 服务端网络访问Woodpecker 的 Bitbucket 集成是服务端驱动模式由 woodpecker-server 直接调用 Bitbucket 的 REST APIurl/rest与 OAuth 2.0 端点完成登录、webhook 与构建状态上报。快速启用docker-compose 环境变量启用 Bitbucket Server 驱动只需在 woodpecker-server 容器中追加以下环境变量官方文档示例变量名中DC即 Datacenterservices: 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_BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMINtrue woodpecker-agent: [...]其中WOODPECKER_BITBUCKET_DCtrue启用该 Forge 驱动默认falseWOODPECKER_BITBUCKET_DC_URLBitbucket Server 的地址如http://stash.mycompany.com驱动会基于它拼接 API 端点四组CLIENT_ID/CLIENT_SECRET、GIT_USERNAME/GIT_PASSWORD分别对应 OAuth 2.0 应用与 Git 机器账号两者缺一不可ENABLE_OAUTH2_SCOPE_PROJECT_ADMIN可选功能开关见下文组织级权限一节。配置完成后重启 woodpecker-server 容器即可生效。若任一项必需值缺失驱动初始化会直接报错——这正是 server/forge/setup/setup.go 中setupBitbucketDatacenter()的强制校验逻辑缺失git-username/git-password/ 类型错误的 scope 开关都会返回error对应测试见 setup_test.go。Service Accountclone 私有仓库的专用凭据这是本集成最容易踩坑、也最关键的一步。Bitbucket Server 目前不支持使用 OAuth Token 克隆仓库而 Woodpecker 默认以githttps方式 clone。作为折衷方案你必须在 Bitbucket Server 上创建一个专用的服务账号Service Account / 机器账号为其授予对所有需要构建的私有仓库的读取clone权限将该账号的用户名、密码配置给 Woodpecker。驱动在每次构建的 clone 阶段会为仓库生成.netrc凭据文件见 bitbucketdatacenter.go 的Netrc()实现从 clone URL 提取主机名填入Login: username/Password: passwordGit 客户端凭此完成 HTTPS 认证。也正是因为该机制仓库会被视为始终私有见 convert.go 中IsSCMPrivate: true的注释说明Since we have to use Netrc it has to always be private驱动不再依赖 OAuth Token 做 clone 鉴权。注意Service Account 的密码会直接出现在 netrc 中请妥善保管并限制该账号权限仅授予必要的仓库读取权限。注册应用在 Bitbucket 中创建 Incoming Application LinkWoodpecker 的 Web 登录依赖 OAuth 2.0 授权码流程源码Login()通过AuthCodeURL跳转、Exchange换取 token见 bitbucketdatacenter.go。因此必须先在 Bitbucket Server 的管理界面注册进入 Bitbucket 管理后台选择Application Links点击Create link创建一个新的应用链接类型选择External Application方向选择Incoming创建完成后记录系统生成的client id与client secret填入 Woodpecker 的WOODPECKER_BITBUCKET_DC_CLIENT_ID/WOODPECKER_BITBUCKET_DC_CLIENT_SECRET。官方文档同时给出了 Atlassian 的《Configure an incoming link》参考链接建议按其中的回调地址规范配置Woodpecker 侧的回调地址为{WOODPECKER_HOST}/authorize源码见newOAuth2Config()中RedirectURL: fmt.Sprintf(%s/authorize, server.Config.Server.OAuthHost)bitbucketdatacenter.go。OAuth 端点由驱动自动推导授权地址为{OAuthHost}/oauth2/latest/authorize令牌地址为{urlAPI}/oauth2/latest/token。当OAuthHost为空时默认回落到WOODPECKER_BITBUCKET_DC_URL。OAuth 流程完成后驱动会保存 access/refresh tokenupdateUserCredentialsconvert.go并通过Refresh()在令牌过期时自动续期bitbucketdatacenter.go。配置项全表逐个参数说明以下为官方文档列出的全部配置项。多数参数提供合理默认值可覆盖大部分安装场景URL、两对凭据为必填。环境变量默认值说明WOODPECKER_BITBUCKET_DCfalse启用 Bitbucket ServerDatacenter驱动WOODPECKER_BITBUCKET_DC_URL无配置 Bitbucket Server 的地址WOODPECKER_BITBUCKET_DC_CLIENT_ID无配置 OAuth 2.0 client idIncoming Application Link 生成WOODPECKER_BITBUCKET_DC_CLIENT_SECRET无配置 OAuth 2.0 client secretWOODPECKER_BITBUCKET_DC_GIT_USERNAME无用于认证并 clone 所有私有仓库的机器账号用户名WOODPECKER_BITBUCKET_DC_GIT_USERNAME_FILE无从指定文件路径读取GIT_USERNAME的值WOODPECKER_BITBUCKET_DC_GIT_PASSWORD无用于认证并 clone 所有私有仓库的机器账号密码WOODPECKER_BITBUCKET_DC_GIT_PASSWORD_FILE无从指定文件路径读取GIT_PASSWORD的值WOODPECKER_BITBUCKET_DC_SKIP_VERIFYfalse是否跳过 SSL 证书校验WOODPECKER_BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMINfalse启用后要求 Application Link 包含PROJECT_ADMINscope允许使用组织级 Secret 并正确列出组织仓库凭据文件化*_FILE 后缀生产环境中把机器账号密码直接写进环境变量并不理想。WOODPECKER_BITBUCKET_DC_GIT_USERNAME_FILE与WOODPECKER_BITBUCKET_DC_GIT_PASSWORD_FILE允许改为从文件读取敏感值——只需在文件中写入对应凭据并把环境变量指向该文件路径推荐挂载为只读 Secret 文件。这与 Woodpecker 其他 Forge 驱动的*_FILE约定保持一致便于对接 Docker Secret、Kubernetes Secret 或系统密钥管理。SKIP_VERIFY 的适用场景当 Bitbucket Server 使用自签名证书或内部 CA 时HTTPS 握手可能失败。此时可设WOODPECKER_BITBUCKET_DC_SKIP_VERIFYtrue跳过 SSL 校验。注意这会降低安全性存在中间人攻击风险仅在可信内网环境使用优先推荐为 Woodpecker 服务端正确配置受信任的 CA 证书。组织级权限PROJECT_ADMIN scope 的作用这是本集成中语义最微妙的开关。源码层面驱动默认只申请REPO_READ、REPO_WRITE、REPO_ADMIN三个 scope见newOAuth2Config()bitbucketdatacenter.go仅当WOODPECKER_BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMINtrue时才会追加PROJECT_ADMINscope同文件 L749-L751代码注释明确写了 TODO: Remove this feature flag in the next major version and always include project admin scope——即下一大版本将默认启用并移除开关若未启用该 scope驱动中依赖组织级权限的方法会直接拒绝实现hasProjectAdminAccess()相关逻辑在oauthEnableProjectAdminScope为 false 时返回不可用[bitbucketdatacenter.go](https://link.gitcode.com/i/52aff0c31da6fbb94e97340ae169cace#L659-L660 附近的注释This method cannot be implemented without the PROJECT_ADMIN scope included in the OAuth2 configuration。因此如果你的团队需要在 Bitbucket Datacenter 上使用组织级OrganizationSecret或希望驱动能完整列出组织下的仓库就必须在 Bitbucket 的 Application Link 中为 Woodpecker 添加PROJECT_ADMINscope将WOODPECKER_BITBUCKET_DC_ENABLE_OAUTH2_SCOPE_PROJECT_ADMIN设为true重新走一遍 OAuth 授权流程让已登录用户重新授权以获得新 scope。从源码实现看启用后驱动会在组织成员/组织仓库枚举时先检查当前用户是否为 Bitbucket project adminhasProjectAdminAccess通过Projects.SearchProjectPermissions探测bitbucketdatacenter.go若不具备项目管理员权限再回退检查其是否对组织内任一仓库拥有写权限hasRepositoryWriteAccess同文件 L696-L703以此决定可列出哪些组织及其仓库。功能边界与已知限制实验性提示结合源码与文档接入前请知悉以下边界clone 鉴权走 Service Account而非用户 OAuth Token因此所有私有仓库的 clone 权限取决于机器账号的授权范围而不是登录用户本身新仓库加入后需要确认机器账号有对应读取权限tag 类 Webhook 存在特殊处理源码注释指出 Bitbucket Data Center 在推送 annotated tag 时webhook 的ToHash是 tag 对象的 SHA 而非实际 commit SHA[bitbucketdatacenter.go](https://link.gitcode.com/i/52aff0c31da6fbb94e97340ae169cace#L562-L563 附近驱动已对此做了兼容处理webhook 事件覆盖驱动注册的 webhook 事件包括 refs 变更、PR opened / from / merged / declined / deleted 等同文件 L429-L436用于触发构建与状态回写IsSCMPrivate恒为 true由于 netrc 机制仓库访问模式被固定为私有公网公开仓库场景不受影响但所有仓库都会走机器账号凭据 clone驱动仍为实验特性官方文档明确标注 warning升级 Woodpecker 版本时请留意 CHANGELOG.md 中关于 bitbucket-dc 的变更说明如 scope 默认化的演进计划。参考路径速查官方配置文档docs/docs/30-administration/10-configuration/12-forges/60-bitbucket_datacenter.mdForge 驱动主实现server/forge/bitbucketdatacenter/bitbucketdatacenter.go驱动单元测试server/forge/bitbucketdatacenter/bitbucketdatacenter_test.go 与 convert_test.go驱动初始化与必填项校验server/forge/setup/setup.goForge 类型枚举server/model/forge.go赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker CI 集成 Bitbucket Datacenter / Server 完整指南环境变量配置、服务账号与 OAuth 2.0 注册Woodpecker CI 集成 Bitbucket Datacenter / Server 完整指南环境变量配置、服务账号与 OAuth 2.0 注册 本文CI/CDDevOpsWoodpecker 接入 Gitea 完整指南内置 Forge 驱动的启用、OAuth 注册与配置详解Woodpecker 接入 Gitea 完整指南内置 Forge 驱动的启用、OAuth 注册与配置详解 Woodpecker 对 Gitea 提供了开箱即用CI/CDDevOpsWoodpecker 集成 GitLab 完整指南Forge 驱动配置、OAuth 注册与权限模型解析Woodpecker 集成 GitLab 完整指南Forge 驱动配置、OAuth 注册与权限模型解析 Woodpecker CI/CD 内置对 GitLabCI/CDDevOps上一篇Cilium Standalone DNS Proxy 通信协议详解基于 gRPC 的 FQDN 策略下发与 DNS 映射回传机制下一篇DeepSearcher 向量数据库配置详解Milvus Lite、独立服务器与 Zilliz Cloud 的接入实践创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考