woodpecker

Woodpecker CI 流水线配置

补充说明

Woodpecker 是轻量级自托管 CI，配置写在 .woodpecker.yml 或 .woodpecker/ 目录。每个 step 在容器中执行，支持依赖、条件、服务和密钥。

常用示例

woodpecker-cli pipeline ls
woodpecker-cli pipeline info 42
woodpecker-cli log 42
woodpecker-cli repo ls
woodpecker-cli secret add --repo example/app --name token --value "$TOKEN"

最小配置：

steps:
  - name: test
    image: node:20
    commands:
      - npm ci
      - npm test

  - name: build
    image: plugins/docker
    depends_on: [test]
    settings:
      repo: example/app
      tags: latest
      username:
        from_secret: docker_username
      password:
        from_secret: docker_password

易错点与排错

• Woodpecker v2+ 支持 .woodpecker/ 目录拆分；旧版只认根目录单文件，先确认版本。
• step 之间不共享文件系统；需要产物时用 workspace 或显式挂载。
• depends_on 只表达依赖，不会自动传递文件；产物传递要单独配置。
• secrets 必须 from_secret；明文写进 YAML 会进仓库历史。
• 自托管实例的 forge（GitHub/Gitea/GitLab）OAuth 和 webhook 要配对；否则不会触发。
• agent 的标签和并发要匹配 step 需求；否则任务一直排队。
• 插件镜像固定版本；latest 会让构建结果漂移。
• 条件（when）写错会导致流水线完全不触发；先在测试仓库验证。

相关命令

• gitea-actions — Gitea 的 Actions
• drone — 同类自托管 CI
• docker — 容器运行时