YAML Configuration

The file with the definition must be named action.yml. In the file, you can configure the following items:

1. Name
2. Inputs
3. Commands to execute (optional)
4. Filesystem & cache (optional)
5. Docker image (i.e. run environment)
6. Outputs (optional)

Example

Here we can see an action with three inputs: user, IP, and password. The inputs are passed as variables to the command. The values are then produced in the action logs with the echo command. The command is run in the Ubuntu environment in the latest version.

yamlname: "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"

Name & category

The name of the action must be unique throughout the whole workspace, i.e. cannot be the same as any action name on the default list of actions. If the name is not unique, a parsing error will appear. Underscores are parsed into spacebars by default. For example, an action named "My_Custom_Action" will be displayed as "My Custom Action".

By default, custom actions are added to the Custom / Popular section of the action list. You can define your own categories by adding the category parameter to the YAML file:

yamlname: "My_Custom_Action"
category: "Example Inputs"

Inputs

The inputs let you specify the data that the action requires. You can add single or multi-line text inputs, checkboxes, command fields, selectors, and more.

In this example, we can see two inputs: one is a simple text field for entering the username, the second is a masked input for the password. Both fields are required.

yamlinputs:
  user:
    type: TEXT
    required: true
  password:
    type: PASSWORD
    required: true

Commands

By default, the action runs the commands baked in the Docker image. You can overwrite these commands by adding the execute_commands parameter:

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

Filesystem & caching

If your action requires repository files, you need to attach the pipeline filesystem to it, i.e. define the volume_mappings parameter. The filesystem is a directory exclusive to every pipeline. When a pipeline is run, Buddy pulls the repo to the filesystem, allowing you to run commands on the files it contains. The processed files and artifacts stay in the filesystem, available for use by other actions in the pipeline.

yamlvolume_mappings:
 - /:/buddy

You can also cache additional directories with the cached_dirs parameter. This feature is useful if your action downloads files on every run – caching them will speed up the execution time.

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

Docker image

Custom actions are run in an isolated container launched from an image defined by the user. The Docker image must be stored on the Docker Hub and be publicly available. If your action does not require a specific language and/or framework, we recommend using the official Ubuntu image in the latest version:

yamldocker_image_name: "ubuntu" 
docker_image_tag: "latest"

Outputs

When the action is run, the values of the inputs are passed to the container as non-settable environment variables. These variables can be generated in the action with the output parameter:

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

A variable can be described with three parameters:

• masked: hides the value of the variable in the logs
• example: adds an example/description
• info: displays a tooltip on mouse hover

The variables can also be exported and used by other actions in the pipeline for the duration of the pipeline run using the export INPUT_NAME command:

yamlexecute_commands:
  - export first_input
  - export second_input

Example

Here we have an action with two inputs reproduced into variables. The third variable is created by the action's commands:

yamlname: "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

Custom action with generated variables

The output of the action closely follows the descriptions from the screenshot:

Action output