跳到主要内容

入门指南

您可以按照下面的步骤在本地计算机上进行开发，或者您可以使用 Gitpod 和 Gitea 开始使用完全准备好的在线设置。

Gitpod​

如果您想尽可能轻松地开始开发或更新文档，可以使用我们为 Woodpecker 预配置的 Gitpod 设置。Gitpod 在云中启动完整的开发设置，包含：

  • 浏览器中的 IDE 或桥接到您的本地 VS-Code 或 Jetbrains
  • 预配置的 Gitea 实例作为代码托管平台
  • 预配置的 Woodpecker 服务器
  • 单个预配置的 Woodpecker 代理节点
  • 我们的文档预览服务器

通过点击以下徽章在 Gitpod 中启动 Woodpecker。您可以使用 woodpecker 和 password 登录。

在 Gitpod 中打开

本地开发准备​

安装 Go​

按照此指南安装 Golang (>=1.20)。

安装 make​

GNU Make 是一个工具，它控制从程序源文件生成可执行文件和程序的其他非源文件（https://www.gnu.org/software/make/）。

在以下平台安装 make：

  • Ubuntu：apt install make - 文档
  • Windows
  • Mac OS：brew install make

安装 Node.js 和 pnpm​

如果您想构建 Woodpecker 的 UI 或文档，请安装 Node.js (>=20)。

对于 Woodpecker 的 UI 和文档的依赖项安装（node_modules），使用包管理器 pnpm。 此指南描述了 pnpm 的安装。

安装 pre-commit（可选）​

Woodpecker 使用 pre-commit 允许您轻松自动修复代码。 要在本地开发期间应用它，请查看 pre-commit 的文档。

创建包含开发配置的 .env 文件​

与您可以为 Woodpecker 生产设置设置的环境变量类似，您可以在 Woodpecker 项目的根目录中创建一个 .env 文件并向其添加任何需要的配置。

调试的常见配置如下所示：

WOODPECKER_OPEN=true
WOODPECKER_ADMIN=your-username

WOODPECKER_HOST=http://localhost:8000

# github（代码托管平台配置示例 - 其他代码托管平台请参见 /docs/administration/forge/overview）
WOODPECKER_GITHUB=true
WOODPECKER_GITHUB_CLIENT=<redacted>
WOODPECKER_GITHUB_SECRET=<redacted>

# agent
WOODPECKER_SERVER=localhost:9000
WOODPECKER_AGENT_SECRET=a-long-and-secure-password-used-for-the-local-development-system
WOODPECKER_MAX_WORKFLOWS=1

# 如果您想开发 UI，请启用
# WOODPECKER_DEV_WWW_PROXY=http://localhost:8010

# 如果您想使用像 GitHub 这样的在线代码托管平台测试 webhook，需要设置此地址并可从公共服务器访问
WOODPECKER_EXPERT_WEBHOOK_HOST=http://your-address.com

# 调试时禁用健康检查（开发时通常不需要）
WOODPECKER_HEALTHCHECK=false

# WOODPECKER_LOG_LEVEL=debug
# WOODPECKER_LOG_LEVEL=trace

设置 OAuth​

按照代码托管平台文档中的描述为您的代码托管平台创建 OAuth 应用程序。

使用 VS Code 开发​

您可以使用不同的方法来调试 Woodpecker 应用程序。目前推荐的调试和测试 Woodpecker 应用程序的方法之一是使用 VS-Code 或 VS-Codium（VS-Code 的开源二进制文件），因为大多数维护者都在使用它，并且 Woodpecker 已经包含了所需的调试配置。

要启动本地开发所需的所有服务，您可以使用"Woodpecker CI"调试配置，它将在调试模式下启动 UI、服务器和代理。然后打开 http://localhost:8000 访问它。

作为使用 VS Code 编程 Go 的入门指南，您可以使用此视频指南： 在 VS Code 中开始使用 Go

调试 Woodpecker​

Woodpecker 源代码已经包含了 Woodpecker 服务器和代理的启动配置。要开始调试，您可以点击 VS-Code 导航栏中的调试图标 (ctrl-shift-d)。在该页面上，您将在顶部看到现有的启动作业。只需选择代理或服务器并点击播放按钮。您可以在源文件中设置断点以在特定点停止。

使用 VS Code 调试 Woodpecker

测试和代码检查​

要测试或检查 Woodpecker 的部分内容，您可以运行以下命令之一：

# 测试服务器代码
make test-server

# 测试代理代码
make test-agent

# 测试 cli 代码
make test-cli

# 测试数据存储/数据库相关代码，如服务器的迁移
make test-server-datastore

# 检查 go 代码
make lint

# 检查 UI 代码
make lint-frontend

# 测试 UI 代码
make test-frontend

如果您想测试特定的 Go 文件，您也可以使用：

go test -race -timeout 30s go.woodpecker-ci.org/woodpecker/v3/<path-to-the-package-or-file-to-test>

或者您可以在 VS-Code 中打开测试文件，并通过点击内联命令运行或调试测试：

通过 VS-Code 运行测试

从终端运行应用程序​

如果您想从终端运行 Woodpecker 应用程序，可以从 Woodpecker 项目的基础目录使用以下命令之一。它们将以类似于调试 Woodpecker 中描述的方式执行 Woodpecker，但无法在编辑器中真正调试它。

启动服务器
go run ./cmd/server
启动代理
go run ./cmd/agent
执行 cli 命令
go run ./cmd/cli [command]