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_RUN_COMMIT_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_scope BETA	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.

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

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`.

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

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`.

Hint

Learn more about encrypting variables in Buddy YAML.

Event schema

Here's how to define the event triggering the pipeline:

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

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:

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

Amazon S3