Skip to main content

Build Definition

BuildDefinition​

Software build and containerization pipeline.

The engine generates the CI/CD workflow from spec.

PropertyTypeDescription
apiVersionstringAPI schema version. Must be lowops.manifests.v1.
kindstringResource kind. Must be BuildDefinition.
metadatamapThe engine reads the keys organization, github-repository and github-connection to resolve the build identity and its parent GithubRepository and GithubConnection.
specSpecUser-authored build configuration.

Spec​

User-defined build configuration.

The engine grants the CI service account access to the referenced registries.

PropertyTypeDescription
descriptionstringOptional free text. The engine does not read it.
typestringRequired. 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.
workDirstringBase directory that the build stages run from.
privateboolIf 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.
pathstringNOT YET IMPLEMENTED. The engine ignores this field. Use work_dir instead.
stageslist of stringOrdered 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.
golangGolangRequired for type: GOLANG.
flutterFlutterRequired for type: FLUTTER.
protobufProtobufRequired for type: PROTOBUF.
pythonPythonRequired for type: PYTHON.
javaJavaRequired for type: JAVA.
mojoMojoRequired for type: MOJO.
helmHelmRequired for type: HELM.
publishPublishRegistry and archive format for the publish stage.
containerizeContainerizeRequired when containerize is in stages.
validatorValidatorNOT YET IMPLEMENTED. The engine ignores this block.
terraformTerraformRequired for type: TERRAFORM.
dependsOnstringDeprecated. DEPRECATED and ignored. The engine now composes all BuildDefinitions of one github-repository into one orchestrator workflow.
reactReactRequired for type: REACT.
agentAgentRequired for type: AGENT. The engine uses only agent.registry.
phpPhpRequired for type: PHP.
nodeNodeRequired for type: NODE.
nextjsNextjsRequired for type: NEXTJS.
angularAngularRequired for type: ANGULAR.
astroAstroRequired for type: ASTRO.
hugoHugoRequired for type: HUGO.
dotnetDotnetRequired for type: DOTNET.
rustRustRequired for type: RUST.
rubyRubyRequired 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.

PropertyTypeDescription
pythonVersionstringPython version of the build environment, for example 3.12.
registrystringRequired. Name of the AGENT-type ArtifactRegistry that receives the agent wheel.
entryModulestringRequired. Python module path of the agent entrypoint, for the thin app/agent.py wrapper.
packageNamestringRequired. Top-level Python package name. It sets the wheel namespace and must match the package name in pyproject.toml.
agentDirectorystringRequired. 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.

PropertyTypeDescription
nodeVersionstringNode.js version, for example 22. Defaults to the current LTS.
packageManagerstringOne of npm, pnpm or yarn. Defaults to the one whose lockfile exists.
projectstringProject name in angular.json to build. Defaults to the default project of the workspace.
configurationstringAngular build configuration name. Defaults to production. An explicit empty string is invalid.
testScriptstringName 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.

PropertyTypeDescription
nodeVersionstringNode.js version, for example 22. Defaults to the current LTS.
packageManagerstringOne of npm, pnpm or yarn. Defaults to the one whose lockfile exists.

Containerize​

Container image build configuration.

Each BuildDefinition produces at most one image.

PropertyTypeDescription
namestringName that tags the built image. Required. Must match ^[a-z0-9]+(-[a-z0-9]+)*$.
dockerfilestringDockerfile path in the source repository. Defaults to Dockerfile in the build path.
platformslist of stringImage platforms, for example linux/amd64 or linux/arm64.
registrieslist of stringAt 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.

PropertyTypeDescription
versionslist of string.NET SDK versions in the build matrix. The first entry builds and publishes. Defaults to 9.0.x.
projectstringPath of the .csproj or .sln file to publish, relative to the build working directory. Defaults to the only one found.
blazorWasmboolIf 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.

PropertyTypeDescription
optionslist of stringExtra options for flutter build (web builds).
versionslist of stringFlutter SDK versions in the build matrix.
channelstringFlutter SDK channel, for example stable or beta.
platformslist of stringOne 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.
registrystringName of the Dart ArtifactRegistry or ExternalRegistry that resolves dependencies.

