Build Definition

BuildDefinition

BuildDefinition defines the declarative configuration for a software build and containerization process. It supports multiple languages and toolchains (e.g., Go, Java, Python, Flutter, Protobuf) and manages the lifecycle of a build from source code to published artifact.

From a technical perspective, this manifest acts as a structured schema to template CI/CD pipelines (such as GitHub Actions workflows) or internal executors. The engine parses the Spec to generate execution plans consisting of test, security scan, compilation, and container publishing steps.

Property	Type	Description
apiVersion	string	The API version of the manifest, enforcing backward compatibility contracts.
kind	string	The resource type discriminator, explicitly defining this block as a BuildDefinition object.
metadata	map	Custom metadata for labeling and classifying the resource within the control plane.
spec	Spec	The concrete configuration driving the build logic.

Spec

Spec contains the user-defined configuration for the build process. It provides variables such as target languages, build flags, platform matrix, and publishing registries which are used by the engine to hydrate the CI/CD pipeline templates.

Property	Type	Description
description	string	A string providing descriptive context about this build process. This description is optional but will drastically improve the understanding of the AI assistant about the structural elements of the organization.
type	string	Specifies the primary language or toolchain for the build process. Evaluates the discriminator branch for pipeline stages and executor images in workflows.
workDir	string	Root directory where the build will take place. Applies the base execution directory path context for all pipeline stages.
private	bool	If true, indicates that the source code for this build is in a private repository that requires authentication. Configures pipeline authentication mechanisms required to checkout external module references.
path	string	The relative path within the source repository to the code that should be built. If not specified, the root of the repository is used. Overrides targeted execution directories for discrete compilation phases.
stages	list of string	A list of prioritized build stages to execute. Defines chronological step blocks mapping directly onto generated workflow definitions.
golang	Golang	Settings specific to building Go applications. Required if 'type' is 'GOLANG'.
flutter	Flutter	Settings specific to building Flutter applications. Required if 'type' is 'FLUTTER'.
protobuf	Protobuf	Settings for compiling Protobuf definitions. Required if 'type' is 'PROTOBUF'.
python	Python	Settings specific to building Python applications. Required if 'type' is 'PYTHON'.
java	Java	Settings specific to building Java applications. Required if 'type' is 'JAVA'.
mojo	Mojo	Settings specific to building Mojo applications. Required if 'type' is 'MOJO'.
helm	Helm	Settings for packaging Helm charts. Required if 'type' is 'HELM'.
publish	Publish	Defines where to natively publish the final artifact of a build, typically used for language-specific packages like Go modules or Python packages.
containerize	list of Containerize	Defines one or more container images to be built and uploaded. Requires the 'containerize' phase to be declared in stages.
validator	Validator	Defines a custom, ad-hoc execution validation stage for the build. Required if 'type' is 'VALIDATOR'.
terraform	Terraform	Settings for packaging and publishing Terraform modules. Required if 'type' is 'TERRAFORM'.

Containerize

Containerize dictates the translation of code or binaries into an OCI-compliant image. Generates steps interacting with Docker Buildx to leverage layer caching, structural metadata stamping, and registry uploads.

Property	Type	Description
name	string	A unique name for the container image to be built. This name is used for tagging the final image.
dockerfile	string	The path to the Dockerfile within the source repository. If not specified, it defaults to 'Dockerfile' in the build 'path'.
platforms	list of string	A list of platforms to build the container image for (e.g., 'linux/amd64', 'linux/arm64'). Controls the cross-compilation matrix variables for the container build phases.
registries	list of string	A list of 'ArtifactRegistry' manifest names where the built container image will be pushed.

Flutter

Flutter configures builds for Flutter/Dart applications. It captures Flutter SDK channels, target platforms, and publish registries to translate into the relevant flutter build commands per target interface.

Property	Type	Description
options	list of string	Command-line options to pass to the flutter build.
versions	list of string	Flutter SDK versions to use for the build matrix.
channel	string	The SDK release channel (stable, beta, standard).
platforms	list of string	Target compilation platforms (web, android, ios, windows, macos, linux).
registry	string	Target registry to publish the compiled outputs or packages.

Golang

Golang configures builds for Go applications. It captures standard Go toolchain parameters like CGO settings, target platforms, and build flags to dynamically generate the required go build matrix in the CI/CD pipeline.

Property	Type	Description
buildType	string	Specifies whether to build a binary ('bin') or a library ('lib'). Dictates the final build command and output artifacts. 'bin' produces an executable, while 'lib' produces a package for use in other Go projects.
obfuscated	bool	Explicit toggle to obfuscate Go builds using Garble. Drives the compiler to use an obfuscated build toolchain instead of standard execution.
target	string	The path to the main package to be built (e.g., './cmd/server'). Instructs the build pipeline on the specific target location.
buildFlags	list of string	A list of additional flags to pass to the 'go build' command (e.g., '-ldflags "-X main.version=1.2.3"').
versions	list of string	A list of Go versions to build against. Orchestrates dynamic build matrices across multiple version targets to ensure compatibility.
platforms	TargetPlatforms	Defines the operating systems (goos) and architectures (goarch) to build for. Populates platform constraints into the build matrix dynamic generation.
cgo	Cgo	Configuration for builds that require CGO. Injects environment flags and required external compilation libraries.

