pacto

README

Pacto

Pacto is to service operations what OpenAPI is to HTTP APIs.

A service's operational behavior — interfaces, dependencies, runtime semantics, configuration, scaling and readiness — is scattered across Helm values, wikis and dashboards, and drifts from what's actually running. Pacto captures it once in a validated, versioned contract (pacto.yaml), distributes it through your existing OCI registry and lets pacto diff catch breaking changes while the operator catches runtime drift. It doesn't replace OpenAPI, Helm, Terraform, Backstage or Kubernetes — it adds the operational contract layer between them, composing the interfaces you already own and adding what no single one does: ownership, dependencies, compatibility and readiness over time.

Documentation · Quickstart · Specification · Examples · Live demo

Why Pacto exists — MANIFEST.md

---

Where Pacto fits

flowchart LR
    DEV([Developer]) --> C
    OA[OpenAPI spec] -. composed .-> C
    JS[Config JSON Schema] -. composed .-> C
    C["📋 pacto.yaml<br/>operational contract"] --> R[(OCI registry)]
    R --> P["Platforms and tools<br/>CI · Kubernetes · Backstage · Crossplane"]

Pacto composes the interfaces you already own into one versioned contract, distributes it like a container image and lets whatever runs your services read it instead of reverse-engineering it.

The three tools

flowchart LR
    CLI["CLI · design-time and CI<br/>init · validate · diff · doc · push"] --> R[(OCI registry)]
    R --> DASH["Dashboard · anytime<br/>graph · ownership · SBOM · readiness · docs"]
    R --> OP["Operator · in-cluster<br/>track · verify runtime drift"]
    OP -. runtime state .-> DASH

No sidecars and no central control plane: the CLI uses your existing OCI registry, the operator watches CRDs and the dashboard merges every source — local, OCI, Kubernetes and cache — into one view.

---

Try it

# Author and publish a contract (install is below)
pacto init my-service && cd my-service       # scaffold a contract bundle
pacto validate .                             # 4-layer validation
pacto push oci://ghcr.io/acme/svc-pacto      # tag inferred from service.version

# Catch breaking changes in CI
pacto diff oci://ghcr.io/acme/svc:1.0 oci://ghcr.io/acme/svc:2.0

# Explore everything in a browser
pacto dashboard                              # auto-detects local, OCI and K8s sources

The Quickstart goes from zero to a published contract in two minutes.

What a contract captures

pactoVersion: "1.2"

service:
  name: payments-api
  version: 2.1.0
  owner:
    team: payments
    dri: alice

interfaces:
  - name: rest-api
    type: http
    port: 8080
    visibility: public
    contract: interfaces/openapi.yaml   # points at your existing OpenAPI spec

dependencies:
  - name: auth
    ref: oci://ghcr.io/acme/auth-pacto@sha256:abc123
    required: true
    compatibility: "^2.0.0"

Only pactoVersion and service are required — everything else (runtime semantics, scaling, configuration, policies and readiness) is opt-in. Each interface's contract points at a schema you already own, so a contract composes your interfaces rather than redefining them. See the Contract Reference for the full schema.

---

What you get

Bump a version, move a port, remove an endpoint, drop a config property — pacto diff classifies it and fails CI before the merge:

$ pacto diff oci://ghcr.io/acme/svc:1.0 oci://ghcr.io/acme/svc:2.0
NON_BREAKING  service.version               1.0.0 → 2.0.0
BREAKING      interfaces.port               8081 → 9090
BREAKING      openapi.paths[/predict]       removed
BREAKING      schema.properties.model_path  removed
exit status 1                                # non-zero gates the merge

Everything a contract enables, from one artifact:

