YAML Schema
The buddy.yml
file defines all pipelines in the project. Every pipeline consists of a list of actions to be executed. Below you’ll find schemas for both pipelines and actions.
Pipelines schema
The file consists of a list of pipelines:
- pipeline: "production"
on: "CLICK"
refs:
- "refs/heads/master"
variables:
- key: "username"
value: "Buddy"
settable: false
description: "var_descrption"
change_set_base: "LATEST_RUN_MATCHING_REF"
- pipeline: "build"
on: "EVENT"
events:
- type: "PUSH"
refs:
- "*"
Properties
Name | Type | Description |
---|---|---|
pipeline Required | String | The ID of the pipeline. |
on | String | The trigger mode of the pipeline. Can be one of 'CLICK', 'EVENT', 'SCHEDULE'. If not set, the default value is 'EVENT' |
refs | String[] | Set it if on is set to 'CLICK' or 'SCHEDULE'. The list of refs for which the pipeline will be triggered. Automatically set to 'NONE' if not provided. |
events | Event[] | The list of events for which the pipeline will be triggered. Set it if 'on' is set to 'EVENT'. Required if 'ON' is set or not set to 'EVENT'. |
trigger_conditions | TriggerCondition[] | The list of trigger conditions to meet so that the pipeline can be triggered. |
always_from_scratch | Boolean | Defines whether or not to upload everything from scratch on every execution. |
auto_clear_cache | Boolean | Defines whether or not to automatically clear cache before running the pipeline . |
no_skip_to_most_recent | Boolean | Defines whether or not to skip execution to the most recent execution. |
do_not_create_commit_status | Boolean | Defines whether or not to omit sending commit statuses to Github or Gitlab upon execution. |
start_date | iso 8601 utc date | Required if the pipeline is set to 'on: SCHEDULE' and no 'cron' is specified. Defines when the pipeline execution should start. Format: 2016-11-18T12:38:16.000Z |
delay | Integer | Required if the pipeline is set to 'on: SCHEDULE' and no 'cron' is specified. Defines the intervals in which the pipeline should be executed (in minutes). |
cron | String | Required if the pipeline is set to 'on: SCHEDULE' and neither 'start_date' nor 'delay' is specified. The standard CRON expression defining the execution schedule. |
actions | Action[] | The list of actions executed in the pipeline. |
variables | Variable[] | The list of variables you can use in the pipeline. |
ignore_fail_on_project_status | Boolean | If set to 'true' the status of a given pipeline will not impact the project status on the dashboard. |
execution_message_template | String | The title of every execution in this pipeline. By default it is set to '$BUDDY_EXECUTION_REVISION_SUBJECT'. |
target_site_url | String | The URL of the target website. |
disabled | Boolean | Set it, if you want the pipeline to be disabled. |
disabled_reason | String | Specify the reason for disabling the pipeline. |
fetch_all_refs | Boolean | When the pipeline is run, Buddy fetches only one Git reference to the pipeline filesystem (branch, tag, or pull request). If the option is set to true , Buddy will be forced to fetch all Git references. |
permissions | PipelinePermissions | Define to set permissions for the pipeline. |
change_set_base | String | Defines the way the changeset for deployments and trigger conditions between subsequent executions in the pipeline will be calculated. Available values: 'LATEST_RUN', 'LATEST_RUN_MATCHING_REF', 'PULL_REQUEST'. By default, it is set to 'LATEST_RUN'. |
PipelinePermissions schema
Name | Type | Description |
---|---|---|
others | String | AccessLevel for the group Others. Can be one of 'DENIED', 'DEFAULT', 'READ_ONLY', 'RUN_ONLY', or 'READ_WRITE'. Default setting is 'DEFAULT' (Project role). |
users | UserPermission[] | The list of users who will be granted a permission other than the Others group. |
groups | GroupPermission[] | The group who will be granted a permission other than the Others group. |
permissions:
others: "DEFAULT"
users:
alex@buddy.works: "DENIED"
mike@buddy.works: "READ_ONLY"
groups:
frontend: "READ_WRITE"
backend: "DEFAULT"
Actions schema
Every pipeline contains a list of actions. The actions are executed in the order provided in the .yml
file:
- pipeline: "production"
on: "CLICK"
refs:
- "refs/heads/master"
execution_message_template: "test"
ignore_fail_on_project_status: "true"
actions:
- action: "Execute: npm test"
type: "BUILD"
docker_image_name: "library/node"
docker_image_tag: "6"
execute_commands:
- "npm install"
- "npm test"
setup_commands:
- "npm install -g gulp grunt-cli"
variables:
- key: "username"
value: "Buddy"
settable: true
description: "var_description"
retry_interval: 1
retry_count: 3
- action: "Upload files to buddy.server"
type: "FTP"
input_type: "BUILD_ARTIFACTS"
local_path: "/"
login: "buddy"
password: "password"
host: "buddy.server"
port: "21"
retry_interval: 1
retry_count: 3
Properties
Name | Type | Description |
---|---|---|
action Required | String | The ID of the action. |
type Required | String | The type of the action. |
variables | Variable[] | The list of variables you can use the action. |
trigger_conditions | TriggerCondition[] | The list of trigger conditions to meet so that the action can be triggered. |
timeout | Integer | The timeout in seconds. |
disabled | Boolean | When set to 'true' the action is disabled. By default it is set to 'false'. |
run_next_parallel | Boolean | When set to 'true', the subsequent action defined in the pipeline will run in parallel to the current action. |
run_only_on_first_failure | Boolean | Defines whether the action should be executed on each failure. Restricted to and required if the 'trigger_time' is 'ON_FAILURE'. |
ignore_errors | Boolean | If set to 'true' the execution will proceed, mark action as a warning and jump to the next action. Doesn't apply to deployment actions. |
retry_interval | Integer | Delay time between auto retries in seconds. |
retry_count | Integer | Number of retries if the action fails. |
trigger_time | String | Specifies when the action should be executed. Can be one of ON_EVERY_EXECUTION , ON_FAILURE , ON_BACK_TO_SUCCESS , ON_WARNING or ON_WAIT_FOR_APPROVE . The default value is ON_EVERY_EXECUTION . |
Variables schema
You can define variables in the following way:
variables:
- key: "my_file"
type: "FILE"
value: "dGVzdA0K"
file_path: "/buddy-variables/file"
file_chmod: "644"
file_place: "CONTAINER"
- key: "id_my_key"
value: "secure!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.qiYL/5JiylAVf8oeD57u9w=="
type: "SSH_KEY"
encrypted: true
file_path: "~/.ssh/id_my_key"
file_chmod: "600"
file_place: "CONTAINER"
- key: "my_variable"
value: "my_value"
type: "VAR"
Properties
Name | Type | Description |
---|---|---|
key Required | String | The name of the variable. |
value Required | String | The value of the variable. If the 'type' is 'FILE', the value must be Base64 encoded. |
type | String | The type of the added variable. Can be one of 'VAR', 'SSH_KEY' or 'FILE'. |
description | String | The optional description of the variable. |
encrypted | Boolean | When set to 'true' the variable value will be encrypted and hidden. |
settable | Boolean | When set to 'true' the variable value can be shifted between subsequent actions or executions as well as pipelines. |
file_place | String | Available values: 'CONTAINER', 'NONE'. Set if type is 'SSH_KEY' or 'FILE'. If it's 'NONE', the variable can be used as a parameter in an action. For 'CONTAINER', the given file/key is additionally copied to an action container on each run. |
file_path | String | Specifies where to copy the file on each run. Set if 'type' is 'SSH_KEY' or 'FILE'. |
file_chmod | String | File permission set on copy to a container on each run. Set if 'type' is 'SSH_KEY' or 'FILE'. |
Using encrypted variables in YAML with Buddy Encryption Tool
To define a variable with the encrypted value:
Go to the Pipelines tab and click YAML helper in the right menu. Select Generate an encrypted value:
Generating a new encrypted value
Provide the input value and click Encrypt. It will produce a hash that you can copy and safely use in your YAML:
Setting a new encrypted value
Event schema
Here's how to define the event triggering the pipeline:
events:
- type: "PUSH"
refs:
- "refs/heads/master"
- "refs/heads/dev-*
Properties
Name | Type | Description |
---|---|---|
type Required | String | The type of the event. Available values: 'PUSH', 'CREATE_REF', 'DELETE_REF'. |
refs Required | String | The list of refs for which the pipeline will be triggered in the given event. |
tags | String | Runs the pipeline on the worker with tag that matches at least one of those specified in the array. |
Trigger condition schema
You can define trigger conditions in the following way:
trigger_conditions:
- trigger_condition: "VAR_IS"
trigger_variable_value: "expectedValue"
trigger_variable_key: "myVar"
- trigger_condition: "ON_CHANGE"
Properties
Name | Type | Description |
---|---|---|
trigger_condition | String | Defines when the action should be run. Can be one of 'ON_CHANGE', 'ON_CHANGE_AT_PATH', 'VAR_IS', 'VAR_IS_NOT', 'VAR_CONTAINS', 'VAR_NOT_CONTAINS', 'VAR_LESS_THAN', 'VAR_LESS_THAN_OR_EQUAL', 'VAR_GREATER_THAN', 'VAR_GREATER_THAN_OR_EQUAL', 'DAY', 'HOUR', 'TRIGGERING_USER_IS', 'TRIGGERING_USER_IS_NOT', 'TRIGGERING_USER_IS_IN_GROUP', 'TRIGGERING_USER_IS_NOT_IN_GROUP', or 'SUCCESS_PIPELINE', 'ACTION_STATUS_IS' or 'ACTION_STATUS_IS_NOT' (last two can only be set in the action). |
trigger_condition_paths | String[] | Required when 'trigger_condition' is set to 'ON_CHANGE_AT_PATH'. |
trigger_variable_key | String | Required when 'trigger_condition' is set to 'VAR_IS', 'VAR_IS_NOT' or 'VAR_CONTAINS' or 'VAR_NOT_CONTAINS', 'VAR_LESS_THAN', 'VAR_LESS_THAN_OR_EQUAL', 'VAR_GREATER_THAN', 'VAR_GREATER_THAN_OR_EQUAL'. Defines the name of the desired variable. |
trigger_variable_value | String | Required when 'trigger_condition' is set to 'VAR_IS', 'VAR_IS_NOT' or 'VAR_CONTAINS' or 'VAR_NOT_CONTAINS', 'VAR_LESS_THAN', 'VAR_LESS_THAN_OR_EQUAL', 'VAR_GREATER_THAN', 'VAR_GREATER_THAN_OR_EQUAL'. Defines the value of the desired variable which will be compared with its current value. |
trigger_hours | Integer[] | Available when 'trigger_condition' is set to 'HOUR'. Defines the time – by default running from 1 to 24. |
trigger_days | Integer[] | Available when 'trigger_condition' is set to 'DAY'. Defines the days running from 1 to 7 where 1 is for Monday. |
zone_id | String | Available when 'trigger_condition' is set to 'DAY' or 'HOUR'. Defines the timezone (by default it is UTC) and takes values from here. |
trigger_project_name | String | Required when 'trigger_condition' is set to 'SUCCESS_PIPELINE'. Defines the name of the project in which the 'trigger_pipeline_name' is. |
trigger_pipeline_name | String | Required when 'trigger_condition' is set to 'SUCCESS_PIPELINE'. Defines the name of the pipeline. |
trigger_action_name | String | Required when 'trigger_condition' is set to 'ACTION_STATUS_IS' or 'ACTION_STATUS_IS_NOT'. Defines the name of the action. |
trigger_status | String | Required when 'trigger_condition' is set to 'ACTION_STATUS_IS' or 'ACTION_STATUS_IS_NOT'. Defines the status that the action should or shouldn't have. Can be one of 'SUCCESSFUL', 'SKIPPED' or 'FAILED'. |
trigger_user | String | Required when 'trigger_condition' is set to 'TRIGGERING_USER_IS' or 'TRIGGERING_USER_IS_NOT'. Defines the email address of the user. |
trigger_group | String | Required when 'trigger_condition' is set to 'TRIGGERING_USER_IS_IN_GROUP' or 'TRIGGERING_USER_IS_NOT_IN_GROUP'. Defines the name of the group. |
Multiline YAML
To apply multiline in YAML, use the |
(pipe) character:
pipeline: |
first line
second line
Please mind that some fields are collections and should retain the collection structure. This applies to SSH and build actions:
- action: "Execute: ls"
type: "BUILD"
execute_commands:
- npm install
- npm test
- npm build
If you want to apply multiline in such actions, you need to define it as an element of the execute_commands
collection:
- action: "Execute: ls"
type: "BUILD"
execute_commands:
- |
npm install &&
npm test
- npm build
Last modified on September 21, 2023