Skip to main content

Config File Runner

The Config File Runner executes builds using a declarative YAML configuration file. It enables build logic to be version-controlled, reviewed, and reused consistently across projects and environments, promoting reproducibility and standardization.

When to Use​

Use the Config File Runner when you need to:

  • Store build definitions in source control for versioning, traceability, and auditability.
  • Ensure builds are reproducible and consistent across different environments.
  • Enable teams to collaborate on and review build logic through code reviews.
  • Manage complex build workflows that require structured, declarative configuration.
  • Standardize build behavior across projects and teams.

Parameters​

ParameterDescription
Step NameOptional step name. Defaults to the runner name if not specified.
Working DirectoryDirectory where the build process runs.
Config FilePath to the configuration file.

Typical Use Cases​

Common scenarios for using the Config File Runner include:

  • Defining build workflows in repository-managed YAML files.
  • Orchestrating multi-step builds with clearly defined dependencies.
  • Sharing standardized build templates across teams and projects.
  • Managing build logic using an infrastructure-as-code–style approach.
  • Maintaining consistent build behavior across environments through version-controlled configuration.

Example​

This example demonstrates how to trigger a build using the Config File Runner with a YAML configuration file.

Scenario
Execute a multi-step build defined in a repository-managed YAML file.

Configuration settings:

  • Step Name: Run Build Configuration
  • Working Directory: /workspace/project
  • Config File: build-config.yaml
note

For detailed guidance on creating and managing YAML build configurations, see YAML Configuration ReferenceBuildNinja allows you to use Custom YAML Configuration Files with the Config File runner, in addition to exported configurations..

Limitations​

  • Requires familiarity with YAML syntax and schema.
  • Debugging can be slower compared to inline commands.
  • Adds overhead for small or ad-hoc tasks.
  • Validation errors may cause early build failures.
  • Version control systems (VCS) must be configured manually in the build configuration’s VCS Settings.

Best Practices​

  • Keep YAML files modular and easy to read.
  • Store configuration files alongside application source code.
  • Use comments and consistent naming conventions.
  • Version-control all build configuration files to track changes and enable collaboration.