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:
yaml- 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" description_required: true - 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. |
git_changeset_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 . |
cache_scopeBETA | String | Docker cache scope. Available values: WORKSPACE , PROJECT , PIPELINE . By default, it is set to PIPELINE . |
description_required | Boolean | The default value is false . If set to true and the user does not provide a description when starting a pipeline, the pipeline won't run. |
pause_on_repeated_failures | Integer | Pauses the pipeline after n failed pipeline runs. Restricted to pipelines set to 'on: SCHEDULE'. Possible values: 1-100 (the default value is 100). |
filesystem_changeset_base | String | Defines changeset calculation method whenever deployment action has input_type set to BUILD_ARTIFACTS . Default set to DATE_MODIFIED . Possible values: DATE_MODIFIED , CONTENTS |
Permissions 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. |
yamlpermissions: 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:
yaml- pipeline: "production" on: "CLICK" refs: - "refs/heads/master" execution_message_template: "test" filesystem_changeset_base: "CONTENTS" 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 | String | Defines whether the action should run in parallel with the next one. Possible values: WAIT_ON_SUCCESS (no parallel), IN_SOFT_PARALLEL (run as soon as a runner is available), IN_HARD_PARALLEL (run only with enough runners). The default value is ON_EVERY_EXECUTION |
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:
yamlvariables: - 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 . |
Event schema
Here's how to define the event triggering the pipeline:
yamlevents: - 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 runner 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:
yamltrigger_conditions: - trigger_condition: "VAR_IS" trigger_variable_value: "expectedValue" trigger_variable_key: "myVar" - trigger_condition: "ON_CHANGE"
The default operator for multiple trigger conditions is AND
if you want to use OR
you have to include it:
yamltrigger_conditions: - trigger_condition: OR trigger_operands: - trigger_condition: "VAR_NOT_CONTAINS" trigger_variable_value: "test" trigger_variable_key: "BUDDY_EXECUTION_URL" - trigger_condition: "VAR_IS" trigger_variable_value: "asd" trigger_variable_key: "BUDDY_EXECUTION_URL"
Properties
Name | Type | Description |
---|---|---|
trigger_condition | String | Defines when the action should be run. Can be one of ON_CHANGE , OR , 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', 'SUPRESSED' 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:
yamlpipeline: | first line second line
Please mind that some fields are collections and should retain the collection structure. This applies to SSH and build actions:
yaml- 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:
yaml- action: "Execute: ls" type: "BUILD" execute_commands: - | npm install && npm test - npm build
Last modified on Oct 31, 2024