Platform

platform is the EvalOps control-plane monorepo.

It combines three previously separate surfaces:

• shared protobuf contracts from evalops/proto
• shared runtime code from evalops/service-runtime
• service implementations under one Go module

The repo now owns the public contract surface, the shared runtime, service entrypoints, service internals, DB migrations, build assets, generated SDKs, and release automation in one place.

Quick Start

Recommended local baseline:

• Go 1.26.1 via the go 1.26.0 / toolchain go1.26.1 root module
• Node 20
• Python 3.12
• buf
• jq
• Docker for container-backed integration tests
• gh for workflow and release inspection
• ko only when publishing or smoke-testing images locally

Common commands:

make proto-lint
make runtime-lint
make event-types-check
make generate
make test
make test TEST_FLAGS="-short -race"
make test TEST_FLAGS="-race -p 2"
make ko-base-image-check
make upstream-drift
make build SERVICE=identity
make test SERVICE=identity
make go-lint SERVICE=identity
make ko-install
make image SERVICE=keys IMAGE_REPO=ghcr.io/evalops/platform/keys
make hook-archives HOOK_VERSION=v0.1.36

What Lives Here

Repo layout:

• proto/: public cross-service protobuf contracts
• gen/: generated Go, TypeScript, and Python code for the public contracts
• pkg/: shared runtime packages plus runtime-private generated proto output
• cmd/: service and helper entrypoints
• internal/: service implementation packages
• db/: namespaced SQL migrations
• build/: charts, configs, scripts, compose files, and other non-image assets
• openapi/: service OpenAPI documents that are still checked in separately
• docs/services/: per-service docs migrated from standalone repos
• apps/: service-owned UIs that intentionally remain outside the root package
• sdk/: service-owned SDKs that are not part of the root TypeScript package

Monorepo decisions that matter to contributors:

• The repo is a single Go module: github.com/evalops/platform.
• Public contract generation remains committed under gen/go, gen/ts, and gen/python.
• Runtime-private proto generation remains under pkg/gen/proto/go.
• Pure-Go images publish with root ko config instead of per-service Dockerfiles.
• Services that need REST compatibility should prefer google.api.http annotations plus the shared Vanguard wrapper over duplicate handwritten REST route trees.
• Cross-service analytics APIs should use common.v1.TimeRange, common.v1.Money, common.v1.InsightSource, and common.v1.EvidenceRef rather than defining local period, currency, source, or evidence messages.
• gate still uses a CGO-capable ko profile because it ships checked-in configs and policies via kodata.
• Standalone service repositories are archived; service source of truth is the monorepo service layout.
• HTTP services should use startup.NotifyContext, startup.Lifecycle, and startup.RunHTTPServer instead of bespoke signal/shutdown goroutines.
• Long-lived HTTP service commands have been standardized on that startup flow; worker, migrator, benchmark, and similar non-HTTP or one-shot commands are expected to keep command-specific lifecycle handling.

Services

Imported services currently include:

• agent-mcp
• approvals
• secret-broker
• attribution
• audit
• compliance
• connectors
• entities
• gate
• governance
• identity
• keys
• llm-gateway
• memory
• meter
• notifications
• objectives
• hris
• pipeline
• prompts
• agent-registry
• ingest
• skills
• traces

There are also repo-level helper commands that are not published as normal service images, including agent-hook, gate-benchmark, gate-policy, dev-token, and hris-seed.

For the full service catalog, command mapping, extra docs, OpenAPI files, frontend surfaces, and publish status, see docs/services/README.md.

CI And Release Automation

The repo currently runs these top-level workflows:

