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

NameTypeDescription
pipeline RequiredStringThe ID of the pipeline.
onStringThe trigger mode of the pipeline. Can be one of CLICK, EVENT, SCHEDULE. If not set, the default value is EVENT
refsString[]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.
eventsEvent[]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_conditionsTriggerCondition[]The list of trigger conditions to meet so that the pipeline can be triggered.
always_from_scratchBooleanDefines whether or not to upload everything from scratch on every execution.
auto_clear_cacheBooleanDefines whether or not to automatically clear cache before running the pipeline .
no_skip_to_most_recentBooleanDefines whether or not to skip execution to the most recent execution.
do_not_create_commit_statusBooleanDefines whether or not to omit sending commit statuses to Github or Gitlab upon execution.
start_dateiso 8601 utc dateRequired 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
delayIntegerRequired 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).
cronStringRequired if the pipeline is set to on: SCHEDULE and neither start_date nor delay is specified. The standard CRON expression defining the execution schedule.
actionsAction[]The list of actions executed in the pipeline.
variablesVariable[]The list of variables you can use in the pipeline.
ignore_fail_on_project_statusBooleanIf set to true the status of a given pipeline will not impact the project status on the dashboard.
execution_message_templateStringThe title of every execution in this pipeline. By default it is set to $BUDDY_EXECUTION_REVISION_SUBJECT.
target_site_urlStringThe URL of the target website.
disabledBooleanSet it, if you want the pipeline to be disabled.
disabled_reasonStringSpecify the reason for disabling the pipeline.
fetch_all_refsBooleanWhen 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.
permissionsPipelinePermissionsDefine to set permissions for the pipeline.
git_changeset_baseStringDefines 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_scopeBETAStringDocker cache scope. Available values: WORKSPACE, PROJECT, PIPELINE. By default, it is set to PIPELINE.
description_requiredBooleanThe 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_failuresIntegerPauses 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_baseStringDefines 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

NameTypeDescription
othersStringAccessLevel for the group Others. Can be one of 'DENIED', 'DEFAULT', 'READ_ONLY', 'RUN_ONLY', or 'READ_WRITE'. Default setting is 'DEFAULT' (Project role).
usersUserPermission[]The list of users who will be granted a permission other than the Others group.
groupsGroupPermission[]The group who will be granted a permission other than the Others group.
yaml
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:

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

NameTypeDescription
action RequiredStringThe ID of the action.
type RequiredStringThe type of the action.
variablesVariable[]The list of variables you can use the action.
trigger_conditionsTriggerCondition[]The list of trigger conditions to meet so that the action can be triggered.
timeoutIntegerThe timeout in seconds.
disabledBooleanWhen set to 'true' the action is disabled. By default it is set to false.
run_nextStringDefines 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_failureBooleanDefines whether the action should be executed on each failure. Restricted to and required if the 'trigger_time' is ON_FAILURE.
ignore_errorsBooleanIf 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_intervalIntegerDelay time between auto retries in seconds.
retry_countIntegerNumber of retries if the action fails.
trigger_timeStringSpecifies 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.
Hint
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:

yaml
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

NameTypeDescription
key RequiredStringThe name of the variable.
value RequiredStringThe value of the variable. If the 'type' is FILE, the value must be Base64 encoded.
typeStringThe type of the added variable. Can be one of VAR, SSH_KEY or FILE.
descriptionStringThe optional description of the variable.
encryptedBooleanWhen set to 'true' the variable value will be encrypted and hidden.
settableBooleanWhen set to 'true' the variable value can be shifted between subsequent actions or executions as well as pipelines.
file_placeStringAvailable 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_pathStringSpecifies where to copy the file on each run. Set if type is SSH_KEY or FILE.
file_chmodStringFile 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:

yaml
events: - type: "PUSH" refs: - "refs/heads/master" - "refs/heads/dev-*

Properties

NameTypeDescription
type RequiredStringThe type of the event. Available values: 'PUSH', 'CREATE_REF', 'DELETE_REF'.
refs RequiredStringThe list of refs for which the pipeline will be triggered in the given event.
tagsStringRuns 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:

yaml
trigger_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:

yaml
trigger_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

NameTypeDescription
trigger_conditionStringDefines 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_pathsString[]Required when 'trigger_condition' is set to ON_CHANGE_AT_PATH.
trigger_variable_keyStringRequired 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_valueStringRequired 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_hoursInteger[]Available when trigger_condition is set to HOUR. Defines the time – by default running from 1 to 24.
trigger_daysInteger[]Available when trigger_condition is set to DAY. Defines the days running from 1 to 7 where 1 is for Monday.
zone_idStringAvailable when trigger_condition is set to DAY or HOUR. Defines the timezone (by default it is UTC) and takes values from here.
trigger_project_nameStringRequired when trigger_condition is set to SUCCESS_PIPELINE. Defines the name of the project in which the trigger_pipeline_name is.
trigger_pipeline_nameStringRequired when trigger_condition is set to SUCCESS_PIPELINE. Defines the name of the pipeline.
trigger_action_nameStringRequired when trigger_condition is set to 'ACTION_STATUS_IS' or ACTION_STATUS_IS_NOT. Defines the name of the action.
trigger_statusStringRequired 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_userStringRequired when trigger_condition is set to TRIGGERING_USER_IS or TRIGGERING_USER_IS_NOT. Defines the email address of the user.
trigger_groupStringRequired 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:

yaml
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:

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