Build Service

Service: build-service · Port: 8098

build-service turns your Git repository into a container image. It's what makes "deploy from GitHub" work: give it a repository, branch and Dockerfile path, and it builds and pushes an image, which then follows exactly the same deployment path as any other image. build-service never runs your app itself — it only builds images.

How a build runs

1. A Kaniko Job starts in the host cluster's dedicated kubeopera-builds namespace. Builds run centrally, so tenant vClusters never need permission to run privileged build pods, and build capacity is managed in one place.
2. The repository is cloned, using a short-lived token for private repositories (or the stored credential of a build configuration).
3. Kaniko builds the image from your Dockerfile and build context — no Docker daemon required.
4. The image is pushed to your tenant's area of KubeOpera's built-in registry: registry.<domain>/tenant-<tenant_id>/<app_id>:<commit-sha>.
5. The build hands off the image reference for deployment.

Each tenant has its own registry credentials, issued by auth-service, which can only reach that tenant's images — one tenant's build can never read or overwrite another's.

Why Kaniko?

Kaniko builds standard Dockerfiles inside Kubernetes without privileged access to a container runtime. It's predictable for Dockerfile-based projects and lighter than a full pipeline engine for "clone, build, push".

Build on push

A build configuration links a repository and branch to an app. Once registered, every push to that branch builds a new image and — if you choose — redeploys the app automatically.

1. Create a build configuration (the Deploy wizard creates one for you when you deploy from GitHub).
2. Add the webhook URL and secret it gives you to your repository (trigger: push).
3. Push. A build starts, and the result appears in the app's history and in Pipelines.

Incoming webhooks are verified with the provider's signature (X-Hub-Signature-256 for GitHub, X-Gitlab-Token for GitLab). A push to a branch with no build configuration is simply ignored. You can also start a build from a configuration at any time with Build now.

Progress reporting

Builds report into their pipeline from the server, with clone and build-and-push stages timed from the build pod itself. You can close the browser mid-build; the run still completes with full detail.

REST API

Method	Path	Description
POST	/api/v1/builds	Start a build.
GET	/api/v1/builds	List builds.
GET	/api/v1/builds/{id}	Build status.
GET	/api/v1/builds/{id}/logs	Build logs (streamed while running).
POST · GET	/api/v1/build-configs	Create or list build configurations.
DELETE	/api/v1/build-configs/{id}	Remove a build configuration.
POST	/api/v1/build-configs/{id}/trigger	Build now.
POST	/webhook/github · /webhook/gitlab	Inbound push webhooks (signature-verified).
GET	/healthz	Health check.

Users reach these routes through kubeopera-api, which scopes every call to the caller's tenant.

Configuration

Variable	Default	Description
DATABASE_URL	—	PostgreSQL connection.
BUILD_NAMESPACE	kubeopera-builds	Namespace for build Jobs.
KANIKO_IMAGE	gcr.io/kaniko-project/executor:latest	Kaniko executor image.
REGISTRY_HOST	—	The built-in registry's address.
BUILD_TIMEOUT	30m	Maximum duration of a build.
CICD_GATEWAY_BASE_URL	http://cicd-gateway:8087	Where build progress is reported.
WEBHOOK_SECRET_KEY	—	Key used to generate per-configuration webhook secrets.
PORT	8098	HTTP port.