CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本文是 Woodpecker CI/CD 引擎开发入门指南面向想要参与 Woodpecker 开发或深入理解其架构的开发者。文章将带你完整走通本地开发环境的搭建流程安装 Go、make、Node.js 与 pnpm 等基础工具通过.env文件配置本地 Server、Agent 与 Forge 的 OAuth 连接并掌握 VS Code 断点调试、make测试与代码检查、以及从终端直接运行 Server/Agent/CLI 三大组件的全部方法。读完本文你将具备一套可复现的 Woodpecker 本地开发工作流并理解其配置项与源码实现之间的对应关系。图在 VS Code 中调试 Woodpecker 应用可在源码中设置断点进行逐步调试环境准备安装基础工具链Woodpecker 是一个 Go 编写、前端使用 Vue 3 的 CI/CD 引擎本地开发需要以下工具安装 GoGo 是编译和运行 Woodpecker 的核心语言按照官方安装指南安装对应平台的 Golang 即可。安装完成后建议确认版本与go.mod中要求的 Go 版本匹配仓库当前使用go.woodpecker-ci.org/woodpecker/v3作为模块路径。安装 makeGNU Make 用于从源码生成可执行文件Woodpecker 仓库的 Makefile 定义了测试、构建、发布等一系列目标日常开发几乎离不开它。各平台安装方式Ubuntuapt install makeWindows参考社区指引安装Makefile 中通过TARGETOS/TARGETARCH及BIN_SUFFIX处理了 Windows 下的.exe后缀见 MakefilemacOSbrew install make安装 Node.js 与 pnpm如果你要构建 Woodpecker 的 UI位于 web/或文档位于 docs/需要安装 Node.jsUI 和文档的依赖node_modules统一使用pnpm管理。这也是前端开发章节docs/docs/92-development/03-ui.md的前置条件。安装 pre-commit可选Woodpecker 使用pre-commit在本地开发时自动修复代码格式问题。可选安装按 pre-commit 官方文档配置后在提交前自动执行。创建.env开发配置Server 与 Agent 的环境变量与生产环境设置环境变量的方式类似你可以在 Woodpecker 项目根目录创建.env文件加入任何需要的配置。这个机制有源码级支撑server、agent、cli三个程序的main入口都会在启动时调用dot_env.Load()见 cmd/server/main.go、cmd/agent/main.go、cmd/cli/main.go其实现位于 shared/dot_env/dot_env.go若项目根目录存在.env文件就用godotenv将其加载为进程环境变量之后 urfave/cli 框架通过cli.EnvVars(...)读取。一个常见的调试配置如下WOODPECKER_OPENtrue WOODPECKER_ADMINyour-username WOODPECKER_HOSThttp://localhost:8000 # github (sample for a forge config - see /docs/administration/forge/overview for other forges) WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTredacted WOODPECKER_GITHUB_SECRETredacted # agent WOODPECKER_SERVERlocalhost:9000 WOODPECKER_AGENT_SECRETa-long-and-secure-password-used-for-the-local-development-system WOODPECKER_MAX_WORKFLOWS1 # enable if you want to develop the UI # WOODPECKER_DEV_WWW_PROXYhttp://localhost:8010 # if you want to test webhooks with an online forge like GitHub this address needs to be set and accessible from public server WOODPECKER_EXPERT_WEBHOOK_HOSThttp://your-address.com # disable health-checks while debugging (normally not needed while developing) WOODPECKER_HEALTHCHECKfalse # WOODPECKER_LOG_LEVELdebug # WOODPECKER_LOG_LEVELtrace下面对照源码逐一说明每个配置项的作用与取值建议配置项作用源码依据WOODPECKER_OPEN启用开放的用户注册open标志本地调试时允许新用户直接登录cmd/server/flags.goWOODPECKER_ADMIN管理员用户列表可指定多个用户cmd/server/flags.goWOODPECKER_HOSTServer 的完整外部 URL格式为scheme://host[/prefix path]本地调试指向http://localhost:8000cmd/server/flags.goWOODPECKER_GITHUB/WOODPECKER_GITHUB_CLIENT/WOODPECKER_GITHUB_SECRET启用 GitHub Forge 驱动并配置 OAuth2 Client ID/Secret。其余 ForgeGitea、Forgejo、GitLab、Bitbucket 等使用各自前缀的环境变量见 cmd/server/flags.go 与 Forge 总览文档cmd/server/flags.goWOODPECKER_SERVERAgent 连接的 gRPC 服务端地址默认值localhost:9000支持unix://前缀的 Unix Socketcmd/agent/core/flags.goWOODPECKER_AGENT_SECRETServer 与 Agent 共享的认证 Token可通过WOODPECKER_AGENT_SECRET_FILE指定从文件读取cmd/agent/core/flags.go、cmd/server/flags.goWOODPECKER_MAX_WORKFLOWSAgent 并行执行 workflow 的数量默认1别名WOODPECKER_MAX_PROCS本地调试保持 1 即可cmd/agent/core/flags.goWOODPECKER_DEV_WWW_PROXY开发模式下将非 API 请求代理到独立的前端 dev server如http://localhost:8010启用后无需每次改动 UI 都重新构建cmd/server/flags.goWOODPECKER_EXPERT_WEBHOOK_HOSTForge 回调用的 Server 完整 URLscheme://host[/prefix path]若用公网 Forge 测试 Webhook 需设置为公网可达地址cmd/server/flags.goWOODPECKER_HEALTHCHECK是否启用健康检查端点默认true调试时通常无需关闭cmd/agent/core/flags.goWOODPECKER_LOG_LEVEL日志级别调试时可按需设为debug或trace—配置 Forge OAuth让本地实例能对接代码托管平台要在本地跑通完整的 CI 流程还需要为你的 Forge代码托管平台创建一个 OAuth App。请参考 Forges 总览文档 中对应的 Forge 章节GitHub、Gitea、Forgejo、GitLab、Bitbucket、Bitbucket DataCenter 均有各自的配置文档把生成的 Client ID 与 Secret 填入.env的WOODPECKER_GITHUB_CLIENT/WOODPECKER_GITHUB_SECRET或其他 Forge 的对应变量中。需要注意的是目前通过环境变量只能配置一个Forge启用多个 Forge 驱动并不会创建多个 Forge其余 Forge 需要由管理员在 UI 的Settings - Forges中添加该特性仍处于实验阶段官方文档明确提示不要在公开或不可信环境使用。使用 VS Code 调试 Woodpecker调试 Woodpecker 应用有多种方式目前社区推荐使用 VS Code 或 VS CodiumVS Code 的开源二进制发行版因为多数维护者都在使用且仓库已内置了所需的调试配置。一键启动完整开发环境在 VS Code 中选择Woodpecker CI调试配置它会以调试模式同时启动 UI、Server 和 Agent 三个服务随后访问http://localhost:8000即可打开界面。首次使用 Go 进行 VS Code 开发可以参考官方的 Go in VS Code 入门视频教程。单点调试 Server 或 Agent源码仓库中已包含 Server 与 Agent 的 launch 配置。点击 VS Code 导航栏的调试图标快捷键ctrl-shift-d在页面顶部的启动任务列表中选择agent或server点击播放按钮即可启动调试在源码文件中设置断点程序就会在指定位置暂停方便逐行检查状态。图在 VS Code 中直接运行或调试测试文件的内联命令测试与代码检查make 目标与单测命令Woodpecker 在 Makefile 中为不同组件提供了独立的测试与 lint 目标make test-servermake test-agentmake test-climake test-server-datastoremake lintmake lint-frontendmake test-frontend对照源码可以看到这些目标的实际行为test-server运行go test -race -cover -timeout 60s覆盖cmd/server与server/...下除store之外的所有包Makefiletest-agent覆盖cmd/agent与agent/...Makefiletest-cli覆盖cmd/cli与cli/...Makefiletest-server-datastore会先以串行方式-p 1运行迁移测试TestMigrate因为迁移测试会重置共享数据库再跳过迁移测试运行其余 datastore 测试Makefilelint使用 golangci-lint未安装时会自动用go run拉取固定版本v2.12.2见 Makefile前端相关目标lint-frontend、test-frontend会先执行pnpm install --frozen-lockfile再在web/目录下运行 pnpm 的 lint/format/typecheck/test 脚本Makefile、Makefile。测试单个 Go 文件或包如果只想测试某个具体的 Go 文件可以直接使用go test指定包路径go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v3/path-to-the-package-or-file-to-test也可以在 VS Code 中打开测试文件点击测试函数上方出现的内联命令直接运行或调试该测试见上图。从终端直接运行三大组件如果不依赖编辑器调试也可以从项目根目录直接运行各组件。它们以与调试模式等价的方式启动只是无法在编辑器中打断点go run ./cmd/servergo run ./cmd/agentgo run ./cmd/cli [command]三个程序的main函数都会先执行dot_env.Load()加载项目根目录的.env因此前述配置在终端运行时同样生效。从源码结构看cmd/server、cmd/agent、cmd/cli分别对应 Woodpecker 的三个二进制产物构建产物由 Makefile 的build-server/build-agent/build-cli目标输出到dist/目录Makefile与本地go run是同一套代码入口。常见问题与调试建议UI 热更新开发 UI 时不必反复pnpm build并重启 Server。在web/目录运行pnpm start启动带热重载的 UI dev server同时在.env中启用WOODPECKER_DEV_WWW_PROXYhttp://localhost:8010Server 会把非 API 请求代理到该 dev server原理详见 docs/docs/92-development/03-ui.md。Webhook 无法回调使用公网 Forge如 GitHub测试 Webhook 时WOODPECKER_EXPERT_WEBHOOK_HOST必须设置为公网可达的地址本地localhost无法被 Forge 服务器访问。日志定位问题调试阶段可临时取消注释WOODPECKER_LOG_LEVELdebug或trace获取更详细的运行日志对应 CLI 也存在--log-level与WOODPECKER_LOG_LEVEL的映射见 cmd/cli/docs.go。Agent 连接问题确认 Agent 的WOODPECKER_SERVER默认localhost:9000与 Server 的 gRPC 监听地址一致且WOODPECKER_AGENT_SECRET两边相同需要 TLS 时通过WOODPECKER_GRPC_SECURE开启cmd/agent/core/flags.go。至此一套完整的 Woodpecker 本地开发环境已经就绪你可以启动 Server Agent 跑通端到端流水线也可以在 VS Code 中打断点调试任意组件还可以通过make目标对改动进行测试与代码检查为向 Woodpecker 贡献代码做好了全部准备。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker CI 本地开发环境搭建、调试与测试完整指南Woodpecker CI 本地开发环境搭建、调试与测试完整指南 本文基于 Woodpecker 官方开发者指南 docs/docs/92 developmenCI/CDDevOpsWoodpecker 本地开发指南从环境搭建、VS Code 调试到测试与运行Woodpecker 本地开发指南从环境搭建、VS Code 调试到测试与运行 本篇指南基于 Woodpecker CI/CD 引擎 v3.16 官方开发文档CI/CDDevOpsWoodpecker CI/CD 本地开发环境搭建指南从 Gitpod 到 VS Code 的完整调试与测试流程Woodpecker CI/CD 本地开发环境搭建指南从 Gitpod 到 VS Code 的完整调试与测试流程 本篇指南以 Woodpecker 官方开发者CI/CDDevOps上一篇jq社区贡献指南如何参与jq开源项目开发下一篇2023终极设计系统工具深度评测构建可扩展设计语言的10大最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Woodpecker CI 本地开发环境搭建指南：从安装 Go 到调试 Server 与 Agent
CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载本文是 Woodpecker CI/CD 引擎开发入门指南面向想要参与 Woodpecker 开发或深入理解其架构的开发者。文章将带你完整走通本地开发环境的搭建流程安装 Go、make、Node.js 与 pnpm 等基础工具通过.env文件配置本地 Server、Agent 与 Forge 的 OAuth 连接并掌握 VS Code 断点调试、make测试与代码检查、以及从终端直接运行 Server/Agent/CLI 三大组件的全部方法。读完本文你将具备一套可复现的 Woodpecker 本地开发工作流并理解其配置项与源码实现之间的对应关系。图在 VS Code 中调试 Woodpecker 应用可在源码中设置断点进行逐步调试环境准备安装基础工具链Woodpecker 是一个 Go 编写、前端使用 Vue 3 的 CI/CD 引擎本地开发需要以下工具安装 GoGo 是编译和运行 Woodpecker 的核心语言按照官方安装指南安装对应平台的 Golang 即可。安装完成后建议确认版本与go.mod中要求的 Go 版本匹配仓库当前使用go.woodpecker-ci.org/woodpecker/v3作为模块路径。安装 makeGNU Make 用于从源码生成可执行文件Woodpecker 仓库的 Makefile 定义了测试、构建、发布等一系列目标日常开发几乎离不开它。各平台安装方式Ubuntuapt install makeWindows参考社区指引安装Makefile 中通过TARGETOS/TARGETARCH及BIN_SUFFIX处理了 Windows 下的.exe后缀见 MakefilemacOSbrew install make安装 Node.js 与 pnpm如果你要构建 Woodpecker 的 UI位于 web/或文档位于 docs/需要安装 Node.jsUI 和文档的依赖node_modules统一使用pnpm管理。这也是前端开发章节docs/docs/92-development/03-ui.md的前置条件。安装 pre-commit可选Woodpecker 使用pre-commit在本地开发时自动修复代码格式问题。可选安装按 pre-commit 官方文档配置后在提交前自动执行。创建.env开发配置Server 与 Agent 的环境变量与生产环境设置环境变量的方式类似你可以在 Woodpecker 项目根目录创建.env文件加入任何需要的配置。这个机制有源码级支撑server、agent、cli三个程序的main入口都会在启动时调用dot_env.Load()见 cmd/server/main.go、cmd/agent/main.go、cmd/cli/main.go其实现位于 shared/dot_env/dot_env.go若项目根目录存在.env文件就用godotenv将其加载为进程环境变量之后 urfave/cli 框架通过cli.EnvVars(...)读取。一个常见的调试配置如下WOODPECKER_OPENtrue WOODPECKER_ADMINyour-username WOODPECKER_HOSThttp://localhost:8000 # github (sample for a forge config - see /docs/administration/forge/overview for other forges) WOODPECKER_GITHUBtrue WOODPECKER_GITHUB_CLIENTredacted WOODPECKER_GITHUB_SECRETredacted # agent WOODPECKER_SERVERlocalhost:9000 WOODPECKER_AGENT_SECRETa-long-and-secure-password-used-for-the-local-development-system WOODPECKER_MAX_WORKFLOWS1 # enable if you want to develop the UI # WOODPECKER_DEV_WWW_PROXYhttp://localhost:8010 # if you want to test webhooks with an online forge like GitHub this address needs to be set and accessible from public server WOODPECKER_EXPERT_WEBHOOK_HOSThttp://your-address.com # disable health-checks while debugging (normally not needed while developing) WOODPECKER_HEALTHCHECKfalse # WOODPECKER_LOG_LEVELdebug # WOODPECKER_LOG_LEVELtrace下面对照源码逐一说明每个配置项的作用与取值建议配置项作用源码依据WOODPECKER_OPEN启用开放的用户注册open标志本地调试时允许新用户直接登录cmd/server/flags.goWOODPECKER_ADMIN管理员用户列表可指定多个用户cmd/server/flags.goWOODPECKER_HOSTServer 的完整外部 URL格式为scheme://host[/prefix path]本地调试指向http://localhost:8000cmd/server/flags.goWOODPECKER_GITHUB/WOODPECKER_GITHUB_CLIENT/WOODPECKER_GITHUB_SECRET启用 GitHub Forge 驱动并配置 OAuth2 Client ID/Secret。其余 ForgeGitea、Forgejo、GitLab、Bitbucket 等使用各自前缀的环境变量见 cmd/server/flags.go 与 Forge 总览文档cmd/server/flags.goWOODPECKER_SERVERAgent 连接的 gRPC 服务端地址默认值localhost:9000支持unix://前缀的 Unix Socketcmd/agent/core/flags.goWOODPECKER_AGENT_SECRETServer 与 Agent 共享的认证 Token可通过WOODPECKER_AGENT_SECRET_FILE指定从文件读取cmd/agent/core/flags.go、cmd/server/flags.goWOODPECKER_MAX_WORKFLOWSAgent 并行执行 workflow 的数量默认1别名WOODPECKER_MAX_PROCS本地调试保持 1 即可cmd/agent/core/flags.goWOODPECKER_DEV_WWW_PROXY开发模式下将非 API 请求代理到独立的前端 dev server如http://localhost:8010启用后无需每次改动 UI 都重新构建cmd/server/flags.goWOODPECKER_EXPERT_WEBHOOK_HOSTForge 回调用的 Server 完整 URLscheme://host[/prefix path]若用公网 Forge 测试 Webhook 需设置为公网可达地址cmd/server/flags.goWOODPECKER_HEALTHCHECK是否启用健康检查端点默认true调试时通常无需关闭cmd/agent/core/flags.goWOODPECKER_LOG_LEVEL日志级别调试时可按需设为debug或trace—配置 Forge OAuth让本地实例能对接代码托管平台要在本地跑通完整的 CI 流程还需要为你的 Forge代码托管平台创建一个 OAuth App。请参考 Forges 总览文档 中对应的 Forge 章节GitHub、Gitea、Forgejo、GitLab、Bitbucket、Bitbucket DataCenter 均有各自的配置文档把生成的 Client ID 与 Secret 填入.env的WOODPECKER_GITHUB_CLIENT/WOODPECKER_GITHUB_SECRET或其他 Forge 的对应变量中。需要注意的是目前通过环境变量只能配置一个Forge启用多个 Forge 驱动并不会创建多个 Forge其余 Forge 需要由管理员在 UI 的Settings - Forges中添加该特性仍处于实验阶段官方文档明确提示不要在公开或不可信环境使用。使用 VS Code 调试 Woodpecker调试 Woodpecker 应用有多种方式目前社区推荐使用 VS Code 或 VS CodiumVS Code 的开源二进制发行版因为多数维护者都在使用且仓库已内置了所需的调试配置。一键启动完整开发环境在 VS Code 中选择Woodpecker CI调试配置它会以调试模式同时启动 UI、Server 和 Agent 三个服务随后访问http://localhost:8000即可打开界面。首次使用 Go 进行 VS Code 开发可以参考官方的 Go in VS Code 入门视频教程。单点调试 Server 或 Agent源码仓库中已包含 Server 与 Agent 的 launch 配置。点击 VS Code 导航栏的调试图标快捷键ctrl-shift-d在页面顶部的启动任务列表中选择agent或server点击播放按钮即可启动调试在源码文件中设置断点程序就会在指定位置暂停方便逐行检查状态。图在 VS Code 中直接运行或调试测试文件的内联命令测试与代码检查make 目标与单测命令Woodpecker 在 Makefile 中为不同组件提供了独立的测试与 lint 目标make test-servermake test-agentmake test-climake test-server-datastoremake lintmake lint-frontendmake test-frontend对照源码可以看到这些目标的实际行为test-server运行go test -race -cover -timeout 60s覆盖cmd/server与server/...下除store之外的所有包Makefiletest-agent覆盖cmd/agent与agent/...Makefiletest-cli覆盖cmd/cli与cli/...Makefiletest-server-datastore会先以串行方式-p 1运行迁移测试TestMigrate因为迁移测试会重置共享数据库再跳过迁移测试运行其余 datastore 测试Makefilelint使用 golangci-lint未安装时会自动用go run拉取固定版本v2.12.2见 Makefile前端相关目标lint-frontend、test-frontend会先执行pnpm install --frozen-lockfile再在web/目录下运行 pnpm 的 lint/format/typecheck/test 脚本Makefile、Makefile。测试单个 Go 文件或包如果只想测试某个具体的 Go 文件可以直接使用go test指定包路径go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v3/path-to-the-package-or-file-to-test也可以在 VS Code 中打开测试文件点击测试函数上方出现的内联命令直接运行或调试该测试见上图。从终端直接运行三大组件如果不依赖编辑器调试也可以从项目根目录直接运行各组件。它们以与调试模式等价的方式启动只是无法在编辑器中打断点go run ./cmd/servergo run ./cmd/agentgo run ./cmd/cli [command]三个程序的main函数都会先执行dot_env.Load()加载项目根目录的.env因此前述配置在终端运行时同样生效。从源码结构看cmd/server、cmd/agent、cmd/cli分别对应 Woodpecker 的三个二进制产物构建产物由 Makefile 的build-server/build-agent/build-cli目标输出到dist/目录Makefile与本地go run是同一套代码入口。常见问题与调试建议UI 热更新开发 UI 时不必反复pnpm build并重启 Server。在web/目录运行pnpm start启动带热重载的 UI dev server同时在.env中启用WOODPECKER_DEV_WWW_PROXYhttp://localhost:8010Server 会把非 API 请求代理到该 dev server原理详见 docs/docs/92-development/03-ui.md。Webhook 无法回调使用公网 Forge如 GitHub测试 Webhook 时WOODPECKER_EXPERT_WEBHOOK_HOST必须设置为公网可达的地址本地localhost无法被 Forge 服务器访问。日志定位问题调试阶段可临时取消注释WOODPECKER_LOG_LEVELdebug或trace获取更详细的运行日志对应 CLI 也存在--log-level与WOODPECKER_LOG_LEVEL的映射见 cmd/cli/docs.go。Agent 连接问题确认 Agent 的WOODPECKER_SERVER默认localhost:9000与 Server 的 gRPC 监听地址一致且WOODPECKER_AGENT_SECRET两边相同需要 TLS 时通过WOODPECKER_GRPC_SECURE开启cmd/agent/core/flags.go。至此一套完整的 Woodpecker 本地开发环境已经就绪你可以启动 Server Agent 跑通端到端流水线也可以在 VS Code 中打断点调试任意组件还可以通过make目标对改动进行测试与代码检查为向 Woodpecker 贡献代码做好了全部准备。赞分享CI/CDDevOps【免费下载链接】woodpeckerWoodpecker is a simple, yet powerful CI/CD engine with great extensibility.项目地址https://gitcode.com/gh_mirrors/wo/woodpecker点击查看免费下载相关推荐Woodpecker CI 本地开发环境搭建、调试与测试完整指南Woodpecker CI 本地开发环境搭建、调试与测试完整指南 本文基于 Woodpecker 官方开发者指南 docs/docs/92 developmenCI/CDDevOpsWoodpecker 本地开发指南从环境搭建、VS Code 调试到测试与运行Woodpecker 本地开发指南从环境搭建、VS Code 调试到测试与运行 本篇指南基于 Woodpecker CI/CD 引擎 v3.16 官方开发文档CI/CDDevOpsWoodpecker CI/CD 本地开发环境搭建指南从 Gitpod 到 VS Code 的完整调试与测试流程Woodpecker CI/CD 本地开发环境搭建指南从 Gitpod 到 VS Code 的完整调试与测试流程 本篇指南以 Woodpecker 官方开发者CI/CDDevOps上一篇jq社区贡献指南如何参与jq开源项目开发下一篇2023终极设计系统工具深度评测构建可扩展设计语言的10大最佳实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
