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:27

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',
  testable: true,
  deployable: true
}

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:38

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

paths

paths: string[];

Defined in: types/index.ts:32

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 provide more flexibility than the boolean flags (testable, deployable, etc).

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'],
  autoMerge: { staging: true },
  semver: {
    bumpRules: { feat: 'minor', fix: 'patch', breaking: 'major' }
  },
  actions: {
    onDevelopMerge: ['runTests'],
    onStagingMerge: ['runTests', 'calculateVersion']
  },
  domains: {
    api: { paths: ['packages/api/**'], description: 'API', testable: true }
  }
}

Properties

actionSourceMode?

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

Defined in: types/index.ts:246

How workflows should reference PipeCraft actions.

'local': Actions copied to ./.github/actions/ (default, full control)
'remote': Reference published marketplace actions (e.g., pipecraft-lab/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: pipecraft-lab/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:255

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:162

Auto-merge configuration for branch promotions.

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

When enabled, PRs are automatically merged after checks pass.

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:208

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:174

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

nx?

optional nx: object;

Defined in: types/index.ts:271

Nx monorepo integration configuration. When enabled, PipeCraft generates workflows that leverage Nx's dependency graph and affected detection for intelligent change-based testing.

baseRef?

optional baseRef: string;

Base git reference for affected detection. Used in nx affected --base=<baseRef>.

Default

'origin/main'

enableCache?

optional enableCache: boolean;

Whether to include Nx cache management in workflows. Speeds up subsequent runs by caching build outputs.

Default

true

enabled

enabled: boolean;

Whether Nx integration is enabled for this project. Auto-detected if nx.json exists in project root.

tasks

tasks: string[];

Ordered list of Nx tasks to run sequentially. Tasks are executed using nx affected --target=<task>.

Example

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

Example

nx: {
  enabled: true,
  tasks: ['lint', 'test', 'build', 'integration-test'],
  baseRef: 'origin/main'
}

packageManager?

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

Defined in: types/index.ts:220

Package manager used for dependency installation. Auto-detected during init based on lockfile presence.

'npm': Uses npm (with package-lock.json)
'yarn': Uses yarn (with yarn.lock)
'pnpm': Uses pnpm (with pnpm-lock.yaml)

Default

'npm'

rebuild?

optional rebuild: object;

Defined in: types/index.ts:307

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/

semver

semver: object;

Defined in: types/index.ts:196

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:350

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

bumpRules: Record<string, string>;

Mapping of commit types to version bump levels.

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.

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?​

Default​

branchFlow​

Example​

ciProvider​

domains​

finalBranch​

initialBranch​

mergeMethod?​

Default​

mergeStrategy​

nx?​

baseRef?​

Default​

enableCache?​

Default​

enabled​

tasks​

Example​

Example​

packageManager?​

Default​

rebuild?​

cacheFile​

enabled​

forceRegenerate​

hashAlgorithm​

ignorePatterns​

skipIfUnchanged​

watchMode​

requireConventionalCommits​

See​

semver​

bumpRules​

Example​

versioning?​

autoPush​

autoTag​

bumpRules​

changelog​

conventionalCommits​

enabled​

releaseItConfig​

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?

Default

branchFlow

Example

ciProvider

domains

finalBranch

initialBranch

mergeMethod?

Default

mergeStrategy

nx?

baseRef?

Default

enableCache?

Default

enabled

tasks

Example

Example

packageManager?

Default

rebuild?

cacheFile

enabled

forceRegenerate

hashAlgorithm

ignorePatterns

skipIfUnchanged

watchMode

requireConventionalCommits

See

semver

bumpRules

Example

versioning?

autoPush

autoTag

bumpRules

changelog

conventionalCommits

enabled

releaseItConfig