• Dependency graph — transitive service relationships and blast radius, recursively resolved
• Ownership registry — every service by team and DRI, with per-owner compliance and readiness
• SBOM inventory — SPDX / CycloneDX package inventory and package-level diffs across versions
• Operational docs — pacto doc renders Markdown, an offline dashboard-grade HTML site or an interactive Swagger/Scalar API explorer
• Readiness scoring — operational-readiness assessment per service, surfaced in the fleet view
• Runtime verification — with the operator, whether deployed workloads still match their contract
• OCI distribution — push/pull to GHCR, ECR, ACR, Docker Hub and Harbor with local caching; signable with cosign or Notary
• Reproducibility and supply chain — pacto.lock for pinned resolution, gitignore-style .pactoignore for packaging
• Extensibility — out-of-process plugins generate deployment artifacts; pacto mcp exposes contract operations to Claude, Cursor and Copilot

The dashboard merges local, OCI and Kubernetes sources into one fleet view; deploy the container image alongside the operator to combine runtime state with contract data.

---

How Pacto compares

Pacto composes the interface tools it sits between (OpenAPI, config schemas) and complements deploy tools (Helm, Terraform). It gets compared just as often to the platform-engineering tier — the orchestrators, provisioners and portals that act on a service. Pacto is not one of them: its job is four verbs over a single versioned OCI artifact — diff (semantic breaking changes), graph (transitive blast radius), enforce (recursive policy, fail-closed) and verify (the same artifact at design-time via the CLI and at runtime via the operator) — while making zero deployment decisions.

	Versioned artifact	Semantic diff	Dependency graph	Transitive policy	Runtime verify	Orchestrator-agnostic	Deploys?
Score	—	—	—	—	—	✅	No
Crossplane Configuration	✅	—	—	—	—	—	Yes
KubeVela / OAM	—	—	Partial	—	—	Partial	Yes
Radius	—	—	✅	—	—	Partial	Yes
Kratix	—	—	—	—	—	Partial	Yes
Backstage / Port	—	—	Partial	—	—	✅	No
Kargo	✅	—	—	—	—	✅	Yes
Pacto	✅	✅	✅	✅	✅	✅	No

✅ first-class · Partial adjacent or limited · — not in scope. A 2026 snapshot, and several of these are complementary rather than competing: a contract can gate a Kargo promotion, feed a Backstage card or front a Crossplane provisioner. The point is the combination — Pacto is the only row that is a versioned, diffable, graph-resolved, policy-enforced and runtime-verified contract that stays orchestrator-agnostic and never deploys.

What Pacto is NOT:

• Not a deployment tool — it describes services, not how to run them, and makes zero deployment decisions, which keeps it complementary to deploy engines like KubeVela, Radius and Kratix rather than competing with them
• Not a service mesh — no sidecars, no traffic interception
• Not a service catalog or portal — the dashboard renders ownership, SBOM and readiness from contracts and runtime; it feeds Backstage/Port, it doesn't replace them
• Not another configuration language — it composes the schemas you already own

See MANIFEST.md for the full rationale.

---

Installation

# Installer script
curl -fsSL https://raw.githubusercontent.com/TrianaLab/pacto/main/scripts/get-pacto.sh | bash

# Go
go install github.com/trianalab/pacto/v2/cmd/pacto@latest

# From source
git clone https://github.com/TrianaLab/pacto.git && cd pacto && make build

Documentation

Full documentation at trianalab.github.io/pacto.

Guide	Description
Quickstart	From zero to a published contract in 2 minutes
Contract Reference	Every field, validation rule and change classification
For Developers	Write and maintain contracts alongside your code
For Platform Engineers	Consume contracts for deployment, policies and graphs
CLI Reference	All commands, flags and output formats
Dashboard	Deploy the dashboard container alongside the operator
Kubernetes Operator	Runtime contract tracking and consistency verification
MCP Integration	Connect AI tools (Claude, Cursor, Copilot) to Pacto via MCP
Plugin Development	Build plugins to generate artifacts from contracts
Examples	PostgreSQL, Redis, RabbitMQ, NGINX, gRPC and more

---

License

MIT