自定义操作

介绍

在默认操作列表顶部，用户可以在YAML中定义自己的操作并在流水线中使用。操作在从Docker Hub注册中心拉取的镜像于启动的Docker容器中运行，Docker容器就像一个预装了操作系统、工具和依赖项的本地开发环境。在容器中，您可以对存储仓文件运行命令，运行对任何公开可用的第三方API的调用，并将输入数据导出到变量以在流水线中的其他操作中使用。

定义

自定义操作由三个元素定义：

YAML配置(必填)
图标(选填)
描述(选填)

所有三个元素都必须上传到存储仓的默认分支：

在存储仓的根目录中(单个操作)
在.buddy/actions目录中，每个操作都在其自己的子目录中(多个操作)，例如：

.buddy/actions/myaction-1
.buddy/actions/myaction-2
.buddy/actions/myaction-3

一旦将操作添加到存储仓后，Buddy会自动解析操作并显示于操作列表顶部：

自定义操作于操作列表

提示

添加的操作可用于工作区中的所有项目，然而，我们建议将您的操作存储在具体的存储仓中。通过这种方式，将它们与您的源代码隔离开来，您可以轻松跟踪其开发记录、发布更新和修复问题。如果需要，您还可以跨多个工作区共享此存储仓中的操作。

图标

图标显示于操作磁贴和配置屏幕上

名称：必须是action
扩展名：jpg、jpeg、png、svg
尺寸：最小40x40像素，可扩展大小尺寸

信息

当没有提供图标时，Buddy将使用系统默认图标。

描述

一个操作可以有一个README.md文件形式的描述。我们建议将此类文件上传到您的操作目录，并附上操作的说明以及所需的参数、命令和变量。您还可以添加包含更新列表的变更日志，以跟踪您的操作演变记录。

YAML配置

自定义操作以类似于默认Buddy操作的方式定义为代码，您可以定义以下事项：

名称
输入
执行命令(选填)
文件系统与缓存(选填)
Docker镜像(例如：运行环境)
输出(选填)

示例

在此，我们可以看到有三个输入项的一个操作：用户、IP与密码。输入作为变量传递命令，命令在Ubuntu最新版本环境中运行。

name: "My_Action"
inputs:
  user:
    type: TEXT
    required: true
  ip:
    type: TEXT
  password:
    type: PASSWORD
    required: true
execute_commands:
  - echo $user@$ip -p $password
docker_image_name: "ubuntu"
docker_image_tag: "latest"

名称与分类

操作名称在整个工作区中必须独特，即不能与默认操作列表中的任何操作名称相同。如果名称不独特，则会出现解析错误。默认情况下，下划线被解析为空格键。例如，名为“My_Custom_Action”的操作将显示为“My Custom Action”。

默认情况下，自定义操作会添加到操作列表的自定义/热门部分。您可以通过将分类category参数添加到YAML文件来定义自己的分类：

name: "My_Custom_Action"
category: "Example Inputs"

输入

输入可让您指定操作所需的数据。您可以添加单行或多行文本输入、复选框、命令字段、选择器等等。

信息

单击此处查看输入参数的完整列表

在此示例中，我们可以看到两个输入：一个是用于用户名的简单文本输入，第二个是用于密码的掩码输入。这两个字段为必填。

inputs:
  user:
    type: TEXT
    required: true
  ip:
  password:
    type: PASSWORD
    required: true

命令

默认情况下，该操作会运行Docker镜像中内置的命令。您可以通过添加execute_commands参数来覆盖这些命令：

execute_commands:
  - echo $user@$ip -p $password

信息

默认情况下，该操作会运行Docker镜像中内置的命令。如果定义了execute_commands，则不会运行镜像命令。

文件系统与缓存

如果您的操作需要存储仓里的文件，则需要附加流水线文件系统，例如定义volume_mappings参数。文件系统是每个流水线的专用目录。当运行流水线时，Buddy会将存储仓拉取到文件系统，允许您在其中运行命令。处理后的文件和工件保留在文件系统中，供流水线中的其他操作使用。

volume_mappings:
 - /:/buddy

您还可以使用cached_dirs参数缓存附加的目录。如果您的操作在每次运行时都下载文件，则此功能很有用——缓存文件将加快执行时间。

volume_mappings:
 - /:/buddy
working_directory: "/buddy/example-folder"
cached_dirs:
 - "/cache-local"
 - "/cache-application"

信息

默认情况下

没有挂载文件系统
没有附加目录(cached_dirs)被缓存
工作目录仍然保持在Docker镜像中定义的状态

Docker镜像

