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"
- pipeline: "build"
on: "EVENT"
events:
- type: "PUSH"
refs:
- "*"
Properties
Name | Type | Description |
---|---|---|
pipeline Required | String | The ID of the pipeline. |
on Required | String | The trigger mode of the pipeline. Can be one of 'CLICK', 'EVENT', 'SCHEDULE'. |
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'. |
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. |
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. |
On top of these properties every action has a set properties unique to its type. You can read how to define each type of action in separate articles.
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!xgXxzMBVkpGEp4sRMxUIEL4TFQSZQv6PklzVGeRYPLOKYR/nNXTTKzYABWNGSgFZenjhGy5sMu8SBEDZAsZI9I188jdF3x5cHkxzq0kwvlR/wX9Cglf+PAkn1TsaNxJf4e2i7hufE5PGJoideIqMH30obPH9xDUXKLZl6lhm63HfgyPzyK9DsC7BAgYXHDsqRbh+Ny/pt7WN5RzrXXZ/4u6zaaKR/dGvPmFMVephLCjDOzjbRsF+56pPVVBOdGLx7sl5rtJVBn41VB2vSfoOoGU+f4GTxnkoctfcCQN/9NUOTBmXZSDX/JGKEDYDp3nVLhaeCw7+3oknwy33B/pRfleLEvW9Qa9RvF3Kbk6A8hPFAWt5koYlD2zTy8B2+13aHB0Chc5uW5seGTDKUuVBCmmp6LFVABP6j+WD/ms1JWaQ0ZH68g6S7+qquq/iu4uvRdtYN1X02YUew6qR+EOGebsoOoYAm1ZsnzvsCj5K9Q+Ouxj3pNr8UMktkwMsCsIJDac0SX9GyhJDsv04HJJOVnxqDNF988qphxHQ+2a7X3w/BWqpbeJhkuBOWeXAiq+fpHF2RKRRWs4uNHLVCc5sGRzSOxl2tgE5ClYCOlQzjs7amQa6UyhZCVLyCP8BmDEfKlUwM93RGIp+OGV5PmIn4MNZNaNRFCUayAGHDixeIGckegsJ1lryIWazAU3v7sHXrKs+OjWW9pCxnVS0b/0VU+77ZgbAH2sroHKTfITIlnfZvb/0h72UtRI/SC2qvIE8yBEVb5saIVZ5BQxY0FjHGwN7Z1kS2ocNqE+lLO3XR1kzBP3KSm5di/WpCodJkh10oqWuQVfyrXjzu3z6aC0MwAOocR6u4/di43ljL4by78iQNoIqdAMl2T8LOPJLTeftmIJNtwvPC6qHGPFNyj4jId/M8Rap4alHz3CS5cDA7QwGk6t9y5jUW3CmgrMC72otSUv5Tpw8u2n2W40xfl4o/Yo+cVoMgjWQy+ySeyO9SrnUP+eWUyQv0KMpA2DLlbXSVqD7cFmJiUgGML8KUiJUzuEyJC2BydgtHVhsppNwQ8ePDDR2sTVTcFsNoPfEw80WUGpOOdlwGxE3Q7lEf0WNSFwTmnF0xKRZeK5pbNJ2gWM6/h2QvICbNTUFa4FwqJml/Yg8yq8w0oIQ6LhAygNjlmyMVNpPbDvFgCv1tov8N08ifA6jCg2vu1V4857kbBAvqSgbFm5zp9DB9qz++WWT/d7NFuxAvOGJqEF+D9qZldOTQoFOXv+WgYDyn8KNppXlUcCEVG52kTT22k1YkUZMboPWJMymsBRkEl3DIVeJ6ad51Qs9xGaYJyBE98jvP37It233bTmkWuoOKqO6Irfi7yarMbtTJx/vAYE/MU+R5WsPFvx8gLB7tjjoETKjnFFV0KpH9nrwApHTXb5EimySyVo6BFl9bM2It4o8FwIPMFtECdG2b/Xko9T6KWDISmKDnGYFsWb8Lt8tO4Qm1xQ+Y2AnZFBxH5di+Hu6CwhvTncC8vEetgss+m2X7o0QB7EhJ6SjH9ksbrqg02++TZbzKcwVker1tMp4IcI7R+iBtjvv3YN43VtjIeIXGQtSxehF5bpiN+vSPYvxccfdJUtbtTawBiSlapob1xqx94NaL/8aNbzOt794xORhxtKMIk5VqW8lh378p4vm1WiziWZAIOU+hMB0WWLLVGtivMMk5fW9JJ0FWoVXlUUgmm8coJcjQgPRh5y8lm4u8/PNEMkMiY0Qvl+id0GA07MMjCpu80n0TuNMvD2qJtcKheenbKb/6bpHj+c5HFk7C5A4VBpmEiCdAJvOHXheqi9aq2lHYxM4VyXCQiv5bnZ4mGpiD0jZLQF0YhLgffNdrG3tObcdHJj8iMQbZrRgSInb6pfg1FQVeoLqd0qe5Uzi6L9imVz14eSk9M9+x6F4AbPfX9KxjHsuk5Kao3iz3Ua5pcjJ/2L8Wpmwo8+nl/aXO1is6k9wzdZo4LUDKMUDNCXQrfIFej4zMa9C5gluI46S2QqTxlPHL7YdWK2flt0uLDW3rDlOG2LiJP+MMXwGZdAkqWDz37UoeY3KWSSGfuJXH3K5lGJqbKV9bkldDBOXJ1rfpZ+0qpDc1hB6FzIvitnylXNerXcmQd9GZvVo4dYdmfPDrm9Y+/7sx9tO5IJejnI2ID3DBiVWPKWaL/minxrvL+MQsAwtjBErIEpX/+x5wVnC5LqsNJCguQpejsHlpAp2mC3L.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
The salt which is used to encrypt the values is unique for each workspace. If you change it, you will need to change all encrypted values in your YAMLs.
The value should be changed only when you move your pipelines with the export/import option – either to another workspace, or from Cloud to the on-premises version.
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 build action should be run. Can be one of 'ALWAYS', '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' or 'SUCCESS_PIPELINE'. Can't be used in deployment actions. |
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. |
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 January 9, 2023