YAML Configuration
The file with the definition must be named action.yml
. In the file, you can configure the following properties:
- Name
- Inputs
- Commands to execute (optional)
- Filesystem & cache (optional)
- Docker image (i.e. run environment)
- 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"
By default:
- No filesystem is mounted.
- No extra directories (
cached_dirs
) are cached. - The working directory remains as defined in the Docker image.
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"
reset_entrypoint: true
to the configuration.
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 logsexample
: adds an example/descriptioninfo
: 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
Image loading...Custom action with generated variables
The output of the action closely follows the descriptions from the screenshot:
Image loading...Action output
Sep 24, 2024