woodpecker-ci

Woodpecker CI

将此技能用作操作手册，而不是替代对已安装主版本文档的查阅。优先使用明确的 SemVer 镜像标签；启动服务前验证解析后的配置；每次更改后验证运行状况。

范围边界： 此技能用于配置和操作 Woodpecker CI（服务器、代理、工作流和集成）。它不会安装或管理 Forgejo/Gitea 本身，也不会配置 Forgejo Actions 运行器。任务提及 Forgejo 时，除非明确要求管理 Forge，否则应将其视为 Woodpecker 连接的代码托管平台。

操作流程

1. 确定 Woodpecker 主版本、代码托管平台、后端、部署文件、数据库、公共 URL，以及任务属于设置、流水线还是故障处理。
2. 更改配置前，阅读下方相应的参考文档。
3. 启动服务器或代理前，渲染并检查配置。
4. 在负责问题的层面进行最小更改：代码托管平台/OAuth、服务器、代理/后端或仓库工作流。
5. 在下一个边界验证结果：服务器健康状态、代理连接状态、仓库 Webhook、流水线调度、步骤日志和外部部署端点。
6. 记录确切版本和相关环境变量，但不要记录机密值。

选择入口

如果任务是……	从这里开始
新建服务器/代理或连接代码托管平台	references/setup.md
工作流 YAML、服务、条件、机密或插件	references/pipeline-syntax.md
升级、备份、指标、CLI 或容量	references/operations.md 和 references/advanced-patterns.md
登录、排队中的流水线、克隆、步骤或后端故障	references/troubleshooting.md 和 references/failure-signatures.md
信任或多租户决策	references/security.md 和 references/setup.md 中的后端部分
本地 lint/exec 或 CLI 安装	references/cli.md

然后，在需要确认与版本相关的命令或变量时，加载 references/source-index.md。

快速命令卡

# Generate a shared server/agent secret
openssl rand -hex 32

# Compose Woodpecker server + agent (not Forgejo itself)
cp templates/docker-compose.yml compose.yaml
cp templates/forgejo.env.example .env
# edit .env, then:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs -f --tail=100 woodpecker-server woodpecker-agent

# Local workflow checks
woodpecker-cli lint .woodpecker.yml
woodpecker-cli exec .woodpecker.yml

# Pipeline and secret administration
woodpecker-cli repo info --repository OWNER/REPO
woodpecker-cli repo secret add --repository OWNER/REPO --name NAME --value @/path/to/value

woodpecker-cli exec 可用于本地命令和元数据检查，但不能完全替代服务器运行：本地可能无法使用服务器管理的机密和代码托管平台事件。

核心默认设置

• 对于隔离的容器步骤，使用 Docker 后端。Docker socket 权限很大：应将 Agent 主机视为 CI 信任边界。
• 使用 Kubernetes 后端实现每个步骤独立使用一个 Pod 的隔离和集群调度；在允许仓库作者设置后端选项之前，应检查服务账户、命名空间边界、拉取密钥、PVC/存储和资源请求。

多租户默认设置： 对于不受信任的仓库，如果集群已作为安全边界运行，优先使用带有命名空间/RBAC/ServiceAccount 控制的 Kubernetes。只有在使用专用 Agent 并按信任级别隔离时，Docker 才是可行的简单默认选项，因为 Docker socket 可以控制主机守护进程。切勿对不受信任的仓库使用 Local 后端。

• Agent 需要 WOODPECKER_SERVER，以及与服务端相同的 WOODPECKER_AGENT_SECRET。服务端会在首次联系时注册 Agent；请持久化 Agent 配置文件，以便其生成的身份在重启后保留。
• 除非有意开放注册，否则请保持 WOODPECKER_OPEN=false。明确授予管理员权限，并保护 OAuth 客户端密钥和 Agent 密钥。
• 默认情况下，不要向不受信任的拉取请求公开密钥。如果必须在其中使用密钥，请限制其事件和插件镜像，并记录威胁模型。
• depends_on 用于工作流排序和并行执行；它不用于检查服务容器是否已就绪。请为数据库和缓存添加实际的等待/退避逻辑或健康探测。
• 步骤的 when 列表在各条目之间采用 OR 逻辑，在单个条目内采用 AND 逻辑。分支筛选器也会影响拉取请求的目标分支；如果只想匹配推送到某个分支的事件，请组合使用 event 和 branch。
• docker compose config 通过或 CLI lint 检查通过，只能证明语法/模型有效，并不能证明 Agent 能连接到代码托管平台、镜像可以拉取或流水线安全。

