Skip to main content

utils/config

Configuration Loading and Validation Utilities

This module provides functions to load and validate PipeCraft configuration files. It uses cosmiconfig to search for configuration in multiple locations:

  • .pipecraftrc (YAML or JSON, recommended)
  • .pipecraftrc.json
  • .pipecraftrc.yaml
  • .pipecraftrc.yml
  • .pipecraftrc.js
  • pipecraft.config.js
  • package.json (pipecraft key)

The configuration is validated to ensure all required fields are present and have valid values before being used to generate workflows.

Variables​

RESERVED_JOB_NAMES​

const RESERVED_JOB_NAMES: readonly ['version', 'changes', 'gate', 'tag', 'promote', 'release']

Defined in: utils/config.ts:33

Reserved job names that cannot be used as domain names. These are managed by Pipecraft and would conflict with generated workflow jobs.

Functions​

getConfigWarnings()​

function getConfigWarnings(config): string[]

Defined in: utils/config.ts:263

Collect non-fatal warnings for config fields that are declared/documented but have no effect, so the dead surface is visible instead of silently ignored.

  • mergeMethod and mergeStrategy: 'merge' are consumed nowhere — promotions always fast-forward (the promote action hardcodes --ff-only).
  • autoMerge is a deprecated alias for autoPromote.

Parameters​

config​

any

A config object (already structurally validated)

Returns​

string[]

Human-readable warning strings (empty when the config is clean)

loadConfig()​

function loadConfig(configPath?): any

Defined in: utils/config.ts:69

Load PipeCraft configuration from filesystem.

Uses cosmiconfig to search for configuration files in standard locations. If no path is provided, searches the current directory and ancestors for configuration files in this order:

  1. .pipecraftrc (YAML or JSON, recommended)
  2. .pipecraftrc.json
  3. .pipecraftrc.yaml
  4. .pipecraftrc.yml
  5. .pipecraftrc.js
  6. pipecraft.config.js
  7. package.json (pipecraft key)

Parameters​

configPath?​

string

Optional explicit path to configuration file

Returns​

any

Parsed configuration object

Throws​

If no configuration file is found

Example​

// Search for config in current directory and ancestors
const config = loadConfig()

// Load from explicit path
const config = loadConfig('./my-config.json')

validateConfig()​

function validateConfig(config): boolean

Defined in: utils/config.ts:119

Validate PipeCraft configuration structure and values.

Performs comprehensive validation including:

  • Presence of all required fields
  • Valid enum values (ciProvider, mergeStrategy)
  • Branch flow structure (minimum 2 branches)
  • Domain configuration (paths, testable, deployable)

Also sets default values for optional domain properties:

  • testable defaults to true
  • deployable defaults to true

Parameters​

config​

any

Configuration object to validate (untyped to allow validation)

Returns​

boolean

true if validation passes

Throws​

If validation fails with detailed error message

Example​

const config = loadConfig()
validateConfig(config) // Throws if invalid
// Safe to use config as PipecraftConfig after this point