PipeCraft Example: Minimal

The simplest possible PipeCraft configuration - perfect for getting started in under 5 minutes.

Purpose

This example demonstrates:

• ✅ Minimal configuration - Just one domain, simplest setup
• ✅ 2-branch workflow - develop → main (no staging)
• ✅ Bootstrap behavior - No initial tag; PipeCraft creates v0.1.0 automatically
• ✅ Auto-merge enabled - Automatic promotion from develop to main
• ✅ Quickstart template - Clone and start using immediately

Repository Structure

pipecraft-example-minimal/
├── .github/workflows/
│   └── pipeline.yml          # Generated by PipeCraft
├── src/
│   ├── index.js              # Main application
│   └── utils.js              # Utility functions
├── test/
│   └── utils.test.js         # Simple tests
├── .gitignore
├── .pipecraftrc.json         # PipeCraft configuration
├── package.json
├── build.js                  # Simple build script
├── test-runner.js            # Test runner
└── README.md

Configuration

{
  "ciProvider": "github",
  "mergeStrategy": "fast-forward",
  "requireConventionalCommits": true,
  "initialBranch": "develop",
  "finalBranch": "main",
  "branchFlow": ["develop", "main"],
  "autoMerge": {
    "main": true
  },
  "domains": {
    "app": {
      "paths": ["src/**"],
      "description": "Application code"
    }
  }
}

Workflow

1. Development

git checkout develop
git pull origin develop

# Make changes
echo "export function subtract(a, b) { return a - b; }" >> src/utils.js

# Commit using conventional commits
git add .
git commit -m "feat: add subtract function"
git push origin develop

2. Automatic Pipeline

When you push to develop:

1. Tests Run - Validates your changes
2. Version Calculated - Based on commit message (feat: → minor bump)
3. Auto-Promote - Automatically fast-forwards to main
4. Tag Created - New version tag (e.g., v0.2.0)

3. Check Results

# View workflow run
gh run list

# Check new version
git fetch --tags
git tag --sort=-creatordate | head -1

# Verify main is updated
git checkout main
git pull origin main

Branch Flow

develop ──────────────► main
  │                       │
  │  feat: add feature   │
  ├──────────────────────┤
  │    auto-merge        │
  └──────────────────────► v0.2.0

Bootstrap Behavior

This repository intentionally has NO initial tag to demonstrate PipeCraft's bootstrap behavior:

1. First commit without a tag → PipeCraft does nothing (no version to bump)
2. First feat: or fix: commit → PipeCraft creates v0.1.0
3. Subsequent commits → Normal version bumping (v0.1.1, v0.2.0, etc.)

Getting Started

Prerequisites

• Node.js 18+ installed
• Git configured
• GitHub account

Clone and Setup

# Clone this repository
git clone https://github.com/jamesvillarrubia/pipecraft-example-minimal.git
cd pipecraft-example-minimal

# Install PipeCraft (if testing locally)
npm install -D @jamesvillarrubia/pipecraft

# Test locally
npm test
npm run build
npm start

Use as Template

1. Click "Use this template" on GitHub
2. Clone your new repo
3. Update .pipecraftrc.json if needed
4. Regenerate workflows:

   npx pipecraft generate

5. Push to develop and watch it work!

Testing Locally

# Run tests
npm test

# Run build
npm run build

# Run application
npm start

Commit Message Format

PipeCraft requires conventional commits:

Version Bumps

• feat: add new feature → Minor version bump (0.1.0 → 0.2.0)
• fix: resolve bug → Patch version bump (0.1.0 → 0.1.1)
• feat!: breaking change → Major version bump (0.1.0 → 1.0.0)

No Version Bump

• chore: update docs
• test: add tests
• refactor: clean code
• docs: update readme

Customization

Add More Domains

Edit .pipecraftrc.json:

{
  "domains": {
    "app": {
      "paths": ["src/**"]
    },
    "api": {
      "paths": ["api/**"]
    }
  }
}

Then regenerate:

npx pipecraft generate

Add Staging Branch

Edit .pipecraftrc.json:

{
  "branchFlow": ["develop", "staging", "main"],
  "autoMerge": {
    "staging": true,
    "main": true
  }
}

Troubleshooting

Workflow Not Running

1. Check GitHub Actions is enabled: Settings → Actions → General
2. Verify workflow permissions: Settings → Actions → Workflow permissions → "Read and write"
3. Ensure you're pushing to develop branch

Version Not Creating

1. Ensure commit follows conventional format
2. Check if initial tag exists: git tag -l
3. For net-new repos, first feat: or fix: commit creates v0.1.0

Tests Failing

# Run tests locally first
npm test

# Check test output in GitHub Actions
gh run view --log

Related Examples

• pipecraft-example-basic - Multi-domain with 3-branch flow
• pipecraft-example-nx - Nx monorepo with mixed detection
• pipecraft-example-gated - Enterprise gated workflow

Learn More

• PipeCraft Documentation
• GitHub Actions Documentation
• Conventional Commits
• Trunk-Based Development

License

MIT © PipeCraft Team