Build Definition

BuildDefinition

Declarative definition of a software build and containerization pipeline.

Templates a CI/CD pipeline (e.g. GitHub Actions workflows) for a single build across many languages and toolchains (Go, Java, Python, Flutter, Protobuf, Mojo, Helm, Terraform, React, and more). The engine parses spec to generate test, security-scan, compile, publish, and container steps, and links the build to its parent GithubRepository and GithubConnection in the dependency graph.

Property	Type	Description
apiVersion	string	API schema version. Pins the manifest to a specific schema contract for backward-compatibility. Must be the constant lowops.manifests.v1.
kind	string	Resource kind discriminator. Identifies this document as a BuildDefinition so the engine routes it to the correct defaulter, validator, computer, and executor. Must be the constant BuildDefinition.
metadata	map	Classification labels and graph linkage. Free-form key/value pairs used to classify the manifest. Reserved keys (organization, github-repository, github-connection) are read by the engine to resolve this build's identity and its parent GithubRepository/GithubConnection in the dependency graph.
spec	Spec	Build configuration. See Spec. The user-authored source, toolchain, stages, and publishing targets driving this build.

Spec

User-defined build configuration.

Describes the source, toolchain, stages, and publishing targets for one build. The computer selects the language block matching type to generate the CI/CD workflow, and the executor grants the CI service account IAM on the referenced registries. Each BuildDefinition produces at most one container image.

Property	Type	Description
description	string	Human-readable description. Optional free text describing this build. Not read by any engine consumer; serves purely as documentation and as context for AI assistants reasoning about the manifest.
type	string	Build toolchain selector. Required. Discriminator choosing which language block and workflow builder drive the build; validated by proto to one of GOLANG, JAVA, FLUTTER, PYTHON, DOCKER, MOJO, VALIDATOR, PROTOBUF, TERRAFORM, HELM, REACT, AGENT. Note: VALIDATOR and AGENT have no workflow builder yet and will fail workflow generation.
workDir	string	Build working directory. Base directory the generated workflow runs its build stages from.
private	bool	Self-hosted runner flag. When true, the build runs on self-hosted (internal) runners and configures authenticated checkout for private modules; the computer bumps the parent connection's runner counts accordingly. Rejected by the validator when the parent GithubRepository is public.
path	string	Source subdirectory. NOT YET IMPLEMENTED. Declared in the schema but currently ignored by the engine (no consumer reads it; use work_dir instead). Intended relative path within the repository to the code to build, defaulting to the repository root.
stages	list of string	Ordered build stages. Prioritized list of stages to generate, each validated by proto to one of analysis, test, validate, security-scan, build, publish, release, containerize. The publish stage requires publish.registry; the containerize stage requires the containerize block and is rejected for PROTOBUF and HELM builds.
golang	Golang	Go settings. See Golang. Required when type is GOLANG.
flutter	Flutter	Flutter settings. See Flutter. Required when type is FLUTTER.
protobuf	Protobuf	Protobuf settings. See Protobuf. Required when type is PROTOBUF.
python	Python	Python settings. See Python. Required when type is PYTHON.
java	Java	Java settings. See Java. Required when type is JAVA.
mojo	Mojo	Mojo settings. See Mojo. Required when type is MOJO.
helm	Helm	Helm settings. See Helm. Required when type is HELM.
publish	Publish	Native publish settings. See Publish. Names the registry the publish stage uploads the language-native artifact to.
containerize	Containerize	Container image settings. See Containerize. Required when containerize is listed in stages; each BuildDefinition produces at most one image (use separate BuildDefinitions for more).
validator	Validator	Custom validation settings. NOT YET IMPLEMENTED. See Validator; the VALIDATOR build type has no workflow builder, so this block is currently ignored. Intended to declare an ad-hoc shell validation stage for type: VALIDATOR.
terraform	Terraform	Terraform settings. See Terraform. Required when type is TERRAFORM.
dependsOn	string	Deprecated. Deprecated build dependency. Deprecated. DEPRECATED and ignored: previously referenced another BuildDefinition by name for sequential execution. The engine now automatically composes all BuildDefinitions targeting the same github-repository into a single orchestrator workflow.
react	React	React settings. See React. Required when type is REACT.
agent	Agent	Agent settings. See Agent. Required when type is AGENT; currently only agent.registry is consumed.

