A declarative, parallel-by-default pipeline orchestrator powered by HCL.
piperun lets you define build, test, and deploy pipelines in .hcl files using a familiar, Terraform-inspired syntax. Stages run concurrently by default; add depends_on when ordering matters.
$ piperun
0ms β’ piperun (version=2, lifecycle=default)
0ms β’ [stage.lint] [+] lint
0ms β’ [stage.test] [+] test
0ms β’ [stage.lint] Running lint for myapp...
1ms β’ [stage.test] Running tests for myapp...
2ms β’ [stage.build] [+] build
2ms β’ [stage.build] Building myapp...
3ms β’ took 3ms
| Feature | Description |
|---|---|
| Parallel by default | All stages in the same dependency layer run concurrently. |
| DAG dependency resolution | Topological sort with cycle detection. |
| HCL configuration | Declarative .hcl files with variables, locals, interpolation. |
| Lifecycle & rule engine | piperun build, piperun deploy, +stage.x / ^stage.x. |
| Pre/post hooks | Run commands before and after any stage. |
| Conditional execution | if meta-argument with expression evaluation. |
| Container support | Run stages inside Docker containers. |
| Formatter | piperun -fmt to canonically format pipeline files. |
| Validator | piperun -validate to check syntax without running. |
| Dry-run mode | piperun -dry-run shows what would execute. |
| Cross-platform | Linux, macOS, Windows. Binaries via GoReleaser. |
Download from Releases.
go install github.com/piperun/piperun/cmd/piperun@latestgit clone https://github.com/piperun/piperun.git
cd piperun/cmd/piperun
go build -o piperun .
./piperun --helpdocker run --rm -v "$PWD":/work -w /work ghcr.io/piperun/piperun:latestCreate a file called piperun.hcl:
piperun {
version = 2
}
stage "hello" {
script = "echo Hello from piperun!"
}Run it:
piperunpiperun {
version = 2
}variable "name" {
type = "string"
default = "world"
description = "Who to greet"
}Set via CLI: piperun -var name=Alice
stage "build" {
depends_on = ["stage.lint", "stage.test"]
script = "go build ./..."
pre_hook {
script = "echo starting build..."
}
post_hook {
script = "echo build finished!"
}
}stage "ci_only" {
if = "env(\"CI\") == \"true\""
script = "echo running in CI"
}stage "in_docker" {
container {
image = "node:20-alpine"
}
script = "node --version"
}stage "deploy" {
lifecycle = ["deploy"]
script = "kubectl apply -f deploy.yaml"
}Run only deploy stages: piperun deploy
piperun deploy +stage.extra_stage # force-include a stage
piperun build ^stage.slow_test # exclude a stagecd piperun
go test ./...piperun/
βββ cmd/piperun/ # CLI entrypoint
β βββ main.go
βββ internal/
β βββ dag/ # DAG builder & topological sort
β βββ engine/ # Execution engine (parallel, hooks, containers)
β βββ formatter/ # HCL formatter ("piperun fmt")
β βββ logger/ # Coloured, per-stage logging
β βββ parser/ # HCL parser β schema.Pipeline
β βββ schema/ # Data types (Pipeline, Stage, Variable, etc.)
βββ examples/
β βββ minimal/ # Hello-world pipeline
β βββ full/ # Variables, deps, hooks, lifecycle
β βββ conditional/ # if-based conditional stages
β βββ lifecycle/ # build vs deploy lifecycle demo
βββ .goreleaser.yaml # Cross-platform release config
βββ Dockerfile # Multi-stage Docker build
βββ go.mod
βββ LICENSE # Apache 2.0
βββ README.md
-
module {}block β reusable pipeline fragments from git/https/s3 -
for_eachβ iterate stages over a collection -
data {}providers β env, git, prompt, terraform -
macro {}β inline reusable stage templates -
import {}β split pipelines across files - Query engine (
--queryflag with HCL expressions) -
locals {}with full HCL expression evaluation - Stage output capture (
this.status,this.stdout) - Retry / timeout per stage
- Remote execution (SSH, Kubernetes Jobs)
- Web UI dashboard
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch (
git checkout -b feat/my-feature) - Commit your changes (
git commit -am 'feat: add something') - Push to the branch (
git push origin feat/my-feature) - Open a Pull Request