自定义操作在由用户定义镜像启动的隔离容器中运行。Docker镜像必须存储在Docker Hub上，并且可供公开访问。如果您的操作不需要特定的语言和/或框架，我们建议您使用最新版本的官方Ubuntu镜像。

docker_image_name: "ubuntu" 
docker_image_tag: "latest"

提示

镜像不能定义入口点，否则它将无法工作。您可以通过将reset_entrypoint: true添加到配置中来清除入口点。

输出

当运行操作时，将输入值作为不可设置的环境变量传递给容器。这些变量可以使用output参数在操作中生成：

inputs:
  first_input:
output:
  variables:
    first_input:
      example: "The description of the variable."
      info: "The contents of the tooltip"
      masked: true

一个变量可以用三个参数来描述：

masked：在日志中隐藏变量值
example：添加示例/描述
info：在鼠标悬停时显示提示

在流水线运行期间，也可以使用export INPUT_NAME命令导出变量并由流水线中的其他操作使用：

execute_commands:
  - export first_input
  - export second_input

示例

这里我们有一个将两个输入复制到变量中的操作，第三个变量由操作命令创建：

name: "Output_Example"
inputs:
  first_input:
    default: "Example text"
  second_input:
    required: true
execute_commands:
  - export first_input
  - export second_input
  - export maskedVar="hidden_value"
docker_image_name: "ubuntu"
docker_image_tag: "latest"
output:
  variables:
    first_input:
      example: "This variable has a default value."
      info: "Tooltip #1"
    second_input:
      example: "This variable is required."
    maskedVar:
      example: "This variable is created by the action and masked."
      info: "Tooltip #3"
      masked: true

自定义操作生成变量

该操作的输出与截图中的描述非常相似：

操作输出

版本控制与解析

操作应该在存储仓的默认分支中创建和更新，并使用Git标签进行版本控制。一个操作可以有与创建的标签一样多的版本，操作的最新版本总是存储在默认分支的 HEAD中。您可以从下拉按钮中选择操作的版本：

选择操作版本

一旦你推送您的操作，它应该会出现在操作列表的顶部。如果在列表中没有看到，可以在动态标签页的推送详情中查看是什么问题：

动态推送事件截图

单击该事件将展开推送详细信息，您可以在其中查看具体的出错内容：

推送事件解析详情

删除与重命名

一旦操作被成功解析，它就会在工作区中永久保留。当一个操作被删除时，它的状态会更改为已弃用，但仍然可以从操作列表中添加并继续在其流水线中工作。这是一种安全措施，可防止在操作存储仓不小心被删除时流水线出现故障。在action.yml中更改操作的名称name会在工作区中新建一个操作，同时保留旧操作。

自定义操作YAML配置

要通过YAML将您的操作添加到流水线，请遵循以下模式：

- action: "Pipeline_action_name"
  type: "CUSTOM"
  custom_type: "name:tag"

其中action是操作在流水线中的标签名称，custom_type是您要使用自定义操作的名称name。

示例

- action: "Worker scaling"
  type: "CUSTOM"
  custom_type: "workers_custom:latest"

信息

与其他操作一样，自定义操作也可以用于远程流水线配置。

自定义操作YAML参数

名称	类型	描述
name `必填`	String	YAML定义中操作的ID，最多40个字符(a-zA-Z0-9_)
docker_image_name `必填`	String	从中启动容器的Docker镜像
docker_image_tag `必填`	String	从中启动容器的Docker镜像标签
reset_entrypoint	Boolean	如果设置为`True`，则取消设置镜像设置的默认入口点。
execute_commands	String[]	在容器中运行的命令列表
shell	String	命令shell的类型。默认: bash
title	String	显示于操作标题和添加操作屏幕上的操作标题，最多40个字符。
category	String	操作分类，最多100个字符。
inputs	String	显示在操作视图上的输入列表
tabs	String	显示在操作视图上的标签页列表
output	String[]	定义在流水线运行期间由操作生成的环境变量表
volume_mappings	String	冒号前面的路径是文件系统路径(将要挂载到容器中的文件系统文件夹)，冒号后面的路径是容器路径(容器中的路径，即文件系统将会位于其中)。
cached_dirs	String[]	将在执行之间缓存的附加容器目录

输入参数列表

