Skip to content
Pilum

Introduction

Pilum is a cloud-agnostic build and deployment CLI. Define your service once, deploy to any cloud provider.

Terminal window
pilum deploy --tag=v1.0.0

Pilum handles the build → push → deploy pipeline while your infrastructure-as-code (Terraform, Pulumi) defines the actual resources.

Why Pilum?

ChallengePilum Solution
Provider lock-inSwap between GCP ↔ AWS ↔ Azure by changing one line
Slow sequential deploysParallel execution with worker queues
Complex CI/CD scriptsDeclarative YAML recipes
Per-provider validation codeRecipe-driven validation — no Go code per provider

The Cooking Metaphor

Pilum uses a cooking metaphor to keep things intuitive:

  • Recipes (recepies/) — Deployment workflows with required fields and ordered steps
  • Ingredients (ingredients/) — Cloud-specific command generators
  • Services — Your applications, discovered via pilum.yaml files

Features

  • Recipe-driven deployments — Define reusable deployment workflows in YAML
  • Recipe-driven validation — Each recipe declares required fields, no Go code per provider
  • Multi-cloud support — GCP Cloud Run, GCP Cloud Run Jobs, AWS Lambda, Azure Container Apps, Cloudflare Pages, npm, Homebrew, and more
  • Parallel execution — Deploy multiple services concurrently with step barriers
  • Dependency ordering — Wave-based deployment respects depends_on for deploy/execute steps
  • Deployment locks — Prevent concurrent deploys with automatic stale lock cleanup
  • GitHub commit status — Post pending/success/failure status to commits from CI
  • Step filtering — Run only build steps, only deploy steps, or custom tag combinations
  • Environment overrides — Per-environment config (staging, prod) via environments block
  • Git-aware filtering — Deploy only services with changes since base branch
  • Dry-run mode — Preview commands before executing
  • JSON output — Machine-readable output for scripting and AI agents
  • Editor support — JSON Schema for autocompletion and validation in VS Code, JetBrains, etc.

How It Works

  1. Discovery — Pilum finds all pilum.yaml files in your project (respects .gitignore and .pilumignore)
  2. Validation — Each service is validated against its recipe’s required fields
  3. Matching — Services are matched to recipes based on provider field
  4. Locking — A deployment lock prevents concurrent runs
  5. Orchestration — Build/push steps run in flat parallel; deploy steps respect depends_on ordering via waves
  6. Recording — Results are saved to .pilum/history.jsonl
Step 1: build
  ├── database        ✓ (0.8s)
  ├── api             ✓ (1.2s)
  └── worker          ✓ (0.9s)


Step 2: push
  ├── database        ✓ (2.1s)
  ├── api             ✓ (1.8s)
  └── worker          ✓ (2.0s)


Step 3: deploy
  Wave 1/2:
  ├── database        ✓ (3.2s)
  Wave 2/2:
  ├── api             ✓ (2.9s)
  └── worker          ✓ (3.1s)

Build and push steps always run in flat parallel for speed. Deploy steps respect depends_on ordering — services are grouped into waves by dependency depth, with each wave executing in parallel.

Next Steps