Skip to content
mahendrarathore1742Public

About

A declarative pipeline orchestration engine powered by HCL, bringing Terraform-style composability, modularity, and infrastructure-grade execution semantics to CI/CD workflows.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

Β 

History

6 Commits

Folders and files

NameName
Last commit message
Last commit date
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸš€ piperun

Go License

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

✨ Features

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.

πŸ“¦ Installation

Pre-built binaries

Download from Releases.

Go install

go install github.com/piperun/piperun/cmd/piperun@latest

Build from source

git clone https://github.com/piperun/piperun.git
cd piperun/cmd/piperun
go build -o piperun .
./piperun --help

Docker

docker run --rm -v "$PWD":/work -w /work ghcr.io/piperun/piperun:latest

🏁 Quick Start

Create a file called piperun.hcl:

piperun {
  version = 2
}

stage "hello" {
  script = "echo Hello from piperun!"
}

Run it:

piperun

πŸ“– Configuration Reference

Top-level block

piperun {
  version = 2
}

Variables

variable "name" {
  type        = "string"
  default     = "world"
  description = "Who to greet"
}

Set via CLI: piperun -var name=Alice

Stages

stage "build" {
  depends_on = ["stage.lint", "stage.test"]
  script     = "go build ./..."

  pre_hook {
    script = "echo starting build..."
  }
  post_hook {
    script = "echo build finished!"
  }
}

Conditional

stage "ci_only" {
  if     = "env(\"CI\") == \"true\""
  script = "echo running in CI"
}

Container

stage "in_docker" {
  container {
    image = "node:20-alpine"
  }
  script = "node --version"
}

Lifecycles

stage "deploy" {
  lifecycle = ["deploy"]
  script    = "kubectl apply -f deploy.yaml"
}

Run only deploy stages: piperun deploy

Allow / Block stages

piperun deploy +stage.extra_stage   # force-include a stage
piperun build ^stage.slow_test      # exclude a stage

πŸ§ͺ Running Tests

cd piperun
go test ./...

πŸ—οΈ Project Structure

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

πŸ—ΊοΈ Roadmap

  • 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 (--query flag 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

🀝 Contributing

Contributions are welcome! Please:

  1. Fork the repository
  2. Create a feature branch (git checkout -b feat/my-feature)
  3. Commit your changes (git commit -am 'feat: add something')
  4. Push to the branch (git push origin feat/my-feature)
  5. Open a Pull Request

πŸ“œ License

Apache License 2.0


About

A declarative pipeline orchestration engine powered by HCL, bringing Terraform-style composability, modularity, and infrastructure-grade execution semantics to CI/CD workflows.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages