pacto

Pacto

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

A service's operational behavior — interfaces, dependencies, runtime semantics, configuration, scaling, readiness — is usually 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 verifies it against live workloads.

Pacto (/ˈpak.to/ — Spanish for pact) is not a replacement for OpenAPI, Helm, Terraform, Backstage, or Kubernetes. It adds the operational contract layer between them.

Documentation · Quickstart · Specification · Examples · Live demo

Why Pacto exists — MANIFEST.md

Three components

No sidecars and no central control plane required: the CLI uses your existing OCI registry, the operator watches CRDs, and the dashboard reads from all sources.

Try it

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

# Author and publish a contract
pacto init                                   # scaffold a pacto.yaml
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

Full install options are below; the Quickstart goes from zero to a published contract in two minutes.

How it fits together

1. A developer defines a pacto.yaml alongside the service code.
2. The CLI validates it and publishes it to an OCI registry.
3. The operator discovers the contract in-cluster, tracks every version, and checks runtime alignment (ports, replicas, health).
4. The dashboard merges all sources — local, OCI, Kubernetes, cache — into one explorable view.

Breaking change detection

Someone bumped the version, moved a port, removed an API endpoint, and dropped a config property. pacto diff catches it before the merge:

The table comes from pacto diff --output-format markdown. The exit code is non-zero on breaking changes, so it can gate merges in CI.

Dashboard

Run pacto dashboard and open your browser. It auto-detects every available source — Kubernetes (via the operator), OCI registries, local directories, and disk cache — and merges them into a single view of your fleet:

• Fleet overview — compliance, readiness, and high-blast-radius services at a glance
• Dependency graph — interactive service relationships with recursive resolution
• Ownership views — compliance and blast radius per owner, with drill-down and owner-filtered graphs
• Readiness overview — readiness scores, status, and check gaps (expired or invalid) across services
• Version history and diffs — every published version from OCI, with classified change diffs
• Service details — interfaces, configuration schemas, policy references, readiness, documentation
• Runtime status — with the operator, whether deployed services align with their contracts

Run it locally, or deploy the container image alongside the operator for a combined view: runtime state from Kubernetes plus contract data from OCI.

What a contract captures

pactoVersion: "1.0"

service:
  name: payments-api
  version: 2.1.0
  owner: team/payments

interfaces:
  - name: rest-api
    type: http
    port: 8080
    visibility: public
    contract: interfaces/openapi.yaml

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

runtime:
  workload: service
  state:
    type: stateful
    persistence:
      scope: local
      durability: persistent
    dataCriticality: high
  health:
    interface: rest-api
    path: /health

scaling:
  min: 2
  max: 10

Only pactoVersion and service are required — everything else is opt-in, so a contract can be as minimal or as detailed as your service needs. pacto init scaffolds a 1.0 contract; use 1.1 when you want the optional readiness section (everything from 1.0 stays valid under 1.1).

Capabilities

• One contract per service — a single pacto.yaml captures interfaces, dependencies, runtime semantics, configuration, scaling, and readiness
• 4-layer validation — structural (JSON Schema), cross-field, semantic, and policy enforcement
• Breaking change detection — deep OpenAPI diffing plus dependency-graph diff with full blast radius; non-zero exit gates CI
• Dependency graph resolution — recursive transitive resolution from OCI registries, siblings fetched in parallel
• Lockfiles — reproducible dependency resolution and supply-chain pinning via pacto.lock
• Packaging ignore — gitignore-style .pactoignore to exclude files from bundles
• Readiness contracts — declare operational readiness evidence (URLs, docs, tickets, reports) with weights and expiry dates; Pacto can derive readiness scores and flag expired or invalid evidence
• OCI distribution — push/pull to GHCR, ECR, ACR, Docker Hub, and Harbor with local caching; signable with cosign or Notary; no custom registry required
• Runtime verification — the Kubernetes operator tracks every contract version and checks ports, replicas, and health against running workloads
• Plugin-based generation — out-of-process plugins produce deployment artifacts from contracts
• AI integration — pacto mcp exposes contract operations as MCP tools for Claude, Cursor, and Copilot
• SBOM diffing — SPDX / CycloneDX package-level change detection

See the documentation for details on each.

When should I use Pacto?

Use Pacto when you need to:

• Know who owns each service and what it depends on
• Catch operational breaking changes before merge
• Compare contract versions across releases
• Track whether deployed workloads still match their declared contract
• Build dependency graphs without scraping dashboards or Helm values
• Surface readiness gaps before production changes

Who is this for?

• Application developers — describe your service once; validation catches misconfigurations before CI, and breaking changes are detected automatically across versions.
• Platform engineers — consume contracts to generate manifests, enforce policies, and visualize dependency graphs, with a live view of every service in the dashboard.
• DevOps / infrastructure teams — distribute contracts through existing OCI registries; the operator tracks what's deployed and whether it matches its contract.

How Pacto compares

Pacto sits alongside these tools, not on top of them — the contract becomes the shared source of truth between your API spec, your deployment tooling, and your cluster.

What Pacto is NOT

• Not a deployment tool — it describes services, not how to run them
• Not a service mesh — no sidecars, no traffic interception
• Not a replacement for OpenAPI or Helm — it complements them
• Not a service catalog — the dashboard can feed data into one

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/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.

License

MIT