Build Definition
BuildDefinition
Software build and containerization pipeline.
The engine generates the CI/CD workflow from spec.
| Property | Type | Description |
|---|---|---|
| apiVersion | string | API schema version. Must be lowops.manifests.v1. |
| kind | string | Resource kind. Must be BuildDefinition. |
| metadata | map | The engine reads the keys organization, github-repository and github-connection to resolve the build identity and its parent GithubRepository and GithubConnection. |
| spec | Spec | User-authored build configuration. |
Spec
User-defined build configuration.
The engine grants the CI service account access to the referenced registries.
| Property | Type | Description |
|---|---|---|
| description | string | Optional free text. The engine does not read it. |
| type | string | Required. One of GOLANG, JAVA, FLUTTER, PYTHON, DOCKER, MOJO, VALIDATOR, PROTOBUF, TERRAFORM, HELM, REACT, AGENT, PHP, NODE, NEXTJS, ANGULAR, ASTRO, HUGO, DOTNET, RUST, RUBY. VALIDATOR and AGENT have no workflow builder and fail workflow generation. The engine also rejects a type that this release does not enable. |
| workDir | string | Base directory that the build stages run from. |
| private | bool | If true, the build runs on self-hosted runners, with authenticated checkout of private modules. It increases the runner counts of the parent connection. Rejected if the parent GithubRepository is public. |
| path | string | NOT YET IMPLEMENTED. The engine ignores this field. Use work_dir instead. |
| stages | list of string | Ordered list of stages to generate. Each must be one of analysis, test, validate, security-scan, build, publish, release, containerize. publish requires publish.registry. containerize requires the containerize block, and PROTOBUF and HELM builds reject it. A REACT build can use both stages. |
| golang | Golang | Required for type: GOLANG. |
| flutter | Flutter | Required for type: FLUTTER. |
| protobuf | Protobuf | Required for type: PROTOBUF. |
| python | Python | Required for type: PYTHON. |
| java | Java | Required for type: JAVA. |
| mojo | Mojo | Required for type: MOJO. |
| helm | Helm | Required for type: HELM. |
| publish | Publish | Registry and archive format for the publish stage. |
| containerize | Containerize | Required when containerize is in stages. |
| validator | Validator | NOT YET IMPLEMENTED. The engine ignores this block. |
| terraform | Terraform | Required for type: TERRAFORM. |
| dependsOn | string | Deprecated. DEPRECATED and ignored. The engine now composes all BuildDefinitions of one github-repository into one orchestrator workflow. |
| react | React | Required for type: REACT. |
| agent | Agent | Required for type: AGENT. The engine uses only agent.registry. |
| php | Php | Required for type: PHP. |
| node | Node | Required for type: NODE. |
| nextjs | Nextjs | Required for type: NEXTJS. |
| angular | Angular | Required for type: ANGULAR. |
| astro | Astro | Required for type: ASTRO. |
| hugo | Hugo | Required for type: HUGO. |
| dotnet | Dotnet | Required for type: DOTNET. |
| rust | Rust | Required for type: RUST. |
| ruby | Ruby | Required for type: RUBY. |
Agent
Agent build configuration.
Settings for type: AGENT builds. NOT YET IMPLEMENTED: the engine uses only registry and ignores the other fields.
| Property | Type | Description |
|---|---|---|
| pythonVersion | string | Python version of the build environment, for example 3.12. |
| registry | string | Required. Name of the AGENT-type ArtifactRegistry that receives the agent wheel. |
| entryModule | string | Required. Python module path of the agent entrypoint, for the thin app/agent.py wrapper. |
| packageName | string | Required. Top-level Python package name. It sets the wheel namespace and must match the package name in pyproject.toml. |
| agentDirectory | string | Required. Agent source directory, relative to the repository root (the --agent-directory flag of agents-cli). |
Angular
Angular build configuration.
Settings for type: ANGULAR builds. The production bundle goes to a STATIC registry or an unprivileged nginx image.
| Property | Type | Description |
|---|---|---|
| nodeVersion | string | Node.js version, for example 22. Defaults to the current LTS. |
| packageManager | string | One of npm, pnpm or yarn. Defaults to the one whose lockfile exists. |
| project | string | Project name in angular.json to build. Defaults to the default project of the workspace. |
| configuration | string | Angular build configuration name. Defaults to production. An explicit empty string is invalid. |
| testScript | string | Name of the package.json script that runs the unit tests once, headless. Defaults to test. An explicit empty string is invalid. |
Astro
Astro build configuration.
Settings for type: ASTRO builds. The static output goes to a STATIC registry or an unprivileged nginx image.
| Property | Type | Description |
|---|---|---|
| nodeVersion | string | Node.js version, for example 22. Defaults to the current LTS. |
| packageManager | string | One of npm, pnpm or yarn. Defaults to the one whose lockfile exists. |
Containerize
Container image build configuration.
Each BuildDefinition produces at most one image.
| Property | Type | Description |
|---|---|---|
| name | string | Name that tags the built image. Required. Must match ^[a-z0-9]+(-[a-z0-9]+)*$. |
| dockerfile | string | Dockerfile path in the source repository. Defaults to Dockerfile in the build path. |
| platforms | list of string | Image platforms, for example linux/amd64 or linux/arm64. |
| registries | list of string | At least one required. Names of Docker ArtifactRegistry or ExternalRegistry manifests that receive the image. Each must exist. |
Dotnet
.NET build configuration.
Settings for type: DOTNET builds (ASP.NET Core, Blazor WebAssembly). The restore uses locked mode, so the build needs the lock files.
| Property | Type | Description |
|---|---|---|
| versions | list of string | .NET SDK versions in the build matrix. The first entry builds and publishes. Defaults to 9.0.x. |
| project | string | Path of the .csproj or .sln file to publish, relative to the build working directory. Defaults to the only one found. |
| blazorWasm | bool | If true, the project is a Blazor WebAssembly site. The published wwwroot is the static bundle for publish, and containerize builds an nginx image. |
Flutter
Flutter build configuration.
Settings for type: FLUTTER builds.
| Property | Type | Description |
|---|---|---|
| options | list of string | Extra options for flutter build (web builds). |
| versions | list of string | Flutter SDK versions in the build matrix. |
| channel | string | Flutter SDK channel, for example stable or beta. |
| platforms | list of string | One of web, android, ios, windows, macos, linux. Only web generates a workflow, and containerize requires it. ios and windows increase the self-hosted runner counts of the parent connection. |
| registry | string | Name of the Dart ArtifactRegistry or ExternalRegistry that resolves dependencies. |
Golang
Go build configuration.
Settings for type: GOLANG builds.
| Property | Type | Description |
|---|---|---|
| buildType | string | Build kind: bin (executable) or lib (importable package). Only a bin build can produce a container image. |
| obfuscated | bool | If true, the build obfuscates the code with Garble instead of go build. |
| target | string | Path to the Go main package, for example ./cmd/server. Must match ^[A-Za-z0-9_./-]*$. |
| buildFlags | list of string | Extra flags appended to go build. The schema rejects shell metacharacters (;, &, ` |
| versions | list of string | Go versions in the build matrix. Each starts a parallel job. A bin build accepts one version only. |
| platforms | TargetPlatforms | GOOS/GOARCH matrix to cross-compile. Must be empty for lib builds and when cgo.enabled is true. |
| cgo | Cgo | C interop settings. See Cgo. |
Cgo
C interop settings.
Controls CGO_ENABLED, system libraries and C-compiler flags.
| Property | Type | Description |
|---|---|---|
| enabled | bool | If true, the build sets CGO_ENABLED=1. Then platforms must be empty (enforced by validation). |
| libraries | list of string | System libraries to link. Each entry is also an Alpine package name for apk add, and must match ^[a-zA-Z0-9][a-zA-Z0-9._-]*$ to prevent shell injection. |
| gccFlags | list of string | Extra flags for the C compiler. |
Platform
Single OS/architecture target.
A GOOS/GOARCH pair to build or to exclude.
| Property | Type | Description |
|---|---|---|
| goarch | string | GOARCH value, for example amd64 or arm64. |
| goos | string | GOOS value, for example linux, darwin or windows. |
TargetPlatforms
Go build matrix definition.
The CI runs one parallel job for each valid pair.
| Property | Type | Description |
|---|---|---|
| goos | list of string | GOOS values to build for. |
| goarch | list of string | GOARCH values to build for. |
| ignore | list of Platform | GOOS/GOARCH pairs to remove from the matrix. |
Helm
Helm chart configuration.
Settings for type: HELM builds.
| Property | Type | Description |
|---|---|---|
| chartLocation | string | Path to the Helm chart in the source repository. Must match ^[A-Za-z0-9_./-]*$. |
Hugo
Hugo build configuration.
Settings for type: HUGO builds. The static output goes to a STATIC registry or an unprivileged nginx image.
| Property | Type | Description |
|---|---|---|
| hugoVersion | string | Exact release (major.minor.patch), checksum-verified in CI. Defaults to the version that the engine pins. |
| extended | bool | If true, the build uses the extended edition (Sass/SCSS and WebP support). Defaults to false. |
| buildOptions | list of string | Flags appended to hugo, for example --environment, production. The schema rejects the same shell metacharacters as build_flags of Golang. |
Java
Java build configuration.
Settings for type: JAVA builds.
| Property | Type | Description |
|---|---|---|
| buildType | string | Build kind: bin (standalone artifact) or lib (dependency library). |
| buildTool | string | JVM build tool. Required. One of maven or gradle. |
| versions | list of string | JDK versions in the build matrix. |
| registries | list of string | Names of Maven ArtifactRegistry or ExternalRegistry manifests that resolve dependencies. The graph links each to the repository. |
| maven | Maven | Maven settings. Used only when build_tool is maven. |
Maven
Maven-specific settings.
Options for the Maven build tool.
| Property | Type | Description |
|---|---|---|
| cache | Cache | Cache settings for the Maven local repository. |
Cache
Maven repository cache.
Controls whether the workflow caches /root/.m2/repository between runs.
| Property | Type | Description |
|---|---|---|
| enabled | bool | If true, the workflow caches the Maven local repository. |
Mojo
Mojo build configuration.
Settings for type: MOJO builds.
| Property | Type | Description |
|---|---|---|
| buildType | string | Build kind: bin or lib. Only a bin build can produce a container image. |
| buildFlags | list of string | Extra flags for mojo build. |
| srcFile | string | Path to the .mojo source file that is the build entrypoint. Must match ^[A-Za-z0-9_./-]*$. |
| platforms | list of string | Operating systems to cross-compile for. |
| registry | string | Name of the ArtifactRegistry or ExternalRegistry that resolves dependencies and receives the compiled outputs. |
Nextjs
Next.js build configuration.
Settings for type: NEXTJS builds.
| Property | Type | Description |
|---|---|---|
| nodeVersion | string | Node.js version, for example 22. Defaults to the current LTS. |
| packageManager | string | One of npm, pnpm or yarn. Defaults to the one whose lockfile exists. |
| output | string | One of STANDALONE (self-contained server for containerize) or EXPORT (static site for publish and a CDN). Defaults to STANDALONE. Must match output in the Next.js configuration, or the build fails. |
Node
Node.js build configuration.
Settings for type: NODE builds. The build installs from the lockfile with install scripts disabled, and the container has production dependencies only.
| Property | Type | Description |
|---|---|---|
| nodeVersion | string | Node.js version, for example 22. Defaults to the current LTS. |
| packageManager | string | One of npm, pnpm or yarn. Defaults to the one whose lockfile exists. |
| buildScript | string | Name of the package.json script that compiles the service. Omit it for a service that runs from source (no build step). An explicit empty string is invalid. |
| testScript | string | Name of the package.json script that runs the tests. Defaults to test. An explicit empty string is invalid. |
| lintScript | string | Name of the package.json script that runs the linter. Defaults to lint. The build skips it if the script does not exist. An explicit empty string is invalid. |
| entryPoint | string | Entry file that the container starts with node, relative to the repository. Required for containerize when you give no Dockerfile. |
Php
PHP build configuration.
Settings for type: PHP builds (Composer projects and PHP frameworks). The build needs the Composer lockfile.
| Property | Type | Description |
|---|---|---|
| versions | list of string | PHP versions (major.minor) in the test matrix. The first entry builds the code and the image. Defaults to 8.4. |
| framework | string | One of LARAVEL, SYMFONY, DRUPAL or CODEIGNITER. Empty means a plain Composer project. It selects the conventions of that framework. |
| extensions | list of string | Extra PHP extensions for the CI and the image, for example intl. Lowercase names only. |
| staticAnalysis | string | One of PHPSTAN, PSALM or NONE. Defaults to the preset tool. Psalm runs with taint analysis. |
| testRunner | string | One of PHPUNIT or PEST. Defaults to the preset runner. |
| runtime | string | One of FRANKENPHP (one process, built-in web server) or FPM_NGINX (PHP-FPM behind nginx). Defaults to FRANKENPHP. Used when you give no Dockerfile. |
| documentRoot | string | Web root relative to the repository, for example public. Defaults to the preset convention. The container serves only this directory. |
| assets | WebAssets | Optional asset build for a CDN application. See WebAssets. |
Protobuf
Protobuf generation configuration.
Settings for type: PROTOBUF builds, which run buf or protoc.
| Property | Type | Description |
|---|---|---|
| generators | list of string | NOT YET IMPLEMENTED. The engine ignores this field. Each value must be golang or dart. |
| dependencies | list of Dependency | Remote modules that the build resolves before generation. |
| registry | string | Name of the BUF ArtifactRegistry or ExternalRegistry that receives the generated artifacts. |
Dependency
External Protobuf module.
A remote BSR module that the build resolves before generation.
| Property | Type | Description |
|---|---|---|
| organization | string | BSR organization of the module. Must match ^[a-z0-9]+(-[a-z0-9]+)*$. |
| repository | string | BSR repository of the module. Same format as organization. |
| revision | string | Pinned module revision, such as a semver tag or commit SHA. Must match ^[A-Za-z0-9._-]*$. |
Publish
Native or static publish target.
Language builds upload their native artifact. REACT builds upload the dist/ archive to a STATIC registry for target: CDN applications.
| Property | Type | Description |
|---|---|---|
| registry | string | Name of the ArtifactRegistry or ExternalRegistry to push to. It must exist and match the build type (STATIC for REACT bundles). |
| archiveFormat | string | Archive format for a REACT dist/ bundle: tar.gz (default) or zip. Language-native publishes ignore it. |
Python
Python build configuration.
Settings for type: PYTHON builds.
| Property | Type | Description |
|---|---|---|
| target | string | Main module to compile or package. |
| buildFlags | list of string | Extra flags for the environment bootstrap or the package build. |
| versions | list of string | Python interpreter versions in the test and build matrix. |
| registry | string | Name of the Python ArtifactRegistry or ExternalRegistry that resolves dependencies and, with the publish stage, receives the wheel or egg. |
| runCmd | string | Command that runs the application natively in non-containerized scopes. The schema rejects the same shell metacharacters as build_flags of Golang. |
| testCmd | string | Command that runs the tests, for example pytest. |
React
React build configuration.
Settings for type: REACT builds (React, Vite, TypeScript).
| Property | Type | Description |
|---|---|---|
| nodeVersion | string | Node.js major version, for example 22. Defaults to the current LTS. |
| buildOptions | list of string | Extra options for vite build. |
Ruby
Ruby build configuration.
Settings for type: RUBY builds. The build uses a frozen Gemfile.lock.
| Property | Type | Description |
|---|---|---|
| versions | list of string | Ruby versions in the test matrix. The first entry builds and containerizes. Defaults to 3.4. |
| framework | string | RAILS for a Rails application, empty for a plain Ruby project. It selects the framework conventions. |
| testRunner | string | One of RSPEC or MINITEST. Defaults to the runner of the project. |
| assets | WebAssets | Optional asset build for a CDN application. See WebAssets. |
Rust
Rust build configuration.
Settings for type: RUST builds. The build is --locked, so it needs Cargo.lock.
| Property | Type | Description |
|---|---|---|
| toolchain | string | One of stable, beta or a release (1.84 or 1.84.1). Defaults to stable. The build does not accept nightly. |
| package | string | Workspace member to build and containerize (cargo build -p). Empty builds the root package. |
| features | list of string | Cargo features to enable for build and test. |
| target | string | Target triple of the container binary: x86_64-unknown-linux-musl (default) or aarch64-unknown-linux-musl. |
Terraform
Terraform module configuration.
Settings for type: TERRAFORM builds.
| Property | Type | Description |
|---|---|---|
| modules | list of string | Relative paths of the Terraform modules to package and publish. |
| registries | list of string | Names of Terraform ArtifactRegistry or ExternalRegistry manifests that the modules resolve from. Each must exist. The graph links each to the repository. |
Validator
Custom validation step.
NOT YET IMPLEMENTED. The engine ignores this block, which is for type: VALIDATOR.
| Property | Type | Description |
|---|---|---|
| script | string | Script string or file path that validates the build. |
WebAssets
Front-end asset pipeline.
The Node.js asset build of a server-rendered framework (PHP, Rails). The publish stage packages its output for a CDN application.
| Property | Type | Description |
|---|---|---|
| nodeVersion | string | Node.js major version, for example 22. Defaults to the current LTS. |
| packageManager | string | One of npm, pnpm or yarn. Defaults to the one whose lockfile exists. The build needs the lockfile and does not run install scripts. |
| buildScript | string | Name of the package.json script that makes the assets (not a command line). Defaults to build. An explicit empty string is invalid. |
| outputDir | string | Output directory of the built assets, relative to the build working directory. Defaults to the framework convention. |