跳到主要内容

创建插件

创建新插件很简单：构建一个 Docker 容器，将您的插件逻辑用作 ENTRYPOINT。

设置​

要允许用户配置您的插件行为，您应该使用 settings:。

这些设置将作为带有 PLUGIN_ 前缀的大写环境变量传递给您的插件。 使用像 url 这样的设置会导致名为 PLUGIN_URL 的环境变量。

像 - 这样的字符会转换为下划线 (_)。some_String 变成 PLUGIN_SOME_STRING。 CamelCase 不被尊重，anInt 变成 PLUGIN_ANINT。

基本设置​

使用任何基本 YAML 类型（标量）都会转换为字符串：

设置环境值
some-bool: falsePLUGIN_SOME_BOOL="false"
some_String: helloPLUGIN_SOME_STRING="hello"
anInt: 3PLUGIN_ANINT="3"

复杂设置​

也可以使用这样的复杂设置：

steps:
  - name: plugin
    image: foo/plugin
    settings:
      complex:
        abc: 2
        list:
          - 2
          - 3

像这样的值会转换为 JSON，然后传递给您的插件。在上面的示例中，环境变量 PLUGIN_COMPLEX 将包含 {"abc": "2", "list": [ "2", "3" ]}。

密钥​

密钥也应该作为设置传递。因此，用户应该使用 from_secret。

插件库​

对于 Go，我们提供了一个插件库，您可以用它来轻松访问内部环境变量和您的设置。请参阅 https://codeberg.org/woodpecker-plugins/go-plugin。

元数据​

在您的文档中，您可以使用 Markdown 标头为您的插件定义元数据。这些数据由我们的插件索引使用。

支持的元数据：

  • name: 插件的全名
  • icon: 插件图标的 URL
  • description: 简短描述它在做什么
  • author: 您的名字
  • tags: 关键字列表（例如，克隆插件的 [git, clone]）
  • containerImage: 容器镜像的名称
  • containerImageUrl: 容器镜像的链接
  • url: 您的插件的主页或仓库

如果您希望您的插件在索引中列出，您应该添加尽可能多的字段，但只有 name 是必需的。

示例插件​

这提供了一个简短的教程，用于创建 Woodpecker webhook 插件，使用简单的 shell 脚本在构建管道期间进行 HTTP 请求。

最终用户会看到什么​

以下示例演示了我们如何在 YAML 文件中配置 webhook 插件：

steps:
  - name: webhook
    image: foo/webhook
    settings:
      url: https://example.com
      method: post
      body: |
        hello world

编写逻辑​

创建一个简单的 shell 脚本，使用 YAML 配置参数调用 curl，这些参数作为大写环境变量传递给脚本，前缀为 PLUGIN_。

#!/bin/sh

curl \
  -X ${PLUGIN_METHOD} \
  -d ${PLUGIN_BODY} \
  ${PLUGIN_URL}

打包​

创建一个 Dockerfile，将您的 shell 脚本添加到镜像中，并配置镜像以将您的 shell 脚本作为主入口点执行。

# 请固定版本，例如 alpine:3.19
FROM alpine
ADD script.sh /bin/
RUN chmod +x /bin/script.sh
RUN apk -Uuv add curl ca-certificates
ENTRYPOINT /bin/script.sh

构建并将您的插件发布到 Docker 注册表。一旦发布，您的插件就可以与更广泛的 Woodpecker 社区共享。

docker build -t foo/webhook .
docker push foo/webhook

从命令行在本地执行您的插件以验证它是否正常工作：

docker run --rm \
  -e PLUGIN_METHOD=post \
  -e PLUGIN_URL=https://example.com \
  -e PLUGIN_BODY="hello world" \
  foo/webhook

最佳实践​

  • 为不同的架构构建您的插件，以允许许多用户使用它们。 至少，您应该支持 amd64 和 arm64。
  • 为使用 local 后端的用户提供二进制文件。 这些也应该为不同的操作系统/架构构建。
  • 尽可能使用内置环境变量。
  • 除了设置（和内部环境变量）之外，不要使用任何配置。这意味着：不要要求使用 environment，不要要求特定的密钥名称。
  • 添加 docs.md 文件，列出您的所有设置和插件元数据（示例）。
  • 使用您的 docs.md 将插件添加到插件索引（上面的示例在索引中）。