YAML Configuration Reference

BuildNinja allows you to use Custom YAML Configuration Files with the Config File runner, in addition to exported configurations. The following sections describe the structure, required fields, and supported options for YAML configuration files. Use this reference to understand or modify configuration files before reusing them across projects.

YAML File Overview

YAML configuration files define the complete build setup, including version control steps, build steps, and artifact rules. These files can be exported from BuildNinja or created manually by users and executed using the Config File runner.

When a configuration is exported, the YAML file is automatically named after the build configuration. For custom YAML files, you can choose any meaningful name that reflects the purpose of the build, using the following format:

<configuration-name>.yaml

Refer to the following examples to understand the naming format:

backend-build.yaml
nightly-tests.yaml
release-build.yaml

The filename itself does not affect build execution. However, the correct file path to the YAML file must be specified in the execution step for the build to run successfully. For step-by-step guidance on adding the YAML file to a build configuration and running the build, see Run Builds Directly from YAML FileBuildNinja allows you to export build configuration settings as a YAML file, enabling build configurations to be reused across projects without manually recreating execution steps..

Basic Structure

A YAML configuration file defines the build configuration metadata and all execution-related settings. The top-level structure consists of basic identification fields followed by a settings section that contains the actual build logic.

Top-Level Fields

Field	Description
name	The name of the build configuration. This value is used for identification and does not need to match the filename.
description	A brief description of the build configuration’s purpose.
version	The configuration file version. This can be used to track changes or compatibility over time.

Settings Section

The settings section defines the operational behavior of the build. It contains one or more of the following subsections:

Section	Description
vcs-steps	Defines version control actions such as repository checkout and authentication details.
build-steps	Specifies the build execution steps, including runners, commands, and parameters.
artifacts	Defines which files or directories are collected after the build completes and under what conditions.

Each subsection is optional depending on the use case, but required fields within a section must be provided when that section is used.

Refer to the following example for the minimal top-level structure of a YAML configuration file:

# Name of the build configuration (does not need to match the filename).
name: config-name

# Description of what this build configuration does.
description: Sample configuration file

# Version of the configuration format.
version: 1.0

# Execution-related settings.
settings:
  vcs-steps:     # Version control configuration.
  build-steps:   # Build execution steps.
  artifacts:     # Artifact collection rules.

Required BuildNinja Settings

When running builds using the Config File runner, most of the build logic is defined in the YAML configuration file rather than in the BuildNinja UI. As a result, build steps and artifact settings do not need to be configured in the UI, because they are read directly from the YAML file at runtime.

However, the following settings must still be configured in BuildNinja before running the build:

• Basic Information: Used to identify the build configuration within the project.
• VCS Settings: Required to connect to the repository that contains the YAML configuration file.

These UI settings are required only to locate and load the YAML file; all build execution logic is controlled by the configuration file itself.

During execution, BuildNinja loads and executes all build steps, runners, and artifact rules exactly as defined in the YAML configuration file.

Build Steps Definition

Each build step defines a unit of execution within the build process.

• All required fields for a build step must be provided.
• Optional fields may be left empty or omitted if not needed.

Build steps are executed in the order in which they appear in the YAML file.

Common Fields in Build Steps

Each entry under build-steps uses the following common fields:

Field	Description
name	A human-readable name for the build step, shown in logs and the BuildNinja UI.
key	Identifies the runner used to execute the step.
disabled	Controls whether the step is executed. Set to true to skip the step.
workDir	The working directory from which the step is executed on the build agent.
args	Contains runner-specific arguments required for execution.
argsProtected	Stores sensitive values securely (if applicable).

Supported Runners

The following runners are supported in YAML configuration files:

Runner	Runner Key	Description
Command Line	runner_cmd	Executes shell commands.
MSBuild	runner_msbuild	Builds MSBuild solutions.
VSTest	runner_vstest	Executes VSTest assemblies.
Config File	runner_configfile	Not required in YAML.
SSH	runner_ssh	Executes commands on remote machines over SSH.
Script	runner_script	Executes scripts using a specified shell.

Command Line Runner (runner_cmd)

The Command Line runner executes shell commands on the build agent.

Arguments

• commands: The command or commands to execute.

Refer to the following example for single command configuration:

- key: runner_cmd                # Uses Command Line runner.
  name: Print Hello World        # Step name.
  disabled: false                # Enables the execution step.
  workDir: ""                    # Working directory (empty uses default).
  args:
    commands: echo "Hello, World!"  # The shell command to execute.
  argsProtected: {}                 # Place sensitive info here if needed.

Refer to the following example for multiple commands configuration:

- key: runner_cmd                # Uses Command Line runner.
  name: Network Diagnostics      # Step name.
  disabled: false                # Enables the execution step.
  workDir: ""                    # Working directory (empty uses default).
  args:
    commands: |-                 # Multi-line shell commands.
      ping -w 5 www.google.com   
      ping -w 5 github.com       
  argsProtected: {}              # Place sensitive info here if needed.

