DOCSEARCHbyAlgolia
Submit Docs

PipeCraft Documentation

website·Indexed 29 days ago

https://pipecraft.thecraftlab.dev

PipeCraft generates battle-tested CI/CD workflows directly into GitHub repositories from a simple configuration file. It implements a promote-on-merge trunk-based workflow by default and integrates with release-it for semantic versioning and conventional commits. The tool provides template-based generation for GitHub Actions, including domain-based testing for monorepos and automated branch protection utilities.

Tokens
40.6K
Snippets
273
Records
324
Agent score
50%

What's inside PipeCraft

  1. Overview of PipeCraft CI/CD Generation

    PipeCraft is a CLI tool that generates GitHub Actions CI/CD workflows based on a project structure defined in a .pipecraftrc.json configuration file. Instead of writing YAML from scratch, developers use PipeCraft to scaffold production-ready workflows that include domain-based change detection, semantic versioning automation, branch promotion flows (e.g., develop → staging → main), and GitHub releases. The generated files are stored in the .github/ directory and are fully owned by the user.

  2. Use PipeCraft with Monorepos and Nx

    PipeCraft is compatible with any monorepo (including Nx) using path-based change detection. Instead of using tool-specific logic like nx affected, you define one domain per project in .pipecraftrc.json with paths matching that project's directory. Only domains with changed files will be executed.

  3. Automate semantic versioning with the Calculate Version Action Template

    The Calculate Version Action Template generates a composite action located at actions/calculate-version/action.yml. This action automates semantic versioning in CI/CD pipelines by analyzing conventional commit messages since the last tag and using release-it to determine the appropriate version bump: feat triggers a minor bump, fix triggers a patch bump, and BREAKING changes trigger a major bump. The calculated version is then output for use in subsequent workflow jobs.

  4. Use VersionManager for semantic versioning and release automation

    The VersionManager class handles semantic versioning operations, including automatic version calculation based on commit history, generation of configuration files for release-it, commitlint, and husky, and validation of conventional commits. It is designed to integrate with trunk-based workflows to automate version bumps during pipeline promotion.
    const versionManager = new VersionManager(config)

// Setup version management (creates config files)
versionManager.setupVersionManagement()

// Get current version from git tags
const currentVersion = versionManager.getCurrentVersion()

// Calculate next version based on commits
const { version, type } = versionManager.calculateNextVersion()
console.log(`Next version: ${version} (${type} bump)`)

  5. SetupSummary Interface Reference

    The SetupSummary interface provides a high-level overview of the entire setup process, including overall status and categorized lists of items and errors.
    interface SetupSummary {
  repository: string;
  overallStatus: 'error' | 'ready' | 'needs-setup' | 'partial';
  permissions: StatusItem[];
  settings: StatusItem[];
  autoPromote: StatusItem[];
  warnings: string[];
  errors: string[];
  nextSteps: string[];
}

  6. Debug PipeCraft using verbose output and logs

    To get more detailed information about configuration loading and pre-flight checks, use the --verbose flag during generation. You can also use the GitHub CLI to inspect workflow runs.
    # Enable verbose output
pipecraft generate --verbose

# List recent GitHub Action runs
gh run list

# View logs for a specific run
gh run view <run-id> --log

  7. Understand the PipeCraft Auto-Merge Two-Layer System

    Auto-merge in GitHub requires two distinct layers of configuration to function within PipeCraft workflows:

    1. Repository-Level Setting (allow_auto_merge): This must be enabled at the repository level for the auto-merge feature to be available. PipeCraft configures this based on the .pipecraftrc file.
    2. Per-PR Activation: Each Pull Request must be explicitly enabled for auto-merge. PipeCraft workflows automatically trigger this activation for branches defined in the autoPromote section of .pipecraftrc.
    {
  "branchFlow": ["develop", "staging", "main"],
  "autoPromote": {
    "staging": true, // Auto-merge PRs to staging
    "main": true // Auto-merge PRs to main
  }
}

  8. Understand the GitFlow branching model

    GitFlow is a branching model designed for projects with scheduled, versioned releases (e.g., desktop or mobile apps). It utilizes multiple long-lived branches to separate development stages: main (production), develop (integration), release (preparation), and hotfix (urgent production fixes). Feature branches are merged into develop, which then feeds into release branches before finally merging into main.

  9. Planned Custom Flow support in PipeCraft

    PipeCraft plans to introduce Custom Flow support in a future release. This feature will allow users to define their own branching strategies, promotion rules, and deployment targets beyond the predefined patterns (such as trunk, GitHub Flow, and GitFlow). This is intended for teams with unique pipeline needs, such as dev → qa → uat → prod sequences or parallel staging environments.

  10. Generate GitHub Actions CI/CD pipelines using the Workflows Template Generator

    The Workflows Template Generator is the main orchestrator for creating complete GitHub Actions CI/CD pipelines. It generates a main pipeline workflow (with path-based change detection), several reusable composite actions (for tag creation, versioning, branch management, etc.), and a .release-it.cjs configuration file. The generator supports both initial generation and incremental updates, preserving user modifications to existing workflows through intelligent merging.

  11. Generate a reusable GitHub action for domain change detection

    The Detect Changes Action Template generates a reusable GitHub composite action located at actions/detect-changes/action.yml. This action uses dorny/paths-filter to detect which domains have changed based on file glob patterns.

    Key Design Principle: The action is configuration-driven. Domain definitions are passed as input at runtime rather than being hardcoded into the action, allowing the same generated action to be used across different projects without needing to be regenerated.

  12. Understand the PipeCraft generated workflow structure

    PipeCraft generates a GitHub Actions workflow that implements a multi-phase CI/CD pipeline. The workflow consists of:

    1. Change Detection: A job that analyzes modified files to determine which domains (e.g., api, web) are affected. It outputs boolean values used by subsequent jobs to avoid unnecessary runs.
    2. Domain-Specific Testing: Jobs that execute only if their corresponding domain was modified (e.g., test-api runs only if needs.changes.outputs.api == 'true').
    3. Versioning: Automatically calculates the next semantic version based on commit messages.
    4. Promotion: Automatically triggers the workflow on the next branch (e.g., staging → main) after tests pass for version-bumping commits.
    jobs:
  changes:
    # Managed by Pipecraft - detects affected domains
    outputs:
      api: ${{ steps.detect.outputs.api }}
      web: ${{ steps.detect.outputs.web }}

  test-api:
    needs: changes
    if: ${{ needs.changes.outputs.api == 'true' }}
    # User-customizable test logic