Agent

Agent build configuration.

Settings for type: AGENT builds that package an ADK AI agent as a versioned wheel for Agent Engine. NOT YET IMPLEMENTED for workflow generation: the computer has no AGENT build case, so only registry is currently consumed (the executor grants the CI service account push IAM on it); the remaining fields are ignored.

Property	Type	Description
pythonVersion	string	Build Python version. NOT YET IMPLEMENTED. Declared in the schema but currently ignored by the engine (no consumer reads it). Intended Python version for the agent build environment (e.g. 3.12).
registry	string	Target AGENT registry name. Required. Name of the ArtifactRegistry manifest (AGENT/Python type) the agent wheel is published to. Proto-required, and consumed by the executor to grant the CI service account artifact-push IAM.
entryModule	string	Agent entry module. Required. NOT YET IMPLEMENTED. Declared in the schema (proto-required) but currently ignored by the engine (no consumer reads it). Intended Python module path for the agent entrypoint (e.g. pvot.agents.pvot_agent.agent), used to scaffold the thin app/agent.py wrapper.
packageName	string	Top-level package name. Required. NOT YET IMPLEMENTED. Declared in the schema (proto-required) but currently ignored by the engine (no consumer reads it). Intended top-level Python package name (e.g. pvot) determining the wheel namespace; must match the package name in pyproject.toml.
agentDirectory	string	Agent source directory. Required. NOT YET IMPLEMENTED. Declared in the schema (proto-required) but currently ignored by the engine (no consumer reads it). Intended agent source directory relative to the repository root (maps to the agents-cli --agent-directory flag).

Containerize

Container image build configuration.

Describes the OCI image produced by the containerize stage: image name, Dockerfile, target platforms, and destination registries. Built with Docker Buildx (layer caching, metadata stamping); each BuildDefinition produces at most one image.

Property	Type	Description
name	string	Image name. Required. Name used to tag the built image; validated by proto to be a lowercase, dash-separated slug (^[a-z0-9]+(-[a-z0-9]+)*$).
dockerfile	string	Dockerfile path. Path to the Dockerfile within the source repository. Defaults to Dockerfile in the build path when empty.
platforms	list of string	Target image platforms. Platforms the image is built for (e.g. linux/amd64, linux/arm64), driving the container build matrix.
registries	list of string	Destination registry names. At least one required. Names of ArtifactRegistry/ExternalRegistry manifests (Docker type) the built image is pushed to; validated by proto (min 1) and by the Go validator, which also checks each registry exists and is Docker-typed.

Flutter

Flutter build configuration.

Settings for type: FLUTTER builds: SDK channel and versions, target platforms, and the source registry, translated into flutter build steps. Only the web platform is currently wired for workflow generation.

Property	Type	Description
options	list of string	Extra flutter build options. Command-line options passed verbatim to flutter build (web builds).
versions	list of string	Flutter SDK versions. Flutter SDK versions forming the build matrix.
channel	string	Flutter SDK channel. SDK release channel to install (e.g. stable, beta).
platforms	list of string	Target platforms. Compilation targets, each restricted by proto to one of web, android, ios, windows, macos, linux. Only web is currently supported by workflow generation; ios/windows targets bump the parent connection's macOS/Windows self-hosted runner counts, and the containerize stage requires web.
registry	string	Source registry name. Name of the ArtifactRegistry/ExternalRegistry manifest (Dart type) used to resolve dependencies during the build.

Golang

Go build configuration.

Toolchain settings for type: GOLANG builds — build kind, target package, versions, cross-compilation matrix, and CGO — used to generate the Go build workflow.