MSBuild Runner (runner_msbuild)

The MSBuild runner builds Visual Studio and MSBuild-based solutions.

Arguments

• solution: Path to the solution file.
• configuration: Build configuration (for example, Debug or Release).
• parameters: Additional MSBuild parameters.

Refer to the following example for single command configuration:

- key: runner_msbuild             # Uses MSBuild runner.
  name: Build Solution            # Step name.
  disabled: false                 # Enables the execution step.
  workDir: ""                     # Working directory (empty uses default).
  args:
    solution: MyApp.sln           # Path to the solution file to build.
    configuration: Release        # Build configuration.
    parameters: ""                # Optional additional MSBuild parameters.

Refer to the following example for multiple parameters configuration:

- key: runner_msbuild                 # Uses MSBuild runner.
  name: Build with Custom Parameters  # Step name.
  disabled: false                     # Enables the execution step.
  workDir: ""                         # Working directory (empty uses default).
  args:
    solution: MyApp.sln               # Path to the solution file to build.
    configuration: Debug              # Build configuration.
    parameters: "/m /p:Platform=x64"  # Additional MSBuild parameters (multi-core build and target platform).

VSTest Runner (runner_vstest)

The VSTest runner executes test assemblies and generates test reports.

Arguments

• testAssembly: Path to the test assembly.
• reportDir: Directory for test reports.
• reportName: Name of the test report.
• failCriterian: Criteria for failing the build.
• args: Additional VSTest arguments.

Refer to the following example for single test assembly:

- key: runner_vstest              # Uses VSTest runner.
  name: Run Unit Tests            # Step name.
  disabled: false                 # Enables the execution step.
  workDir: ""                     # Working directory (empty uses default).
  args:
    testAssembly: tests/MyApp.Tests.dll  # Path to the test assembly (DLL).
    reportDir: reports                   # Directory where test reports will be saved.
    reportName: test-results             # Name of the test report file.
    failCriterian: failedTests           # Defines when the build fails.
    args: ""                             # Optional additional command-line arguments.

Refer to the following example for multiple arguments configuration:

- key: runner_vstest                  # Uses VSTest runner.
  name: Run Tests with Filters        # Step name.
  disabled: false                     # Enables the execution step.
  workDir: ""                         # Working directory (empty uses default).
  args:
    testAssembly: tests/MyApp.Tests.dll      # Path to the test assembly (DLL).
    reportDir: reports                       # Directory where test reports will be saved.
    reportName: filtered-results             # Name of the test report file.
    failCriterian: failedTests               # Defines when the build fails.
    args: "--TestCaseFilter:Category=Smoke"  # Additional VSTest argument to filter test cases.

SSH Runner (runner_ssh)

The SSH runner executes commands on remote machines from the build agent using SSH.

Arguments

• host: SSH host address.
• port: SSH port number (default: 22).
• user: SSH user name.
• authType: Authentication type (password, defaultKey, or customKey).
• commands: Commands to execute on the remote machine.

Refer to the following example for SSH configuration using password authentication:

- key: runner_ssh                   # Uses SSH runner.
  name: Remote Deployment           # Step name.
  disabled: false                   # Enables the execution step.
  workDir: ""                       # Working directory (empty uses default).
  args:
    host: example.com               # SSH host address.
    port: 22                        # SSH port (default is 22).
    user: deploy                    # SSH user name.
    authType: password              # Authentication type.
    commands: |-                    # Commands to execute on the remote machine.
      cd /var/www/app
      ./deploy.sh
  argsProtected:
    password: ${SSH_PASSWORD}       # SSH password (stored securely).

Refer to the following example for SSH configuration using a custom SSH key:

- key: runner_ssh                       # Uses SSH runner.
  name: Remote Commands with SSH Key    # Step name.
  disabled: false                       # Enables the execution step.
  workDir: ""                           # Working directory (empty uses default).
  args:
    host: example.com                   # SSH host address.
    port: 22                            # SSH port (default is 22).
    user: deploy                        # SSH user name.
    authType: customKey                # Authentication type.
    commands: |-                        # Commands to execute on the remote machine.
      docker ps
      docker restart app
  argsProtected:
    sshKey: ${SSH_PRIVATE_KEY}          # Custom SSH private key.
    passphrase: ${SSH_KEY_PASSPHRASE}   # Passphrase for the SSH key (if required).

Script Runner (runner_script)

The Script runner executes scripts using a specified shell on the build agent.

Arguments

• shell: Shell in which the script is executed.
• script: Script content to execute.

Refer to the following example for script execution:

- key: runner_script               # Uses Script runner.
  name: Run Deployment Script      # Step name.
  disabled: false                  # Enables the execution step.
  workDir: ""                      # Working directory (empty uses default).
  args:
    shell: bash                    # Shell used to execute the script.
    script: |-                     # Script content to execute.
      echo "Starting deployment"
      ./deploy.sh

Refer to the following example for inline script execution:

- key: runner_script                 # Uses Script runner.
  name: Inline Build Steps           # Step name.
  disabled: false                    # Enables the execution step.
  workDir: ""                        # Working directory (empty uses default).
  args:
    shell: bash                      # Shell used to execute the script.
    script: |-                       # Inline script commands.
      echo "Cleaning workspace"
      rm -rf build/

      echo "Building application"
      npm install
      npm run build

      echo "Build completed"

Artifacts Configuration

Artifacts specify the files or directories to be collected after a build completes. These artifacts are evaluated once the build finishes and are uploaded according to the configured condition.

Common Fields in Artifacts

Each entry under artifacts uses the following common fields:

Field	Description
name	Logical name for the artifact set
condition	Determines when artifacts are collected
paths	Files or directories to collect

Artifact Conditions

The condition field determines when artifacts are collected and supports the following values:

• always: Collect artifacts regardless of build result.
• buildSucceeds: Collect artifacts only if the build succeeds.
• buildFails: Collect artifacts only if the build fails.

Simple Artifact Configuration (Recommended)

For most use cases, artifacts can be defined by directly listing file or directory paths.

Refer to the following example for single path configuration:

artifacts:
- name: build-output               # Name of the artifact.
  condition: buildSucceeds         # Condition to collect artifact.
  paths:
  - output/dist                    # Path to the files or directories to collect.

Refer to the following example for multiple paths configuration:

artifacts:
- name: my_first_artifacts         # Name of the artifact.
  condition: buildFails            # Condition to collect artifact.
  paths:
  - UI/IO                          # First path to include.
  - IO/SI/PO-IO                    # Second path to include.

Each artifact path must be listed as a separate entry.

Advanced Artifact Configuration (Nested Paths)

For more complex scenarios, artifacts can be grouped using nested definitions. This allows additional organization and conditional control over specific artifact sets.

Refer to the following example for nested artifact configuration:

artifacts:
- name: upload artifacts             # Name of the top-level artifact collection.
  condition: always                  # Condition to collect artifact.
  paths:
  - name: build-output               # Name of the nested artifact.
    condition: 0                     # Condition for nested artifact (0 typically means ignore or no specific condition).
    paths:
    - output/main                    # Path of files or directories to include in the nested artifact.

note

• Nested artifact definitions allow grouping related outputs.
• The outer condition controls when the artifact group is evaluated.
• Inner paths define the actual files or directories to collect.
• Nested conditions are intended for advanced use cases and are not required for standard builds.
• Use simple path-based artifacts for most builds.
• Add nested artifacts only when grouping or advanced control is needed.
• Ensure all artifact paths exist on the build agent.
• Keep artifact names descriptive and meaningful.

Complete YAML Configuration Example

Refer to the following example for a full YAML configuration file that includes VCS settings, build steps, and artifact configuration:

# Name of the build configuration used for identification within BuildNinja.
name: backend-build

# Brief description of what this build does.
description: Complete build configuration example

# Version of the configuration file.
version: 1.0

settings:
  # Version Control Configuration
  vcs-steps:
    - name: Checkout Repository           # Display name for the VCS step.
      key: vcs_git                        # Specifies Git as the VCS type.
      disabled: false                    # Set to true to skip repository checkout.
      args:
        url: https://github.com/example/backend-service.git  # Repository URL.
        branch: main                                       # Branch to checkout.
        authType: pat                                     # Authentication type (PAT).
        username: build-user                              # Username for repository access.
      argsProtected:
        token: your-personal-access-token                 # Securely stored access token.

  # Build Execution Steps
  build-steps:
    - key: runner_cmd                      # Uses Command Line runner.
      name: Install Dependencies           # Step name shown in logs and UI.
      disabled: false                      # Executes this step.
      workDir: ""                          # Working directory (empty = default).
      args:
        commands: |-                       # Multiple shell commands.
          npm install                      # Install project dependencies.
          npm run lint                     # Run lint checks.
      argsProtected: {}                    # No sensitive values for this step.

    - key: runner_msbuild                  # Uses MSBuild runner.
      name: Build Application              # Builds the application using MSBuild.
      disabled: false
      workDir: ""
      args:
        solution: BackendService.sln       # Path to the solution file.
        configuration: Release             # Build configuration.
        parameters: "/m"                   # Additional MSBuild parameters.

    - key: runner_vstest                   # Uses VSTest runner.
      name: Run Unit Tests                 # Executes automated tests.
      disabled: false
      workDir: ""
      args:
        testAssembly: tests/BackendService.Tests.dll  # Test assembly path.
        reportDir: reports                            # Directory for test reports.
        reportName: unit-test-results                 # Report file name.
        failCriterian: failedTests                    # Fail build if tests fail.
        args: ""                                      # Additional VSTest arguments.

  # Artifact Collection
  artifacts:
    - name: build-artifacts                # Logical name for the artifact set.
      condition: buildSucceeds             # Collect artifacts only on success.
      paths:
        - bin/Release                      # Compiled binaries.
        - reports                          # Test reports.