Buddy自动化运维：自定义操作详细文档

介绍

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

界说

自界说操作由三个元素界说：

1. YAML装备(必填)
2. 图标(选填)
3. 描绘(选填)

一切三个元素都有必要上传到存储仓的默许分支：

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

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

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

增加的操作可用于作业区中的一切项目，但是，咱们主张将您的操作存储在具体的存储仓中。经过这种方式，将它们与您的源代码阻隔开来，您能够轻松跟踪其开发记录、发布更新和修正问题。假如需求，您还能够跨多个作业区共享此存储仓中的操作。

图标

图标显现于操作磁贴和装备屏幕上

• 称号：有必要是action
• 扩展名：jpg、jpeg、png、svg
• 尺度：最小40×40像素，可扩展大小尺度

当没有供给图标时，Buddy将运用体系默许图标。

描绘

一个操作能够有一个README.md文件方式的描绘。咱们主张将此类文件上传到您的操作目录，并附上操作的阐明以及所需的参数、指令和变量。您还能够增加包括更新列表的变更日志，以跟踪您的操作演变记录。

YAML装备

自界说操作以类似于默许Buddy操作的方式界说为代码，您能够界说以下事项：

1. 称号
2. 输入
3. 履行指令(选填)
4. 文件体系与缓存(选填)
5. Docker镜像(例如：运转环境)
6. 输出(选填)

示例

在此，咱们能够看到有三个输入项的一个操作：用户、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"

默许情况下

1. 没有挂载文件体系
2. 没有附加的目录(cached_dirs)被缓存
3. 作业目录依然保持在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和文件体系。

操作选项卡排序

• 设置选项卡(假如界说输入则显现)
• 自界说选项卡(假如界说选项卡则显现)
• 变量(在“选项”选项卡中翻开/关闭)
• 触发条件(一直显现)
• 选项(一直显现)

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

如若您在Buddy运用上遇到疑问，可随时联络官方技术支撑邮件：support@buddy.red

感谢您花时间阅读Buddy自界说操作文档！