Cgo

Cgo manages C-language interop dependencies during the Go build. Technically, it toggles CGO_ENABLED and injects -ldflags or C-compiler library dependencies.

Property	Type	Description
enabled	bool	Set to true to enable CGO for the build.
libraries	list of string	A list of system libraries to link against (e.g., '-lm').
gccFlags	list of string	A list of additional flags to pass to the C compiler.

Platform

Platform represents a single target OS and architecture combination. Used to explicitly ignore or specify exact cross-compilation binaries.

Property	Type	Description
goarch	string
goos	string

TargetPlatforms

TargetPlatforms defines the cross-compilation matrix. This is translated into a build matrix array in GitHub Actions, dynamically spawning parallel jobs for each valid GOOS/GOARCH combination minus exclusions.

Property	Type	Description
goos	list of string	A list of target operating systems (e.g., 'linux', 'windows', 'darwin').
goarch	list of string	A list of target CPU architectures (e.g., 'amd64', 'arm64').
ignore	list of Platform	A list of OS/architecture combinations to exclude from the build matrix.

Helm

Helm configures packaging steps for Kubernetes Helm Charts. Automates helm lint, helm package, and helm push within the pipeline process.

Property	Type	Description
chartLocation	string	The path to the Helm chart within the source repository. Configures the working directory bound to packaging commands.

Java

Java configures Maven or Gradle JVM-based builds. Generates CI steps that rely on standard JVM docker images passing along JDK targets and registry URIs for JAR/WAR deployments.

Property	Type	Description
buildType	string	Specifies whether to output a standalone binary ('bin') or a dependency library ('lib').
buildTool	string	The specific JVM build toolchain to utilize.
versions	list of string	JDK versions forming the build execution matrix.
registries	list of string	List of Maven/Gradle registries to push the produced JAR instances.
maven	Maven	Native settings applied purely to Maven-oriented toolchains.

Maven

Maven encapsulates settings specific to the Maven build toolchain. Defines plugin caching properties to speed up iterative pipeline runs.

Property	Type	Description
cache	Cache

Cache

Cache instructs the CI pipeline to perform directory caching of /root/.m2/repository. Determines cache step generation for the workflow pipeline.

Property	Type	Description
enabled	bool

Mojo

Mojo configures native compile flows utilizing the modular Mojo compiler structure. Passes LLVM/MLIR compilation properties to translate .mojo files down to binaries/libraries.

Property	Type	Description
buildType	string	Specifies whether to output a standalone binary ('bin') or a dependency library ('lib').
buildFlags	list of string	Compilation flags passed to mojo build.
srcFile	string	Target source file defining the entrypoint.
platforms	list of string	Target operational systems to natively cross-compile outputs to.
registry	string	Registry to push the compiled outputs.

Protobuf

Protobuf configures source code generation from Protocol Buffer definitions. It triggers protoc or buf pipelines to fetch dependencies and compile generated clients.

Property	Type	Description
generators	list of string	A list of languages for which to generate Protobuf client/server code. Specifies target language plugins to run during schema generation.
dependencies	list of Dependency	A list of external Protobuf repositories that this build depends on.
registry	string	The name of the 'ArtifactRegistry' manifest where the generated Protobuf artifacts will be published.

Dependency

Dependency points to a remote module or repository containing required .proto files. Triggers dependency updates to resolve correct external schema revisions.

Property	Type	Description
organization	string
repository	string
revision	string

Publish

Publish instructs the generic pipeline phase to upload generic outputs to a registry. Driven inherently by language choices (e.g. Go modules).

Property	Type	Description
registry	string	The name of the 'ArtifactRegistry' manifest where the final build artifact will be published.

Python

Python configures builds and isolated environments for Python utilities. Maps standard commands like pip, pytest, or PyPI registry publishes using tox/poetry logic under the hood.

Property	Type	Description
target	string	Main module to trace or compile for packaging.
buildFlags	list of string	Build flags to append when executing the Python environment bootstrap or build package.
versions	list of string	Array of Python interpreter versions to run tests/builds against in the matrix.
registry	string	Target pip-compliant registry name in Artifact Registry to push the wheel/egg.
runCmd	string	Command string used to natively run the application during non-containerized scopes.
testCmd	string	Command string used to invoke tests (e.g. pytest ./tests).

Terraform

Terraform automates linting and module packaging for Hashicorp standard configurations. Enforces terraform validate and publishing zipped module versions.

Property	Type	Description
modules	list of string	A list of relative paths corresponding to Terraform modules to be packaged or published.
registries	list of string	A list of ArtifactRegistry manifests configured for Terraform modules where the modules will be published.

Validator

Validator allows custom bash/shell evaluation injection. Spawns standalone shell steps to parse proprietary code semantics before passing the build chain.

Property	Type	Description
script	string	A script string or file path to be executed to validate the build artifacts or source code.