Property	Type	Description
buildType	string	Binary vs library build selector. Selects whether the Go build produces an executable (bin) or an importable package (lib); validated by proto to be one of bin/lib. Drives the generated go build command and output artifacts, and only bin builds may be containerized (enforced by the validator).
obfuscated	bool	Garble obfuscation toggle. When true, the generated Go build uses the Garble obfuscating toolchain instead of the standard go build.
target	string	Main package path. Path to the Go main package to build (e.g. ./cmd/server), passed through to the generated build command.
buildFlags	list of string	Extra go build flags. Additional flags appended verbatim to the generated go build invocation (e.g. -ldflags "-X main.version=1.2.3").
versions	list of string	Go toolchain versions. Go versions forming the build matrix; each spawns a parallel job. For bin builds only a single version is expected (the validator rejects more than one).
platforms	TargetPlatforms	Cross-compilation matrix. GOOS/GOARCH combinations (minus exclusions) expanded into the build matrix. Must be empty for lib builds and when CGO is enabled (both enforced by the validator).
cgo	Cgo	CGO configuration. Enables and configures C interop for the build; when enabled, cross-compilation is restricted so platforms must be empty.

Cgo

C interop settings.

Toggles CGO_ENABLED and supplies the system libraries and C-compiler flags needed when the Go build links against C code.

Property	Type	Description
enabled	bool	CGO enable flag. When true, the build sets CGO_ENABLED=1. CGO builds are restricted to the default platform, so platforms must be empty (enforced by the validator).
libraries	list of string	System libraries to link. Libraries linked against during the CGO build (e.g. -lm).
gccFlags	list of string	Extra C-compiler flags. Additional flags passed to the C compiler during the CGO build.

Platform

Single OS/architecture target.

One concrete GOOS/GOARCH pair, used to name an exact cross-compilation target or an entry to exclude from the build matrix.

Property	Type	Description
goarch	string	Target CPU architecture. GOARCH value for this platform entry (e.g. amd64, arm64).
goos	string	Target operating system. GOOS value for this platform entry (e.g. linux, darwin, windows).

TargetPlatforms

Go build matrix definition.

Lists the operating systems and architectures to cross-compile for plus any combinations to exclude; expanded into the CI build matrix, spawning one parallel job per valid GOOS/GOARCH pair.

Property	Type	Description
goos	list of string	Target operating systems. List of GOOS values to build for (e.g. linux, windows, darwin).
goarch	list of string	Target CPU architectures. List of GOARCH values to build for (e.g. amd64, arm64).
ignore	list of Platform	Excluded OS/architecture pairs. Combinations removed from the expanded GOOS x GOARCH matrix.

Helm

Helm packaging configuration.

Settings for type: HELM builds that lint, package, and push a Helm chart within the pipeline.

Property	Type	Description
chartLocation	string	Chart directory path. Path to the Helm chart within the source repository, used as the working directory for the packaging commands.

Java

Java build configuration.

Settings for type: JAVA builds: build kind, Maven/Gradle toolchain, JDK versions, registries, and Maven cache, generating JVM-based CI steps for JAR/WAR outputs.

Property	Type	Description
buildType	string	Binary vs library build selector. Selects whether the build outputs a standalone artifact (bin) or a dependency library (lib); validated by proto to be one of bin/lib.
buildTool	string	JVM build tool. Required. Selects the toolchain driving the build; validated by proto (required) and the Go validator to be one of maven/gradle.
versions	list of string	JDK versions. JDK versions forming the build matrix.
registries	list of string	Source registry names. Names of ArtifactRegistry/ExternalRegistry manifests (Maven type) used to resolve dependencies during the build; each is related to the repository in the graph.
maven	Maven	Maven settings. See Maven. Applied only when build_tool is maven.

Maven

Maven-specific settings.

Options applied only when the Maven toolchain is selected, currently the local-repository cache toggle.

Property	Type	Description
cache	Cache	Cache settings. See Cache. Enables directory caching of the Maven local repository.

Cache

Maven repository cache.

Controls whether the workflow caches /root/.m2/repository between runs to speed up iterative builds.

Property	Type	Description
enabled	bool	Cache enable flag. When true, the generated workflow adds a caching step for the Maven local repository.

Mojo

Mojo build configuration.

Settings for type: MOJO builds: build kind, compile flags, entrypoint source file, target platforms, and registry, passing LLVM/MLIR properties to mojo build.

