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

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.

VCS Settings and Authentication

Version control settings are defined directly within the YAML configuration file and control how BuildNinja connects to the source repository during execution.

Common Fields in VCS Steps

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

Field	Description
name	A human-readable name for the VCS step, shown in logs and the BuildNinja UI.
key	Specifies the VCS type. For Git repositories, this value is vcs_git.
disabled	Enables or disables the step. Set to true to skip the step during execution.
args	Contains non-sensitive VCS configuration values such as repository URL and branch.
argsProtected	Stores sensitive values such as access tokens securely.

Authentication Options

Authentication is configured using the authType field, which supports the following values:

• anonymous: Access the repository without authentication.
• pat: Authenticate using a Personal Access Token (PAT).

Sensitive values such as passwords and access tokens must be specified under argsProtected.

Refer to the following example for VCS configuration with anonymous access:

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/project.git  # Repository URL.
      branch: main                                 # Branch to check out.
      authType: anonymous                          # Access repository without authentication.

Refer to the following example for VCS configuration with PAT:

vcs-steps:
  - name: Checkout Repository              # Display name for the VCS step.
    key: vcs_git                           # Specifies Git as the VCS type.
    disabled: false                        # Enables the checkout step.
    args:
      url: https://github.com/example/project.git  # Repository URL.
      branch: main                                 # Branch to check out.
      authType: pat                                # Use Personal Access Token authentication.
      username: git-user                           # Username associated with the PAT.
    argsProtected:
      token: your-personal-access-token            # Securely stored access token.

note

• Ensure the repository URL and branch are accessible to the configured agent.
• Authentication details must match the access requirements of the repository.
• The VCS step must be enabled (disabled: false) for checkout to occur.

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.

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.

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.