BasicsPipelinesActions & ServicesEnvironmentsIntegrationsTargetsDomainsSandboxesSelf-HostedAgents & TunnelsYAMLBuddy GitFAQAPI

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"
  refs:
  - "refs/heads/master"
  variables:
  - key: "username"
    value: "Buddy"
    settable: "disabled"
    description: "var_descrption"
  change_set_base: "LATEST_RUN_MATCHING_REF"
  description_required: true  
- pipeline: "build"
  events:
  - type: "PUSH"
    refs:
    - "*"

Properties

Name Type Description
pipeline Required String The ID of the pipeline. Should consist of lowercase letters, digits, and underscores, and start with a letter.
name String Display name of the pipeline.
refs String[] Pipeline context refs. If unset and Events is empty, the pipeline counts as codeless.
events Event[] The list of events for which the pipeline will be triggered.
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.
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.
docker_build_cache 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"
  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: "enabled"
      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: "id_public_ssh_key"
    value: "ssh-rsa AAAAB3NzaC1yc3EAAAABIwAAAQEA0af9YuXUugKPsLCZzMu1R7bLLSyCrSlLlnR+Nj8FuYaVj/rHbPBk0g6Rg3zEj8H4AffVv7Lr/K9O8L7EYl9QRZoi24UfSiR4RYQvOXLSBNbs/5FO0Vl/Fo6m83OQ91gxdEKzPLYDKBBZfilz2DY2mOxzs9GtI+MoESLV2w/VjIT3ZB6xoz0EFTm20r81/HsFkX1QRz6WGEIxGt1r8R8NpvSJf/W3nIQQCGgV1gVISaJ3Oevuozhs8DIWna3eKv0umAdM2Y3aPIxKJCqeo7LmE9bzPEoMM//h0I/hgPImcDVRfemz7j/kfOqmcfq12kA47k1nZtSipX0Bay3kCPjQDw=="
    type: "SSH_PUBLIC_KEY"
    description: "Production server SSH public key"
    path: "~/.ssh/id_sandbox_pub"
    chmod: 600
  - 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, SSH_PUBLIC_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 String The variable value can be shifted between subsequent actions or executions as well as pipelines. Available values DISABLED, ENABLED, RUN_ONLY(available only if type=VAR).
file_place String Available values: CONTAINER, NONE. Set if type is SSH_KEY, SSH_PUBLIC_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, SSH_PUBLIC_KEY or FILE.
file_chmod String File permission set on copy to a container on each run. Set if type is SSH_KEY, SSH_PUBLIC_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:
  - ":context"
  - "refs/heads/dev-*"
- type: "PULL_REQUEST"
  events:
  - "assigned"
  - "unassigned"
  branches:
  - "main"
  - "relesaes/*"
- type: "WEBHOOK"
  totp: true

Properties

Name Type Description
type Required String The type of the event. Available values: PUSH, CREATE_REF, DELETE_REF, PULL_REQUEST, SCHEDULE, WEBHOOK.
refs String[] The list of refs for which the pipeline will be triggered in the given event. Settable if type is PUSH, CREATE_REF, DELETE_REF, SCHEDULE. If you want to inherit Git context of the pipeline provide :context. Defaults: If pipeline refs are set, then the default refs value in the event are set to :context. If pipeline refs are not set, then for the event type SCHEDULE default refs value in the event is an empty array, and for event types PUSH, CREATE_REF or DELETE_REF default refs value in the event is set to *.
events String[] Required if type is PULL_REQUEST. A list of pull request events that will trigger the pipeline. Available values: assigned, unassigned, labeled, unlabeled, opened, edited, closed, reopened, synchronize, converted_to_draft, locked, unlocked, milestoned, demilestoned, ready_for_review, review_requested, review_request_removed, auto_merge_enabled, auto_merge_disabled.
branches String[] Required if type is PULL_REQUEST. A list of filters for the base in the pull request.
start_date ISO 8601 UTC date Required if type is SCHEDULE and no cron is specified. Defines when the pipeline execution should start. Format: 2016-11-18T12:38:16.000Z
delay Integer Required if type is SCHEDULE and no cron is specified. Defines the intervals in which the pipeline should be executed (in minutes).
cron String Required if type is SCHEDULE and neither start_date nor delay is specified. Standard CRON expression defining execution schedule.
timezone String Available when type is SCHEDULE and cron is specified. Defines timezone base for the CRON. Default is UTC. Timezone codes are taken from here.
totp Boolean Available when type is WEBHOOK. Defines whether TOTP authentication is enabled for the webhook.

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 'ACTIONSTATUSIS' 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

Schedule examples

Simple scheduled run every hour starting on 01.01.2025 8:00 UTC (codeless)

yaml
  events:
  - type: SCHEDULE
    start_date: 2025-01-01T08:00:00Z
    delay: 60

Schedule run every day at 8:00 UTC starting on 01.01.2025 for branches dev and stage

yaml
  events:
  - type: SCHEDULE
    start_date: 2025-01-01T08:00:00Z
    delay: 1440
    refs:
    - refs/heads/dev
    - refs/heads/stage

Schedule run every day at 8:00 America/New_York for all dev-* branches:

yaml
  - type: SCHEDULE
    refs:
    - refs/heads/dev-*
    cron: 0 8 * * *
    timezone: America/New_York

Last modified on Oct 8, 2025

Next pageYAML vs GUI