Golang​

Go build configuration.

Settings for type: GOLANG builds.

PropertyTypeDescription
buildTypestringBuild kind: bin (executable) or lib (importable package). Only a bin build can produce a container image.
obfuscatedboolIf true, the build obfuscates the code with Garble instead of go build.
targetstringPath to the Go main package, for example ./cmd/server. Must match ^[A-Za-z0-9_./-]*$.
buildFlagslist of stringExtra flags appended to go build. The schema rejects shell metacharacters (;, &, `
versionslist of stringGo versions in the build matrix. Each starts a parallel job. A bin build accepts one version only.
platformsTargetPlatformsGOOS/GOARCH matrix to cross-compile. Must be empty for lib builds and when cgo.enabled is true.
cgoCgoC interop settings. See Cgo.

Cgo​

C interop settings.

Controls CGO_ENABLED, system libraries and C-compiler flags.

PropertyTypeDescription
enabledboolIf true, the build sets CGO_ENABLED=1. Then platforms must be empty (enforced by validation).
librarieslist of stringSystem 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.
gccFlagslist of stringExtra flags for the C compiler.

Platform​

Single OS/architecture target.

A GOOS/GOARCH pair to build or to exclude.

PropertyTypeDescription
goarchstringGOARCH value, for example amd64 or arm64.
goosstringGOOS value, for example linux, darwin or windows.

TargetPlatforms​

Go build matrix definition.

The CI runs one parallel job for each valid pair.

PropertyTypeDescription
gooslist of stringGOOS values to build for.
goarchlist of stringGOARCH values to build for.
ignorelist of PlatformGOOS/GOARCH pairs to remove from the matrix.

Helm​

Helm chart configuration.

Settings for type: HELM builds.

PropertyTypeDescription
chartLocationstringPath 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.

PropertyTypeDescription
hugoVersionstringExact release (major.minor.patch), checksum-verified in CI. Defaults to the version that the engine pins.
extendedboolIf true, the build uses the extended edition (Sass/SCSS and WebP support). Defaults to false.
buildOptionslist of stringFlags 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.

PropertyTypeDescription
buildTypestringBuild kind: bin (standalone artifact) or lib (dependency library).
buildToolstringJVM build tool. Required. One of maven or gradle.
versionslist of stringJDK versions in the build matrix.
registrieslist of stringNames of Maven ArtifactRegistry or ExternalRegistry manifests that resolve dependencies. The graph links each to the repository.
mavenMavenMaven settings. Used only when build_tool is maven.

Maven​

Maven-specific settings.

Options for the Maven build tool.

PropertyTypeDescription
cacheCacheCache settings for the Maven local repository.

Cache​

Maven repository cache.

Controls whether the workflow caches /root/.m2/repository between runs.

PropertyTypeDescription
enabledboolIf true, the workflow caches the Maven local repository.

Mojo​

Mojo build configuration.

Settings for type: MOJO builds.

PropertyTypeDescription
buildTypestringBuild kind: bin or lib. Only a bin build can produce a container image.
buildFlagslist of stringExtra flags for mojo build.
srcFilestringPath to the .mojo source file that is the build entrypoint. Must match ^[A-Za-z0-9_./-]*$.
platformslist of stringOperating systems to cross-compile for.
registrystringName of the ArtifactRegistry or ExternalRegistry that resolves dependencies and receives the compiled outputs.

Nextjs​

Next.js build configuration.

Settings for type: NEXTJS builds.

PropertyTypeDescription
nodeVersionstringNode.js version, for example 22. Defaults to the current LTS.
packageManagerstringOne of npm, pnpm or yarn. Defaults to the one whose lockfile exists.
outputstringOne 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.

PropertyTypeDescription
nodeVersionstringNode.js version, for example 22. Defaults to the current LTS.
packageManagerstringOne of npm, pnpm or yarn. Defaults to the one whose lockfile exists.
buildScriptstringName 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.
testScriptstringName of the package.json script that runs the tests. Defaults to test. An explicit empty string is invalid.
lintScriptstringName 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.
entryPointstringEntry 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.

PropertyTypeDescription
versionslist of stringPHP versions (major.minor) in the test matrix. The first entry builds the code and the image. Defaults to 8.4.
frameworkstringOne of LARAVEL, SYMFONY, DRUPAL or CODEIGNITER. Empty means a plain Composer project. It selects the conventions of that framework.
extensionslist of stringExtra PHP extensions for the CI and the image, for example intl. Lowercase names only.
staticAnalysisstringOne of PHPSTAN, PSALM or NONE. Defaults to the preset tool. Psalm runs with taint analysis.
testRunnerstringOne of PHPUNIT or PEST. Defaults to the preset runner.
runtimestringOne of FRANKENPHP (one process, built-in web server) or FPM_NGINX (PHP-FPM behind nginx). Defaults to FRANKENPHP. Used when you give no Dockerfile.
documentRootstringWeb root relative to the repository, for example public. Defaults to the preset convention. The container serves only this directory.
assetsWebAssetsOptional asset build for a CDN application. See WebAssets.

Protobuf​

Protobuf generation configuration.

Settings for type: PROTOBUF builds, which run buf or protoc.

PropertyTypeDescription
generatorslist of stringNOT YET IMPLEMENTED. The engine ignores this field. Each value must be golang or dart.
dependencieslist of DependencyRemote modules that the build resolves before generation.
registrystringName 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.

PropertyTypeDescription
organizationstringBSR organization of the module. Must match ^[a-z0-9]+(-[a-z0-9]+)*$.
repositorystringBSR repository of the module. Same format as organization.
revisionstringPinned 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.

PropertyTypeDescription
registrystringName of the ArtifactRegistry or ExternalRegistry to push to. It must exist and match the build type (STATIC for REACT bundles).
archiveFormatstringArchive 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.

PropertyTypeDescription
targetstringMain module to compile or package.
buildFlagslist of stringExtra flags for the environment bootstrap or the package build.
versionslist of stringPython interpreter versions in the test and build matrix.
registrystringName of the Python ArtifactRegistry or ExternalRegistry that resolves dependencies and, with the publish stage, receives the wheel or egg.
runCmdstringCommand that runs the application natively in non-containerized scopes. The schema rejects the same shell metacharacters as build_flags of Golang.
testCmdstringCommand that runs the tests, for example pytest.

React​

React build configuration.

Settings for type: REACT builds (React, Vite, TypeScript).

PropertyTypeDescription
nodeVersionstringNode.js major version, for example 22. Defaults to the current LTS.
buildOptionslist of stringExtra options for vite build.

Ruby​

Ruby build configuration.

Settings for type: RUBY builds. The build uses a frozen Gemfile.lock.

PropertyTypeDescription
versionslist of stringRuby versions in the test matrix. The first entry builds and containerizes. Defaults to 3.4.
frameworkstringRAILS for a Rails application, empty for a plain Ruby project. It selects the framework conventions.
testRunnerstringOne of RSPEC or MINITEST. Defaults to the runner of the project.
assetsWebAssetsOptional 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.

PropertyTypeDescription
toolchainstringOne of stable, beta or a release (1.84 or 1.84.1). Defaults to stable. The build does not accept nightly.
packagestringWorkspace member to build and containerize (cargo build -p). Empty builds the root package.
featureslist of stringCargo features to enable for build and test.
targetstringTarget 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.

PropertyTypeDescription
moduleslist of stringRelative paths of the Terraform modules to package and publish.
registrieslist of stringNames 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.

PropertyTypeDescription
scriptstringScript 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.

PropertyTypeDescription
nodeVersionstringNode.js major version, for example 22. Defaults to the current LTS.
packageManagerstringOne of npm, pnpm or yarn. Defaults to the one whose lockfile exists. The build needs the lockfile and does not run install scripts.
buildScriptstringName of the package.json script that makes the assets (not a command line). Defaults to build. An explicit empty string is invalid.
outputDirstringOutput directory of the built assets, relative to the build working directory. Defaults to the framework convention.