Property	Type	Description
buildType	string	Binary vs library build selector. Selects whether the build outputs a standalone binary (bin) or a library (lib); validated by proto to be one of bin/lib. Only bin builds may be containerized (enforced by the validator).
buildFlags	list of string	Extra compile flags. Flags passed to mojo build.
srcFile	string	Entrypoint source file. Path to the .mojo source file defining the build entrypoint.
platforms	list of string	Target platforms. Operating systems to cross-compile the outputs for.
registry	string	Target registry name. Name of the ArtifactRegistry/ExternalRegistry manifest used to resolve and publish the compiled Mojo outputs.

Protobuf

Protobuf generation configuration.

Settings for type: PROTOBUF builds: which language stubs to generate, external module dependencies, and the target BUF registry. Triggers buf/protoc pipelines to resolve dependencies and compile generated clients.

Property	Type	Description
generators	list of string	Target code generators. NOT YET IMPLEMENTED. Declared in the schema (proto restricts values to golang/dart) but currently ignored by the engine (no consumer reads it). Intended to select which language plugins run during Protobuf generation.
dependencies	list of Dependency	External module dependencies. Remote Protobuf modules resolved before generation; each becomes a dependency-update entry in the generated workflow.
registry	string	Target BUF registry name. Name of the ArtifactRegistry/ExternalRegistry manifest (BUF type) the generated Protobuf artifacts are published to.

Dependency

External Protobuf module.

A remote BSR module (organization/repository at a revision) whose .proto files this build depends on and resolves before generation.

Property	Type	Description
organization	string	BSR organization. Owning organization of the remote Protobuf module.
repository	string	BSR repository. Name of the remote Protobuf repository/module.
revision	string	Module revision. Pinned revision/commit of the remote module to resolve.

Publish

Native publish target.

Names the registry used by the publish stage to upload language-native artifacts (Go modules, Python wheels, Maven JARs, Terraform modules, Helm charts, etc.).

Property	Type	Description
registry	string	Target ArtifactRegistry name. Name of the ArtifactRegistry/ExternalRegistry manifest the publish stage pushes the native artifact to. Validated (per build type) to exist and be of the matching registry type.

Python

Python build configuration.

Settings for type: PYTHON builds: entry module, build flags, interpreter versions, registry, and run/test commands, mapped onto pip/pytest/PyPI publish steps.

Property	Type	Description
target	string	Entry module. Main module to compile/package for the build.
buildFlags	list of string	Extra build flags. Flags appended when bootstrapping the environment or building the package.
versions	list of string	Python interpreter versions. Interpreter versions forming the test/build matrix.
registry	string	Target PyPI registry name. Name of the ArtifactRegistry/ExternalRegistry manifest (Python type) used to resolve dependencies during the build, and to push the wheel/egg when the publish stage is present.
runCmd	string	Application run command. Command used to run the application natively in non-containerized scopes.
testCmd	string	Test command. Command used to invoke the test suite (e.g. pytest ./tests).

React

React build configuration.

Settings for type: REACT builds (React + Vite + TypeScript). Generates strict CI covering ESLint type-aware rules, strict tsc, npm audit scanning, Vitest reporting, a Vite production build, and optional Nginx SPA containerization.

Property	Type	Description
nodeVersion	string	Node.js major version. Node.js LTS major version to use (e.g. 22). Defaults to the current LTS release when omitted.
buildOptions	list of string	Extra vite build options. Options passed verbatim to vite build.

Terraform

Terraform packaging configuration.

Settings for type: TERRAFORM builds that validate and package/publish Terraform modules to a registry.

Property	Type	Description
modules	list of string	Module paths. Relative paths to the Terraform modules to package and publish.
registries	list of string	Source registry names. Names of ArtifactRegistry/ExternalRegistry manifests (Terraform type) the modules resolve from; each is validated to exist and be Terraform-typed and is related to the repository in the graph.

Validator

Custom validation step.

NOT YET IMPLEMENTED. Intended to declare an ad-hoc shell validation stage for type: VALIDATOR builds, but the engine has no VALIDATOR workflow builder, so this block is currently ignored.

Property	Type	Description
script	string	Validation script. NOT YET IMPLEMENTED. Declared in the schema but currently ignored by the engine (no consumer reads it). Intended script string or file path executed to validate the build artifacts or source code.