types

PipeCraft Type Definitions

This module contains the core TypeScript interfaces and types used throughout PipeCraft. These types define the configuration schema, context objects, and domain specifications for generating CI/CD pipelines with trunk-based development workflows.

Interfaces

DomainConfig

Defined in: types/index.ts:26

Configuration for a single domain (monorepo workspace) in a PipeCraft project.

Domains enable path-based change detection in monorepo architectures, allowing different parts of the codebase to be tested and deployed independently.

Example

const apiDomain: DomainConfig = {
  paths: ['packages/api/**', 'libs/shared/**'],
  description: 'Backend API services',
  prefixes: ['test', 'deploy']
}

Properties

deployable?

optional deployable: boolean;

Defined in: types/index.ts:71

Whether this domain should be deployed. If true, generates deployment jobs for this domain.

Default

false

Deprecated

Use prefixes: ['deploy'] instead for more flexibility

description

description: string

Defined in: types/index.ts:37

Human-readable description of the domain's purpose. Used in workflow comments and documentation.

paths

paths: string[];

Defined in: types/index.ts:31

Glob patterns matching files in this domain. Changes to these paths will trigger domain-specific jobs.

prefixes?

optional prefixes: string[];

Defined in: types/index.ts:55

Job prefixes to generate for this domain. Each prefix generates a customizable placeholder job named {prefix}-{domain}.

For example, with domain 'core' and prefixes: ['test', 'deploy', 'lint']:

test-core (runs when core/ changes)
deploy-core (runs when core/ changes)
lint-core (runs when core/ changes)

These are placeholder jobs where you add your own logic in the custom jobs section. Prefixes are the mechanism job generation reads. The deprecated boolean flags are translated into this array during config validation.

Examples

;['test', 'deploy', 'remote-test']

;['lint', 'build', 'test', 'deploy', 'e2e']

remoteTestable?

optional remoteTestable: boolean;

Defined in: types/index.ts:79

Whether this domain should be tested remotely after deployment. If true, generates remote test jobs for this domain.

Default

false

Deprecated

Use prefixes: ['remote-test'] instead for more flexibility

testable?

optional testable: boolean;

Defined in: types/index.ts:63

Whether this domain has tests that should be run. If true, generates test jobs for this domain.

Default

false

Deprecated

Use prefixes: ['test'] instead for more flexibility

PipecraftConfig

Defined in: types/index.ts:113

Complete PipeCraft configuration schema.

This is the main configuration interface loaded from .pipecraftrc (YAML or JSON), .pipecraftrc.json (legacy), or the pipecraft key in package.json. It defines the entire CI/CD pipeline behavior including branch flow, merge strategies, domain configuration, versioning, and automated actions.

Example

const config: PipecraftConfig = {
  ciProvider: 'github',
  mergeStrategy: 'fast-forward',
  requireConventionalCommits: true,
  initialBranch: 'develop',
  finalBranch: 'main',
  branchFlow: ['develop', 'staging', 'main'],
  autoPromote: { staging: true },
  semver: {
    bumpRules: { feat: 'minor', fix: 'patch', breaking: 'major' }
  },
  actions: {
    onDevelopMerge: ['runTests'],
    onStagingMerge: ['runTests', 'calculateVersion']
  },
  domains: {
    api: { paths: ['packages/api/**'], description: 'API', prefixes: ['test'] }
  }
}

Properties

actionSourceMode?

optional actionSourceMode: "local" | "remote" | "source";

Defined in: types/index.ts:302

How workflows should reference PipeCraft actions.