名称	类型	描述
id `必填`	String	输入ID，用于在容器中创建环境变量，最多40个字符(a-zA-Z0-9_)。必须独特，不能以buddy开始。区分大小写，即`user`和`User`是为两个独立的输入。
name	String	显示在输入标签上的名称。最多100个字符，如果未提供，则从ID中获取值并将下划线`_`替换为空格。
type	String	输入类型。默认: 文本
info	String	在输入下方添加带有附加信息的描述，最多200个字符。
options	String[]	输入选项，要求`AUTOSUGGEST`和`SELECT`类型。
required	Boolean	默认: `false`
masked	Boolean	默认: `false`
default	String	注入到输入的选填默认值

输入类型列表

名称	描述
TEXT	一行文本输入，支持掩码。
TEXTAREA	多行文本输入，支持掩码。
PASSWORD	用于输入密码凭据，始终掩码。
SELECT	选择器列表，要求`Options`。
AUTOCOMPLETE	支持自动补全，要求`Options`。
CHECKBOX	一个可以勾选和关闭的复选框
COMMAND	构建操作后样式化的多行文本区域，支持掩码。
FILESYSTEM_PATH	用于选择流水线文件系统中的路径，支持掩码。
GITHUB_INTEGRATION	允许在项目中选择GitHub集成，使用集成ID作为输入变量。生成`GITHUB_TOKEN`。
AWS_INTEGRATION	允许在项目中选择AWS集成，使用集成ID作为输入变量。生成`AWS_ACCESS KEY`与`AWS_SECRET_KEY`。

输入示例

TEXT

name: "input_TEXT"
inputs:
 first_field:
   name: "本字框 #1"
   required: true
 second_field:
   name: "本字框 #2"
   default: "Second text field"
 third_field:
   name: "本字框 #3"
   info: "此为上面文本字框的示例说明"
execute_commands:
 - echo $first_field
 - echo $second_field
 - echo $third_field
docker_image_name: "ubuntu"
docker_image_tag: "latest"

在这里我们可以看到三个文本输入：

第一个为强制性(要求required: true)
第二个为默认值输入
第三个为带有描述的信息框

自定义操作文本输入

信息

如果没有定义类型type，这是默认输入。

TEXTAREA

name: "input_TEXTAREA"
inputs:
 textarea_1:
   type: TEXTAREA
   name: "Textarea #1"
   default: |-
     First line of multi-line text input.
     Second line of multi-line text input.
     Third line of multi-line text input.
     Fourth line of multi-line text input.
 textarea_2:
   type: TEXTAREA
   name: "Textarea #2"
   info: "This is an example description for the textarea field above."
execute_commands:
 - echo $textarea_1
 - echo $textarea_2
docker_image_name: "ubuntu"
docker_image_tag: "latest"

此操作有两个文本区域：

第一个为四行默认文本
第二个为使用介绍信息框

自定义操作多行文本输入

PASSWORD

name: "input_PASSWORD"
inputs:
 password_1:
   type: PASSWORD
   name: "First password"
   required: true
 password_2:
   type: PASSWORD
   name: "Second Password"
execute_commands:
 - echo $password_1
 - echo $password_2
docker_image_name: "ubuntu"
docker_image_tag: "latest"

在此示例中，第一个密码输入为强制性(要求required: true)，第二个为选填。

自定义操作密码输入

您可以看到密码字段默认为掩码：

SELECT

name: "input_SELECT"
inputs:
 select_1:
   type: SELECT
   name: "First select"
   required: true
   options:
     - "option 1"
     - "option 2"
     - "option 3"
 select_2:
   type: SELECT
   name: "Second select"
   info: "This is an example description for the selector above."
   default: "option 2"
   options:
     - "option 1"
     - "option 2"                                                          
     - "option 3"
execute_commands:
 - echo $select_1
 - echo $select_2
docker_image_name: "ubuntu"
docker_image_tag: "latest"

此处我们有两个选择器：

第一个为必填
第二个为具有默认值2和一个带有描述的信息框

自定义操作选择器

AUTOCOMPLETE

name: "input_AUTOCOMPLETE"
inputs:
 autocomplete_1:
   type: AUTOCOMPLETE
   name: "Example input"
   options:
     - "suggestion 1"
     - "suggestion 2"
     - "suggestion 3"
execute_commands:
 - echo $autocomplete_1
docker_image_name: "ubuntu"
docker_image_tag: "latest"

这种类型的输入支持输入建议，您可以输入您自己的值或从列表中选择一个建议。

自定义操作自动补全

CHECKBOX

name: "input_CHECKBOXES"
inputs:
 first_checkbox:
   type: CHECKBOX
   name: "Checkbox #1"
   default: "true"
 second_checkbox:
   type: CHECKBOX
   name: "Checkbox #2"
   info: "This is an example description for the checkbox above."
execute_commands:
 - echo $first_checkbox
 - echo $second_checkbox
