Pipeline Status:
Skip the debugging cycles. Generate battle-tested CI/CD workflows into your repository with best practices built in. Fully customizable, completely yours.
Read the full documentation at pipecraft.thecraftlab.dev →
The documentation site includes comprehensive guides, real-world examples, configuration references, and troubleshooting help.
Debugging CI/CD pipelines is tedious. You push a change, wait 10 minutes for the pipeline to run, discover a tiny YAML syntax error, fix it, wait another 10 minutes, find another issue. Repeat until you've wasted hours on what should be simple workflow setup.
PipeCraft solves this by providing battle-tested CI/CD templates that you generate into your own repository. Instead of writing GitHub Actions workflows from scratch and debugging them through trial and error, you start with proven patterns that handle common scenarios: domain-based testing for monorepos, semantic versioning, branch promotion flows, and deployment automation.
The generated workflows live in your repository—you own them completely. Customize them as much as you need: add deployment steps, integrate with your tools, modify job configurations. When customizations get complex or you want to start fresh, regenerate from templates. PipeCraft preserves your customizations while updating the core workflow structure.
This approach means you get a fully functional CI/CD pipeline with best practices built in from day one, without the debugging cycles and without the maintenance burden of keeping workflows synchronized across projects.
Get a working pipeline in three commands:
# Initialize PipeCraft in your project
npx pipecraft init
# Edit the generated .pipecraftrc to customize:
# - Branch names (branchFlow, initialBranch, finalBranch)
# - Domain paths and configurations
# - CI provider and merge strategy
# (Supports .pipecraftrc, .json, .yml, .yaml, or .js formats)
# Generate your CI/CD workflows
npx pipecraft generate
# Commit the generated files
git add .github/workflows .github/actions .pipecraftrc
git commit -m "chore: add PipeCraft workflows"
git pushThat's it. You now have a structured CI/CD workflow with change detection. Add your test commands to the generated jobs.
Smart change detection - PipeCraft generates workflows that detect which parts of your monorepo changed. The changes job outputs domain flags (api: true, web: false) that you use in conditional job execution. You write the test commands—PipeCraft handles running them only when needed.
test-api:
needs: changes
if: ${{ needs.changes.outputs.api == 'true' }} # Only runs when API changed
runs-on: ubuntu-latest
steps:
# You add your test commands here:
- run: npm run test:apiSemantic versioning scaffolding - PipeCraft generates a version job that reads conventional commits and calculates version numbers. You get the version as an output to use in your deployment jobs. Tag creation and branch promotion workflows are generated—you add the deployment commands.
Branch promotion structure - PipeCraft generates tag, promote, and release jobs that run after your tests pass. These jobs handle git operations (creating tags, merging branches, creating releases). You add deploy steps to run when code reaches each branch.
Safe workflow regeneration - PipeCraft preserves your custom jobs when you regenerate. The generated workflow has clearly marked sections (<--START CUSTOM JOBS--> / <--END CUSTOM JOBS-->) where your test, deploy, and custom logic lives. Regeneration updates the managed sections (changes detection, version calculation, tag/promote jobs) while keeping your customizations intact.
Change detection works with both strategies - For standard repos, PipeCraft uses path-based detection (you define glob patterns per domain). For Nx monorepos, it automatically uses Nx's dependency graph for precise change detection. Either way, you get domain-based conditional job execution.
You're managing a monorepo with multiple applications or services. PipeCraft gives you the scaffolding for domain-based testing—change detection, conditional job execution, and the workflow structure. You add your actual test commands.
You want a structured trunk-based workflow with version calculation, tagging, and branch promotions. PipeCraft generates the git operations and flow control. You add your deployment steps at each stage.
You need smart change detection that understands your monorepo structure. PipeCraft provides path-based detection (or Nx graph integration) so you can run if: ${{ needs.changes.outputs.api == 'true' }} in your jobs and test only what changed.
No installation required—just run commands directly:
npx pipecraft init
npx pipecraft generateInstall once, use everywhere:
npm install -g pipecraft
pipecraft initAdd to your project's dev dependencies:
npm install --save-dev pipecraftThen add npm scripts to your package.json:
{
"scripts": {
"workflow:init": "pipecraft init",
"workflow:generate": "pipecraft generate",
"workflow:validate": "pipecraft validate"
}
}Create a .pipecraftrc configuration describing your project:
# PipeCraft Configuration
ciProvider: github
mergeStrategy: fast-forward
requireConventionalCommits: true
# Branch flow configuration
initialBranch: develop
finalBranch: main
# Promotion flow: develop → staging → main
branchFlow:
- develop
- staging
- main
# Domain definitions - what parts of your codebase trigger which jobs
domains:
api:
description: 'API services and core logic'
paths:
- apps/api/**
- libs/api-core/**
web:
description: 'Web application and UI'
paths:
- apps/web/**
- libs/ui-components/**Run pipecraft generate and you get workflow scaffolding with:
- Change detection job - Outputs
api: true/falseandweb: true/falsebased on what changed - Conditional test job structure -
test-apiandtest-webjobs withif:conditions, ready for your test commands - Version calculation job - Reads conventional commits, outputs semantic version
- Tag/promote/release jobs - Handle git operations after tests pass
What you add:
- Test commands in each
test-*job (e.g.,npm run test:api) - Deploy commands in custom jobs for each branch (staging deploy, production deploy)
- Remote test commands if you need post-deployment testing
Example of what a generated test job looks like:
test-api:
needs: [changes, version]
if: ${{ needs.changes.outputs.api == 'true' }}
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# <--START CUSTOM TEST STEPS-->
# Add your test commands here:
# - run: npm install
# - run: npm run test:api
# <--END CUSTOM TEST STEPS-->You fill in the custom sections with your actual test logic.
Managed sections (PipeCraft controls these):
changesjob - Detects which domains changed using path patterns or Nx graphversionjob - Calculates semantic version from conventional commitstagjob - Creates git tags for new versionspromotejob - Merges code through your branch flow (develop → staging → main)releasejob - Creates GitHub releases- Domain test job structure with conditional execution
Custom sections (you control these):
- Test commands inside each
test-*job - Deploy jobs for each environment (staging-deploy, production-deploy)
- Remote test jobs for post-deployment testing
- Any additional jobs you need (e.g., security scanning, notifications)
Example workflow structure:
changes: # Managed - detects what changed
version: # Managed - calculates version
test-api: # Managed structure, you add test commands
test-web: # Managed structure, you add test commands
# <--START CUSTOM JOBS-->
deploy-staging: # You create this
remote-test-api: # You create this
deploy-prod: # You create this
# <--END CUSTOM JOBS-->
tag: # Managed - creates git tags
promote: # Managed - merges branches
release: # Managed - creates GitHub releaseRegeneration preserves everything in custom sections. See the Getting Started guide for a complete walkthrough.
Start with the tutorial: The Getting Started guide walks through setting up PipeCraft in a real monorepo with detailed explanations of each step.
Understand your configuration: The Configuration Reference explains every option with examples of when and why to use each setting.
See real-world examples: The Examples page shows configurations for different scenarios—simple web apps, full-stack monorepos, microservices, and enterprise setups.
Learn the commands: The Commands guide covers all CLI commands with practical usage patterns and workflows.
Explore workflow patterns: Start with Trunk Flow to understand how code moves through branches automatically.
If you encounter issues, the Troubleshooting guide covers common problems with detailed solutions.
For questions and discussions, visit GitHub Discussions.
To report bugs or request features, open an issue on GitHub Issues.
We welcome contributions! See the Contributing guide for:
- Development setup instructions
- Code architecture overview
- Testing guidelines
- Pull request process
Quick development setup:
git clone https://github.com/the-craftlab/pipecraft.git
cd pipecraft
npm install
npm testMIT License - see the LICENSE file for details.
Built with ❤️ for trunk-based development teams