buddy.works YAML

October 2023

buddy.works YAML

YAML is a human-readable data serialization language that is often used for writing configuration files. Depending on whom you ask, YAML stands for yet another markup language or YAML ain’t markup language (a recursive acronym), which emphasizes that YAML is for data, not documents. [1]

Many versions ago my favourite CMS introduced project configuration using YAML. As you make changes to system settings, Craft will record those setting values to YAML files in a config/project/ folder. You can then commit those files to your Git repository, just like your templates and front-end resources.

It offers two benefits:

  1. You’ll be able to keep track of your project’s changing state over time.
  2. You can propagate new changes to other development/staging/production environments, rather than manually reapplying them. [2]

It was a game changer and made my life so much simpler.

I recently inherited a couple of projects from an over worked colleague. In the repo was a directory called .buddy and inside was staging.yml and production.yml. I've used buddy.works in the past but had manually set up the pipeline. Turns out there's an easier way to set up a new deployment if you already have an example to copy. Of course, there's also extensive documentation from buddy.works.

Here is am example that deploys a Craft CMS site to Web Hosting Canada when I push to the "staging" branch of the remote repo. I started with the standard GUI buddy.works set up and then used the YAML Helper and switched GUI to YAML. I added the composer script from my colleague's example.

# pipeline settings
- pipeline: "The name you see displayed in buddy.works. I use 'branch name -> site url'"
  - type: "PUSH"
    - "refs/heads/name_of_branch"

  fail_on_prepare_env_warning: true

  # pipeline variables
      value: "dev.myproject.ca"
    - key: "PROJECT_URL"
      value: "https://dev.myproject.ca"
      value: "/home/username/dev.myproject.ca"
    - key: "REMOTE_SSH_HOST"
      value: "ftp.myproject.ca"
    - key: "REMOTE_SSH_PORT"
      value: "27"
    - key: "REMOTE_SSH_USER"
      value: "username"

  # pipeline actions

    # STEP 1: sftp
  - action: "sftp files to ftp.myproject.ca"
    type: "SFTP"
    local_path: "/"
    remote_path: "$REMOTE_PROJECT_ROOT"
    login: "$REMOTE_SSH_USER"
    password: "ssh_user_password"
    host: "$REMOTE_SSH_HOST"
    port: "$REMOTE_SSH_PORT"
    server_key: "ssh_server_key"
    passphrase: "ssh_server_passphrase"
    authentication_mode: "PRIVATE_KEY"

    # STEP 2: install php vendor files with composer
  - action: "Execute composer install"
    type: "SSH_COMMAND"
    working_directory: "$REMOTE_PROJECT_ROOT"
    login: "$REMOTE_SSH_USER"
    password: "ssh_user_password"
    host: "$REMOTE_SSH_HOST"
    port: "$REMOTE_SSH_PORT"
    server_key: "ssh_server_key"
    passphrase: "ssh_server_passphrase"
    authentication_mode: "PRIVATE_KEY"
    - "composer install --verbose --no-progress --no-scripts --optimize-autoloader --no-interaction"
    run_as_script: true

    # STEP ***: email notification on fail
  - action: "Email notification"
    type: "EMAIL"
    trigger_time: "ON_FAILURE"
    title: "buddy.works Project dev"
    content: "$BUDDY_PIPELINE_NAME execution #$BUDDY_EXECUTION_ID"
    recipients: "amanda.lutz@gmail.com"

[1] What is YAML?

[2] Craft CMS Project Config