docker_image_name: "ubuntu"
docker_image_tag: "latest"

设置default: "true"于第一个输入中默认勾选第一个复选框，第二个复选框输入中的信息参数添加一行说明。

自定义操作复选框

COMMAND

name: "input_COMMAND"
inputs:
 command_field:
   name: CMD
   type: COMMAND
   default: "ls -al"
execute_commands:
- bash -c "$command_field"
docker_image_name: "ubuntu"
docker_image_tag: "latest"
volume_mappings:
 - /:/buddy

自定义操作命令输入

在这种情况下，容器附加了一个文件系统，以便可以在存储仓文件上运行命令。

信息

我们建议使用bash -c “$INPUT_NAME"作为命令输入的执行命令，这样命令将始终正常运行，而忽略行数。

FILESYSTEM_PATH

name: "input_FILESYSTEM"
inputs:
 Filesystem_Path:
   type: FILESYSTEM_PATH
   default: "/buddy"
docker_image_name: "ubuntu"
docker_image_tag: "latest"
volume_mappings:
 - /:/buddy

自定义操作文件系统路径

这种类型的输入允许您选择管道文件系统中的路径，您可以看到它附加于volume_mappings。

GITHUB_INTEGRATION

name: "input_GitHub"
inputs:
 github_field:
   type: GITHUB_INTEGRATION
   name: "GitHub Integration"
   default: "github_integration_hash"
execute_commands:
 - gh auth status
docker_image_name: "buddy/github-cli"
docker_image_tag: "latest"

GITHUB_INTEGRATION参数添加一个输入，允许您选择GitHub集成并在操作中使用。该操作还会生成可在流水线中使用的$GITHUB_TOKEN。

此操作使用安装了GitHub CLI的Docker镜像。执行的命令检索与所选AWS集成关联账户的主要联系信息：

自定义操作日志

提示

加入默认default的集成哈希会自动在输入中设置集成。

AWS_INTEGRATION

name: "input_AWS"
inputs:
 aws_field:
   type: AWS_INTEGRATION
   name: "AWS Integration"
   default: "aws_integration_hash"
execute_commands:
 - aws account get-contact-information
docker_image_name: "buddy/aws-cli-2"
docker_image_tag: "latest"

AWS_INTEGRATION参数添加一个输入，让您可以选择AWS集成并在操作中使用。该操作还会生成可在流水线中使用的$AWS_ACCESS_KEY_ID和$AWS_SECRET_ACCESS_KEY。

此操作使用安装了AWS CLI的Docker镜像，执行的命令验证并显示有关所选GitHub集成的身份验证状态信息：

自定义操作日志

提示

加入默认default的集成哈希会自动在输入中设置集成。

标签页/选项卡

如果您的自定义操作定义了输入，它们将显示在操作的设置标签页/选项卡中。您可以添加额外的选项卡以使您的操作清晰有序：

name: "custom_TABS"
execute_commands:
- echo $path_app
- echo $path_docs
tabs:
 AWS:
   aws_integration:
     type: AWS_INTEGRATION
     required: true
 GitHub:
   gh_integration:
     type: GITHUB_INTEGRATION
     required: true
 Filesystem:
   path_app:
     name: "App Path"
     type: FILESYSTEM_PATH
     required: true
   path_docs:
     name: "Documentation Path"
     type: FILESYSTEM_PATH
     required: true
docker_image_name: "node"
docker_image_tag: "latest"
volume_mappings:
 - /:/buddy

在此示例中，未生成设置，因为没有定义输入。而这些参数在三个选项卡中进行了描述：AWS、GitHub和文件系统。

自定义操作标签页/选修卡定义

操作选项卡排序

设置选项卡(如果定义输入则显示)
自定义选项卡(如果定义选项卡则显示)
变量(在“选项”选项卡中打开/关闭)
触发条件(始终显示)
选项(始终显示)

信息

要启用变量支持，请勾选变量复选框于选项标签页中。

自定义操作

介绍​

定义​

图标​

描述​

YAML配置​

名称与分类​

输入​

命令​

文件系统与缓存​

Docker镜像​

输出​

版本控制与解析​

删除与重命名​

自定义操作YAML配置​

自定义操作YAML参数​

输入参数列表​

输入类型列表​

输入示例​

TEXT​

TEXTAREA​

PASSWORD​

SELECT​

AUTOCOMPLETE​

CHECKBOX​

COMMAND​

FILESYSTEM_PATH​

GITHUB_INTEGRATION​

AWS_INTEGRATION​

标签页/选项卡​

操作选项卡排序​

介绍

定义

图标

描述