'local': Actions copied to ./.github/actions/ (default, full control)
'remote': Reference published marketplace actions (e.g., the-craftlab/pipecraft/actions/detect-changes@v1)
'source': Use ./actions/ from repo root (internal use only, for PipeCraft's own CI)

Default

'local'

Example

// User repos (local mode)
actionSourceMode: 'local'
// Generates: uses: ./.github/actions/detect-changes

// User repos (remote mode)
actionSourceMode: 'remote'
actionVersion: 'v1.2.3'
// Generates: uses: the-craftlab/pipecraft/actions/detect-changes@v1.2.3

// PipeCraft repo only (source mode)
actionSourceMode: 'source'
// Generates: uses: ./actions/detect-changes

actionVersion?

optional actionVersion: string;

Defined in: types/index.ts:311

Version/tag to use when actionSourceMode is 'remote'. Pins workflows to a specific marketplace action version.

Example

'v1.2.3', 'v1', 'main'

Default

'v1'

autoMerge?

optional autoMerge: boolean | Record<string, boolean>;

Defined in: types/index.ts:207

Auto-merge configuration.

Deprecated

Use autoPromote instead. This is a backwards-compatible alias and has no independent effect.

autoPromote?

optional autoPromote: boolean | Record<string, boolean>;

Defined in: types/index.ts:170

Auto-promote configuration for branch promotions.

boolean: Enable/disable auto-promotion for all branches
Record: Per-branch auto-promote settings (e.g., { staging: true, main: false })

This controls how a promotion PR is merged, not whether one is opened. PipeCraft opens the promotion PR either way:

true — the PR is opened and merged automatically once checks pass.
false — the PR is opened and left for a human to merge.

There is no value here that stops promotion PRs from being created. To stop promoting to a branch at all, remove it from branchFlow.

Default

false

branchFlow

branchFlow: string[];

Defined in: types/index.ts:152

Ordered list of branches in the promotion flow from initial to final. Must start with initialBranch and end with finalBranch.

Example

;['develop', 'staging', 'main']

ciProvider

ciProvider: 'github' | 'gitlab'

Defined in: types/index.ts:118

CI/CD provider platform. Currently 'github' is fully supported, 'gitlab' support is planned.

domains

domains: Record<string, DomainConfig>

Defined in: types/index.ts:236

Domain definitions for monorepo path-based change detection. Each domain represents a logical part of the codebase with its own test and deployment requirements.

finalBranch

finalBranch: string

Defined in: types/index.ts:144

The final production branch (typically 'main' or 'master'). This is the last branch in the promotion flow.

initialBranch

initialBranch: string

Defined in: types/index.ts:138

The first branch in the promotion flow (typically 'develop' or 'dev'). All feature branches merge into this branch.

mergeMethod?

optional mergeMethod:
  | "merge"
  | "auto"
  | "squash"
  | "rebase"
| Record<string, "merge" | "auto" | "squash" | "rebase">;

Defined in: types/index.ts:194

Git merge method for auto-merge operations.

'auto': Use fast-forward when possible, merge otherwise
'merge': Always create merge commit
'squash': Squash all commits into one
'rebase': Rebase and fast-forward

Can be set globally or per-branch.

Default

'auto'

mergeStrategy

mergeStrategy: 'fast-forward' | 'merge'

Defined in: types/index.ts:125

Git merge strategy for branch promotions.

'fast-forward': Requires linear history, fails if branches diverged
'merge': Creates merge commits

packageManager?

optional packageManager: "npm" | "yarn" | "pnpm";

Defined in: types/index.ts:246

Package manager used for dependency installation.

Deprecated

This field is no longer used by PipeCraft workflows. It was originally intended for JavaScript/Node.js projects but PipeCraft now supports language-agnostic workflows. Existing configs with this field will continue to work, but it has no effect.

promoteDirectPushes?

optional promoteDirectPushes: boolean;

Defined in: types/index.ts:182

Let any push to the initial branch tag and promote, not only commits GitHub authored.

By default tag and promote require committer.email == 'noreply@github.com' (or workflow_dispatch), so a hand-pushed commit does not release. true removes that clause from both jobs; every other condition stays. It also removes the guard against a hotfix typed on the wrong branch.

Default

false

rebuild?

optional rebuild: object;

Defined in: types/index.ts:317

Idempotency and rebuild configuration. Controls when workflows should be regenerated based on config/template changes.

cacheFile

cacheFile: string

Path to cache file storing previous config hash.

enabled

enabled: boolean

Whether idempotency checking is enabled. If true, workflows are only regenerated when config or templates change.

forceRegenerate

forceRegenerate: boolean

Force regeneration even if hash matches. Useful for debugging or manual overrides.

hashAlgorithm

hashAlgorithm: 'md5' | 'sha1' | 'sha256'

Hashing algorithm for detecting config changes.

ignorePatterns

ignorePatterns: string[];

Patterns to ignore when calculating config hash.

skipIfUnchanged

skipIfUnchanged: boolean

Skip regeneration if config hash hasn't changed.

watchMode

watchMode: boolean

Enable watch mode for automatic regeneration on config changes.

requireConventionalCommits

requireConventionalCommits: boolean

Defined in: types/index.ts:132

Whether to enforce conventional commit message format. If true, commit messages must follow the Conventional Commits specification.

See

https://www.conventionalcommits.org/

runtime?

optional runtime: object;

Defined in: types/index.ts:262

Runtime tool versions for generated CI/CD workflows.

Controls the NODE_VERSION / PNPM_VERSION workflow env vars (and the version job's node-version) without hand-editing generated files. When a value is set here it is authoritative — regeneration overwrites the env var with the configured value; when unset, the existing value is preserved and falls back to the defaults.

nodeVersion?

optional nodeVersion: string;

Node.js version for workflows. Accepts a major (e.g. '22') or an exact version (e.g. '22.18.0').

Default

'22'

pnpmVersion?

optional pnpmVersion: string;

pnpm version for workflows (used when the project installs with pnpm). Accepts a major (e.g. '10') or an exact version (e.g. '10.6.2').

Default

'10.6.2'

Example

runtime: { nodeVersion: '22', pnpmVersion: '10' }

semver

semver: object

Defined in: types/index.ts:224

Semantic versioning configuration. Maps conventional commit types to version bump levels.

bumpRules

bumpRules: Record<string, string>

Mapping of commit types to semver bump levels (major, minor, patch).

Example

semver: {
  bumpRules: {
    feat: 'minor',      // New features bump minor version
    fix: 'patch',        // Bug fixes bump patch version
    breaking: 'major'    // Breaking changes bump major version
  }
}

versioning?

optional versioning: object;

Defined in: types/index.ts:360

Version management configuration using release-it. Enables automatic version bumping, tagging, and changelog generation.

autoPush

autoPush: boolean

Automatically push tags to remote after creation.

autoTag

autoTag: boolean

Automatically create git tags for new versions.

bumpRules?

optional bumpRules: Record<string, string>;

Mapping of commit types to version bump levels.

Deprecated

Use semver.bumpRules instead. This field is ignored if semver.bumpRules is present.

changelog

changelog: boolean

Generate CHANGELOG.md from conventional commits.

conventionalCommits

conventionalCommits: boolean

Use conventional commits for version calculation.

enabled

enabled: boolean

Whether version management is enabled.

releaseItConfig

releaseItConfig: string

Path to release-it configuration file.

Variables

KNOWN_CONFIG_KEYS

const KNOWN_CONFIG_KEYS: readonly [
  'ciProvider',
  'mergeStrategy',
  'requireConventionalCommits',
  'initialBranch',
  'finalBranch',
  'branchFlow',
  'autoPromote',
  'promoteDirectPushes',
  'mergeMethod',
  'autoMerge',
  'semver',
  'domains',
  'packageManager',
  'runtime',
  'actionSourceMode',
  'actionVersion',
  'rebuild',
  'versioning'
]

Defined in: types/index.ts:476

Every recognized top-level config key.

This is the runtime allowlist counterpart to PipecraftConfig. It is kept in lockstep with the interface by the compile-time assertions below (a missing or extra key fails tsc) and with .pipecraft-schema.json by tests/unit/schema-types-consistency.test.ts. When you add a config field, add it in all three places.

KNOWN_DOMAIN_KEYS

const KNOWN_DOMAIN_KEYS: readonly [
  'paths',
  'description',
  'prefixes',
  'testable',
  'deployable',
  'remoteTestable'
]

Defined in: types/index.ts:501

Every recognized key inside a single domain entry. Kept in lockstep with DomainConfig and the schema's definitions.DomainConfig.

Interfaces​

DomainConfig​

Example​

Properties​

deployable?​

Default​

Deprecated​

description​

paths​

prefixes?​

Examples​

remoteTestable?​

Default​

Deprecated​

testable?​

Default​

Deprecated​

PipecraftConfig​

Example​

Properties​

actionSourceMode?​

Default​

Example​

actionVersion?​

Example​

Default​

autoMerge?​

Deprecated​

autoPromote?​

Default​

branchFlow​

Example​

ciProvider​

domains​

finalBranch​

initialBranch​

mergeMethod?​

Default​

mergeStrategy​

packageManager?​

Deprecated​

promoteDirectPushes?​

Default​

rebuild?​

cacheFile​

enabled​

forceRegenerate​

hashAlgorithm​

ignorePatterns​

skipIfUnchanged​

watchMode​

requireConventionalCommits​

See​

runtime?​

nodeVersion?​

Default​

pnpmVersion?​

Default​

Example​

semver​

bumpRules​

Example​

versioning?​

autoPush​

autoTag​

bumpRules?​

Deprecated​

changelog​

conventionalCommits​

enabled​

releaseItConfig​

Variables​

KNOWN_CONFIG_KEYS​

KNOWN_DOMAIN_KEYS​

Interfaces

DomainConfig

Example

Properties

deployable?

Default

Deprecated

description

paths

prefixes?

Examples

remoteTestable?

Default

Deprecated

testable?

Default

Deprecated

PipecraftConfig

Example

Properties

actionSourceMode?

Default

Example

actionVersion?

Example

Default

autoMerge?

Deprecated

autoPromote?

Default

branchFlow

Example

ciProvider

domains

finalBranch

initialBranch

mergeMethod?

Default

mergeStrategy

packageManager?

Deprecated

promoteDirectPushes?

Default

rebuild?

cacheFile

enabled

forceRegenerate

hashAlgorithm

ignorePatterns

skipIfUnchanged

watchMode

requireConventionalCommits

See

runtime?

nodeVersion?

Default

pnpmVersion?

Default

Example

semver

bumpRules

Example

versioning?

autoPush

autoTag

bumpRules?

Deprecated

changelog

conventionalCommits

enabled

releaseItConfig

Variables

KNOWN_CONFIG_KEYS

KNOWN_DOMAIN_KEYS