跳到主要内容

创建插件

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

设置​

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

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

像 - 这样的字符会转换为下划线（_）。some_String 变成 PLUGIN_SOME_STRING。 不尊重驼峰命名法，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 将您的插件添加到插件索引（索引中的上述示例）。