参考资料路由

在以下情况下加载	参考资料
使用 Docker Compose 安装、配置 Forgejo/Gitea 或选择后端	references/setup.md
编写工作流 YAML、事件、条件、矩阵、服务、插件或多工作流项目	references/pipeline-syntax.md
设计并行工作流、并发、缓存、注册表、可复用 YAML 或自动扩缩容	references/advanced-patterns.md
管理密钥、注册表、CLI 操作、升级、备份和指标	references/operations.md
流水线、克隆、Agent、OAuth、Docker 或 Kubernetes 运行失败	references/troubleshooting.md
事件期间需要简明的症状到证据对照表	references/failure-signatures.md
检查信任边界、拉取请求、插件、本地后端或 Kubernetes 权限	references/security.md
使用或安装 woodpecker-cli	references/cli.md
检查源 URL 和与版本相关的声明	references/source-index.md

附带工件

• templates/docker-compose.yml — 最小化的服务端与 Docker Agent 部署。
• templates/woodpecker.yml — 保守的构建/测试/部署工作流骨架。
• templates/forgejo.env.example — Forgejo 的占位环境变量约定。
• assets/troubleshooting-checklist.md — 事件交接检查清单。
• scripts/woodpecker-doctor.py — 无依赖的连通性/配置探测工具，支持文本或 JSON 输出。

可用脚本

脚本	用途	调用方式
scripts/woodpecker-doctor.py	用于 Woodpecker 部署的无依赖连通性/配置探测工具：检查服务端 HTTP URL 和 Agent gRPC 端点，支持文本或 JSON 输出。在任何“是 CI 出问题还是我这边的问题”诊断中将其作为第一步；部署变更后运行以验证健康状态；并在深入排查前运行。	python3 scripts/woodpecker-doctor.py --url https://ci.example.com --server agent-host:9000 --json

先决条件

• 运行探测程序的位置必须能够访问 Woodpecker 服务 URL；检查 Agent 时，还必须能够访问 Agent 的 gRPC 主机和端口。
• 仅需 Python 3——探测程序使用标准库，不依赖第三方软件包；且不会修改 Woodpecker 实例。
• 如需执行探测以外的实际管理操作（参见 compatibility）：需要访问 Woodpecker 实例，并根据所用后端使用 Docker Compose、Kubernetes 或 woodpecker-cli——参见 references/setup.md 和 references/cli.md。

限制

• doctor 探测程序只报告连接性和配置相关信号；探测结果为绿色并不能证明 Forge OAuth 正常、流水线会被调度，或步骤能够拉取镜像——请在这些环节分别验证（参见“常见故障边界”）。
• 它不会读取仓库级状态（webhook、密钥、队列深度）；请使用服务 API/UI 和 references/troubleshooting.md。
• 该技能记录的是操作模式，而非固定版本：请始终通过 references/source-index.md，根据已安装的主版本确认对版本敏感的命令和变量。

常见故障边界

• 服务已启动，但仓库没有显示：在修改流水线 YAML 前，先检查 Forge OAuth URL、回调 URL、作用域和服务日志。推送后没有流水线时，先检查 Forgejo 仓库的 Settings → Webhooks → Recent Deliveries，并记录投递状态。
• Agent 已连接，但从不接取工作：检查标签/后端、最大工作流数、仓库的可见性/信任设置，以及 Agent 日志。
• 克隆失败：先在有意暂停的步骤中测试网络/DNS 和凭据；在检出成功前，不要排查应用命令。
• 服务正在运行，但测试无法连接：使用服务主机名和容器端口，然后添加就绪处理。
• 密钥为空：检查密钥作用域、事件筛选器、插件镜像筛选器和表达式转义（Woodpecker 必须将变量传递给 shell 时，使用 $${NAME}）。

何时不适用

安装或管理 Forgejo/Gitea 本身时，请使用对应 Forge 的专用技能；管理集群生命周期时，请使用 Kubernetes 运维技能；加固主机时，请使用 Docker 安全技能。本技能涵盖 Woodpecker 的集成点和 CI 行为。