• CI: proto/runtime lint, proto breaking checks on pull requests, code generation freshness, descriptions coverage, go vet, a root golangci-lint ratchet for new issues, Go tests, TypeScript package checks, Python package checks, and disposable-Postgres migration validation. generate is an independent freshness gate; the test and packaging jobs do not wait on it
• Publish Images: selective ko publishing to GHCR based on changed paths with the ko version sourced from the root Makefile and packages: write scoped to the publish job only. Published image digests are signed with keyless cosign, and SPDX SBOMs are uploaded as workflow artifacts.
• CodeQL: static analysis for Go, JavaScript/TypeScript, and Python on PRs, pushes to main, manual dispatch, and a weekly schedule
• ko-base-image-drift: verifies the pinned Chainguard base image digests in .ko.yaml on PRs touching that file, on pushes, and on a weekly schedule
• SDK Publish: verifies generated Go, TypeScript, and Python SDKs when public proto or generated files change on main. Manual releases publish @evalops/sdk-ts, @evalops/proto, and evalops-sdk when registry gates are enabled; gen/ts/v* tags publish @evalops/proto from the root package so downstream TypeScript consumers can install the generated protobuf surface directly. The Go job tags the github.com/evalops/platform/gen/go submodule.
• agent-hook: builds cross-platform hook archives and attaches them to tag-based releases
• workflow-security-guardrails: validates workflow permissions and SHA pinning
• actionlint: workflow syntax and style linting
• Dependabot: weekly updates for Go modules, GitHub Actions, npm, and pip, plus monthly Docker updates

Current test policy:

• Pull requests run go test -short -race ./...
• Pushes to main run go test -race -p 2 ./...
• Generated code freshness is enforced in CI for both gen/ and pkg/gen/

See docs/testing-ci.md for the exact local parity commands and the environment variables used by integration tests.

Generated Contracts And Runtime

Public contracts and code generation are owned at the repo root. Runtime-private protobufs remain under pkg/.

Important points:

• buf.yaml and pkg/buf.yaml both use WIRE_JSON breaking checks.
• Generated code is intentionally committed and marked as generated in GitHub diffs via .gitattributes.
• descriptions.yaml is checked against the public proto surface in CI.
• proto/common/v1/analytics.proto provides shared analytics primitives used by attribution P&L now and intended for governance policy synthesis and production-to-eval generation next.
• proto/events/v1/event_types.yaml catalogs allowed CloudEvent type values and expected Any payload messages using a proto-shaped YAML schema, and CI validates that catalog against the checked-in event fixtures.
• The root package publishes @evalops/proto from gen/dist for downstream TypeScript consumers that need the canonical generated protobuf surface (npm i @evalops/[email protected]).
• The gen/ts package publishes the generated @evalops/sdk-ts TypeScript contract surface.
• The gen/python package publishes evalops-sdk from the committed generated Python modules.
• The Go SDK is a submodule under gen/go with module path github.com/evalops/platform/gen/go.

See docs/contracts-and-codegen.md for the exact edit/regenerate workflow.

Development Docs

Start here depending on task:

• CONTRIBUTING.md: contributor entry point
• docs/README.md: docs index
• docs/development.md: local setup, layout, and common workflows
• docs/testing-ci.md: local validation and CI parity
• docs/contracts-and-codegen.md: proto, generation, and packaging workflow
• docs/services/README.md: service inventory and docs map
• docs/monorepo-transition.md: migration status, archived upstream ledger, and history lookup
• pkg/README.md: shared runtime package reference

Transition Notes

The service-repo crossover window is closed. Standalone service repositories are archived, _import/ mirrors have been removed, and service development now happens directly in this monorepo. The only upstream sync helpers that remain are for shared proto and service-runtime history.

Shared repos:

• make upstream-drift
• make sync-proto
• make sync-runtime

Merge proto and runtime sync PRs with merge commits rather than squash merges so the upstream parent remains in history and drift checks stay accurate.

The final service archive evidence lives in docs/services/upstream-archive.md.

Imported History

Relocated service files may still show the monorepo import commit in some blame views.

Configure local blame once so Git skips relocation noise where possible:

git config blame.ignoreRevsFile .git-blame-ignore-revs

When you need the original standalone-repo history, inspect the second parent of the matching import <service> history subtree merge:

merge_commit=$(git log --merges --grep='import identity history' --format=%H -n 1)
git log "${merge_commit}^2" -- internal/organizations/service.go

The general path-mapping guidance is documented in docs/monorepo-transition.md.