Buddy YAML Schema

View as Markdown

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.

Minimal working example

yaml
# Minimal Buddy YAML pipeline example
- pipeline: build
  events:
  - type: PUSH
    refs:
    - main
  actions:
  - action: Run tests
    type: BUILD
    docker_image_name: node
    docker_image_tag: "20"
    execute_commands:
    - npm install
    - npm test

Pipeline schema

The buddy.yml file consists of a list of pipelines. Each pipeline can have events, actions, variables, and trigger conditions.

PARAMETERS

pipelinerequiredstring

The human-readable ID of the pipeline.

namestring

Display name of the pipeline shown in the UI.

definition_sourcestring enum

Source of the pipeline definition.

Allowed enum:

LOCAL,

REMOTE

refsstring[]

List of Git refs (branches, tags) that trigger this pipeline. Example: refs/heads/master, refs/tags/*

loopstring[]

Variables for dynamic pipeline execution. The pipeline runs once for each value.

prioritystring enum

Execution priority. Higher priority pipelines are executed first in the queue.

Allowed enum:

LOW,

NORMAL,

HIGH

disabledboolean

When true, the pipeline will not be triggered automatically.

disabled_reasonstring

Reason for disabling the pipeline (shown in the UI).

target_site_urlstring

URL displayed in the commit status as the target site.

execution_message_templatestring

Template for the execution message. Supports variables like $BUDDY_EXECUTION_BRANCH.

always_from_scratchboolean

When true, always clone the repository fresh instead of using cached copy.

ignore_fail_on_project_statusboolean

When true, ignore project status and trigger the pipeline anyway.

strict_contextboolean

When true, use strict context for the execution.

no_skip_to_most_recentboolean

When true, execute every revision instead of skipping to the most recent.

terminate_stale_runsboolean

When true, terminate older running executions when a new one starts.

auto_clear_cacheboolean

When true, automatically clear cache before each execution.

pausedboolean

When true, scheduled executions are paused.

pause_on_repeated_failuresinteger

Number of consecutive failures after which the pipeline schedule is paused.

fetch_all_refsboolean

When true, fetch all Git refs instead of only the triggered one.

fetch_lfsboolean

When true, fetch Git LFS files from the external repository during pipeline runs.

fail_on_prepare_env_warningboolean

When true, fail the pipeline if there are warnings during environment preparation.

concurrent_pipeline_runsboolean

When true, allow multiple executions of this pipeline to run concurrently.

clone_depthinteger

Git clone depth (0 for full clone, positive number for shallow clone).

do_not_create_commit_statusboolean

When true, do not create commit status on the Git provider.

resourcesstring enum

Resource allocation for the pipeline.

Allowed enum:

DEFAULT,

NANO,

SMALL,

MEDIUM,

LARGE,

XLARGE,

CUSTOM,

X2LARGE

remote_pathstring

Path to the remote pipeline definition file.

remote_refstring

Git ref (branch/tag) for the remote pipeline definition.

remote_project_namestring

Name of the project containing the remote pipeline definition.

remote_parametersPipelinePropertyYaml[]

Parameters passed to the remote pipeline definition.

tagsstring[]

Tags for organizing and filtering pipelines.

git_changeset_basestring enum

Base for Git changeset comparison.

Allowed enum:

LATEST_RUN,

LATEST_RUN_MATCHING_REF,

PULL_REQUEST

filesystem_changeset_basestring enum

Base for filesystem changeset comparison.

Allowed enum:

DATE_MODIFIED,

CONTENTS

cpustring enum

CPU architecture. Default: X64.

Allowed enum:

X64,

ARM,

X86

description_requiredboolean

When true, require a description when manually running the pipeline.

folderstring

Folder name to organize the pipeline in the UI.

cache_scopestring enum

Scope for caching. Default: PIPELINE.

Allowed enum:

PIPELINE,

PROJECT,

WORKSPACE

environmentsPipelineEnvironmentYaml[]

Environment configurations for the pipeline.

eventsPipelineEventYaml[]

List of events that trigger the pipeline (push, pull_request, schedule, etc.).

permissionsPermissionsYaml

Access permissions for the pipeline.

actionsAction[]

List of actions to execute in this pipeline.

variablesVariableYaml[]

Environment variables available to all actions in the pipeline.

targetsobject[]

Deployment targets configuration for transfer actions.

artifactsPipelineArtifactContextYaml[]

Artifact contexts for using container images from Buddy artifact registry.

trigger_conditionsTriggerConditionYaml[]

Conditions that must be met for the pipeline to be triggered.

Permissions schema

PARAMETERS

othersstring enum

Access level for other workspace members

Allowed enum:

DENIED,

READ_ONLY,

USE_ONLY,

BLIND,

RUN_ONLY,

READ_WRITE,

MANAGE,

DEFAULT,

ALLOWED,

STAGE,

COMMIT

usersobject

List of specific users with their access levels

groupsobject

List of user groups with their access levels

pipelinesAllowedPipelineYaml[]

List of pipelines allowed to access this resource

sandboxesAllowedSandboxYaml[]

List of sandboxes allowed to access this resource

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

PARAMETERS

typerequiredstring

Value: BUILD

actionrequiredstring

Unique identifier for the action within the pipeline.

trigger_timestring enum

Specifies when the action should be executed.

Allowed enum:

ON_EVERY_EXECUTION,

ON_SUCCESS,

ON_FAILURE,

ON_BACK_TO_SUCCESS,

ON_WARNING,

ON_WAIT_FOR_APPROVE,

ON_TERMINATE

loopstring[]

The list of variables for dynamic action execution. The action runs once for each value.

run_only_on_first_failureboolean

Defines whether the action should be executed on each failure. Restricted to and required if the trigger_time is ON_FAILURE.

disabledboolean

When set to true the action is disabled. By default it is set to false.

timeoutinteger

The timeout in seconds.

ignore_errorsboolean

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_intervalinteger

Delay time between auto retries in seconds.

retry_countinteger

Number of retries if the action fails.

run_nextstring enum

Defines whether the action should run in parallel with the next one.

Allowed enum:

WAIT_ON_SUCCESS,

IN_SOFT_PARALLEL,

IN_HARD_PARALLEL

trigger_conditionsTriggerConditionYaml[]

The list of trigger conditions to meet so that the action can be triggered.

variablesVariableYaml[]

The list of variables you can use in the action.

Info

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"

PARAMETERS

keyrequiredstring

The name of the variable

valuestring

The value of the variable

typestring enum

The type of the added variable

Allowed enum:

VAR,

FILE,

SSH_KEY,

IOS_KEYCHAIN,

IOS_PROVISION_PROFILES,

SSH_PUBLIC_KEY,

GPG_KEY

encryptedboolean

If set to true the variable value will be encrypted and hidden

descriptionstring

The optional description of the variable

init_pathstring

Initial path for the variable

defaultsstring

Default value for the variable

file_pathstring

Specifies where to copy the file on each run. Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES.

file_chmodstring

File permission set on copy to a container on each run. Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES.

file_placestring enum

Set if type is FILE, SSH_KEY, IOS_KEYCHAIN, or IOS_PROVISION_PROFILES. If it's NONE, the variable can be used as a parameter in an action. For CONTAINER, the given key is additionally copied to an action container on each run

Allowed enum:

NONE,

CONTAINER

passwordstring

Password for certificates

passphrasestring

Passphrase for encrypted SSH keys

key_identifierstring

Key identifier for iOS certificates, provisioning profiles, or GPG keys

settablestring

If set to true the variable value can be set by Buddy actions

disabledboolean

If set to true the variable is disabled and will not be injected anywhere

encodingstring enum

Encoding of the variable value. Use b64 for binary files (certificates, images, compiled blobs) where the value is already base64-encoded. Omit or set to text for plain text files (JSON, XML, config) — the system will handle encoding automatically. Only applies to non-encrypted asset variables (FILE, SSH_KEY, SSH_PUBLIC_KEY, IOS_KEYCHAIN, IOS_PROVISION_PROFILES).

Allowed enum:

text,

b64

Info

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
  - type: "EMAIL"
    prefix: "deploy"
    whitelist:
    - "admin@company.com"

PARAMETERS

typerequiredstring enum

The type of event that triggers the pipeline

Allowed enum:

PUSH,

CREATE_REF,

DELETE_REF,

PULL_REQUEST,

SCHEDULE,

PUBLISH_ARTIFACT_VERSION,

DELETE_ARTIFACT_VERSION,

WEBHOOK,

EMAIL,

CREATE_ARTIFACT_VERSION,

ENVIRONMENT_CREATE,

ENVIRONMENT_DELETE,

SANDBOX_CREATED,

SANDBOX_DELETED,

SANDBOX_TIMED_OUT,

SENTRY

refsstring[]

The list of refs (branches/tags) that trigger the pipeline for push/ref events

eventsstring[]

The list of events that trigger the pipeline. For pull request events: opened, reopened, synchronize; for type SENTRY: created, resolved

branchesstring[]

The list of branches for pull request events

artifactsPipelineArtifactContextYaml[]

The list of artifacts that trigger the pipeline

start_datestring

The start date for scheduled events (type SCHEDULE)

delayinteger

The delay in minutes between scheduled runs (type SCHEDULE)

cronstring

The cron expression for scheduled (type SCHEDULE) events e.g., '0 9 __ 1-5' for weekdays at 9 AM

timezonestring

The timezone for scheduled events (type SCHEDULE) e.g., 'UTC', 'Europe/Warsaw'

totpboolean

Whether TOTP (Time-based One-Time Password) is enabled for webhook events (type WEBHOOK)

prefixstring

The email subject prefix for email trigger events (type EMAIL)

whiteliststring[]

The list of allowed email addresses that can trigger the pipeline via email (type EMAIL)

environmentsPipelineEnvironmentYaml[]

The list of environments that trigger the pipeline (type ENVIRONMENT_CREATE or ENVIRONMENT_DELETE)

targetsobject[]

The list of sandbox targets that trigger the pipeline for sandbox events (type SANDBOX_CREATED, SANDBOX_DELETED, SANDBOX_TIMED_OUT)

integrationstring

The identifier of the Sentry integration that triggers the pipeline (type SENTRY)

projectsstring[]

The list of Sentry projects that trigger the pipeline (type SENTRY)

levelsstring[]

The list of Sentry issue levels that trigger the pipeline (type SENTRY)

statusesstring[]

The list of Sentry issue statuses that trigger the pipeline (type SENTRY)

substatusesstring[]

The list of Sentry issue substatuses that trigger the pipeline (type SENTRY)

countinteger

The minimum number of Sentry events required to trigger the pipeline (type SENTRY)

user_countinteger

The minimum number of affected users required to trigger the pipeline (type SENTRY)

snooze_minutesinteger

Prevents the same Sentry issue from triggering this pipeline more than once within the specified time window (in minutes, max 20160 = 14 days; type SENTRY)

Trigger conditions 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"

PARAMETERS

trigger_conditionrequiredstring enum

The type of trigger condition

Allowed enum:

ALWAYS,

ON_CHANGE,

ON_CHANGE_AT_PATH,

VAR_IS,

VAR_IS_NOT,

VAR_CONTAINS,

VAR_NOT_CONTAINS,

DATETIME,

SUCCESS_PIPELINE,

DAY,

HOUR,

OR,

VAR_LESS_THAN,

VAR_LESS_THAN_OR_EQUAL,

VAR_GREATER_THAN,

VAR_GREATER_THAN_OR_EQUAL,

ACTION_STATUS_IS,

ACTION_STATUS_IS_NOT,

TRIGGERING_USER_IS,

TRIGGERING_USER_IS_NOT,

TRIGGERING_USER_IS_IN_GROUP,

TRIGGERING_USER_IS_NOT_IN_GROUP

trigger_variable_valuestring

The value to compare the trigger variable against

trigger_variable_keystring

The name of the variable to check in the trigger condition

timezonestring

The timezone for datetime trigger conditions (e.g., 'UTC', 'Europe/Warsaw')

trigger_hoursinteger[]

The hours when the datetime trigger should activate (0-23)

trigger_daysinteger[]

The days when the datetime trigger should activate (1-7, where 1 is Monday)

projectstring

The project name for cross-project pipeline triggers

pipelinestring

The pipeline name for cross-pipeline triggers

trigger_userstring

The email of the user who can trigger the pipeline

trigger_groupstring

The name of the group that can trigger the pipeline

trigger_condition_pathsstring[]

The file paths that must change to trigger the pipeline

trigger_statusstring enum

The action status to check for action status triggers

Allowed enum:

SUCCESSFUL,

FAILED,

SKIPPED,

SUPPRESSED

trigger_action_namestring

The name of the action to check status for

trigger_operandsTriggerConditionYaml[]

The list of nested trigger conditions for OR/AND operators

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

YAML loops

Pipeline loop

Use loop to select variable keys to iterate over, with values separated by newlines or commas. Each value triggers a separate pipeline run. When multiple keys are listed, all combinations are executed.

Learn more about pipeline loop in the full documentation.

yaml
- pipeline: "Deploy to Production"
  refs:
  - "*"
  loop:
  - deployment_strategy
  - region
  variables:
  - key: deployment_strategy
    value: "canary, rolling"
  - key: region
    value: |
      eu-west
      us-east
      ap-south

Action loop

Select variable keys to iterate over, with values separated by newlines or commas. Each value triggers a separate action run. With multiple keys, all combinations are executed.

yaml
  actions:
  - action: Test on Node $node_version
    type: BUILD
    loop:
    - node_version
    docker_image_name: node
    docker_image_tag: $node_version
    execute_commands:
    - npm install
    - npm test
    shell: BASH
    variables:
    - key: node_version
      value: "18, 20, 22"

Last modified on Apr 22, 2026

YAML vs GUI