Git sources and Build Workers

Configure the connector using Git hosting. That guide also separates repository permissions from the target permissions needed to start saved builds and read their history. Registry credentials are covered under Container registries.

Git source support connects an approved repository revision to an immutable build artifact. It can supply a Docker Container, Deployment, Compose Project, or Pages release, but the resulting workload still follows the lifecycle of its owning resource. A source connection is not permission to change a production route or traffic target by itself.

Decide what automation is allowed to do

Separate three decisions: who may read source, what qualifies as an approved artifact, and whether that artifact may deploy automatically. Keeping them separate lets a team automate routine releases without giving a repository webhook unlimited production authority.

The source owner controls repository access and the commit to build. The platform owner controls the Build Worker, build policy, registry, and deployment target. The service owner defines acceptance and rollback. Opfield connects these records and preserves provenance from commit to digest, but a successful build remains only an input to a release.

Use automatic build when every selected source change should produce an artifact. Enable automatic deploy only after the owning resource has a tested health gate and recovery path, and only for branches whose change-control model permits it. For higher-risk services, keep artifact approval and deployment as separate human decisions.

Prerequisites and ownership

Use a supported, allowlisted source integration and authorize only the repository access needed for the build. Select an exact branch revision, then confirm the assigned dedicated Build Worker is online. The worker runs one build at a time by default (Parallel jobs on its Node page, up to 16), uses isolated BuildKit and containerd state, applies fixed resource limits, denies insecure build entitlements, and clears cache between jobs. A Build Worker host needs systemd.

Queued builds go to Build Workers in the order they appear in the Nodes list: the first online worker takes builds until all its parallel jobs are busy, then the next one does. Drag a worker higher to prefer it, or to the bottom to keep it for overflow. The list order is top-level folders by position, inside a folder its subfolders first and then its Nodes, and Nodes outside any folder last. A worker takes builds only for its own platform (architecture).

Build Secrets are source-scoped and mounted as secrets during the build. Do not put credentials in build arguments, image references, repository URLs, committed configuration, or logs. The build worker owns execution isolation; the registry holds the produced artifact; the target Docker node later pulls and runs that artifact.

Build and review the artifact

1. Connect the integration and choose the repository, branch, and intended revision.
2. Configure the build input and source-scoped secrets.
3. Start the build and follow its Task from worker assignment through artifact publication.
4. Review redacted logs, vulnerability findings, policy result, source commit, and immutable artifact digest.
5. Select the approved digest in the owning Container, Deployment, or Pages workflow.

While a build is rolled out to a Container, Deployment, or Compose Project, Opfield locks that target: lifecycle and configuration changes, secret changes, Availability changes, and migrations are refused with BUILD_ROLLOUT_IN_PROGRESS until the rollout succeeds, fails, or is cancelled, and the Console shows a banner on the target. The lock survives an Opfield restart. If the target is busy with another operation when the rollout starts, the rollout waits up to 5 minutes and then fails with BUILD_ROLLOUT_TARGET_BUSY. Pages releases are not locked this way. During an Opfield update, builds triggered by webhooks or polling are deferred and start once after the update.

Sync now on the Git source of a Container, Deployment, Compose Project, or Pages Project checks the branch right away and builds when it moved and automatic builds are on. The source’s vulnerability policy rejects artifacts with findings at or above the selected severity (Critical by default, or High, Medium, or Low); None approves every scanned artifact, and Disabled approves artifacts without requiring a scan. Build results are pushed to the registry without being kept in the worker’s own image store, so builds do not fill the worker’s disk.

Automatic build and automatic deploy are independent controls. Keep automatic deployment disabled until the health and rollback path is proven for that workload. A successful build only proves that an artifact exists; it does not prove that the application starts correctly on a target node.

Folder placement of built workloads

A Container or Deployment created from a Git source goes into the folder chosen when it is created: the folder field on the Repository tab of the deploy dialog, or folderId through the API and MCP. Creating it there needs the create permission on that folder, and a user who may create only in folders must choose one; the dialog preselects the only allowed folder. Configuring the source also needs integrations:<provider>:use on the repository; see Git hosting.

Until its first build finishes, the workload is listed in that folder with Awaiting build in place of an image. It can be moved like any other container: with Move to folder…, by dragging it, or through the API and MCP, which needs edit permission on the workload and on the destination. The first build creates it in the folder it is in at that moment and checks the create permission there, also when source automation starts the build. A folder-limited user therefore never ends up with a built workload at the root. The name stays reserved for the source meanwhile: creating, duplicating, renaming, or importing another container under it fails with 409 NAME_IN_USE.

Failure handling

If a build cannot start, check source authorization, worker availability, entitlement, and integration state. A cancelled build that reads Build paused: <user> no longer has use on <repo> means the account that saved the source lost integrations:<provider>:use on the repository; see Who can build and view results?. If it fails after start, use the phase and logs to separate dependency, secret, policy, build-definition, or artifact-publication failures. Correct the source or build configuration, then run a new build. Retrying produces a new operation and preserves the previous history.

When the worker or source automation is unavailable, existing history remains useful for diagnosis, but new builds must not be assumed to run. Do not substitute a mutable image tag for the missing immutable artifact; wait for a verified build or use a separately approved image.

Readiness after a rollout

When a build is rolled out to a Container, Opfield recreates it with the new image and waits up to 60 seconds for it to become ready: healthy when the image has a health check, otherwise running for 10 seconds without a restart. A container that crash-loops, exits, or turns unhealthy is returned to its previous image, and the build fails with BUILD_ROLLOUT_ROLLED_BACK, or BUILD_ROLLOUT_ROLLBACK_FAILED when the previous image could not be restored. The error names the container state, exit code, and restart count, followed by the last lines of its log, and the deployed commit stays the previous one. Other rollout failures are reported as BUILD_ROLLOUT_FAILED. A Deployment uses its own health-checked blue/green path: a candidate that fails is stopped and traffic stays on the serving slot. A Compose revision built from Git whose published port another workload already holds on the Node fails with COMPOSE_HOST_PORT_IN_USE, and no revision is created.

Cleanup and rollback

Removing a source connection prevents future source-driven work but does not delete an already deployed runtime or its artifact automatically. Removing a container removes its Git source, and when the repository webhook of a removed container cannot be deleted, its source stops building and deploying, so a new commit cannot recreate the container; the cleanup is retried later. Build images of deleted Containers, Deployments, and Compose Projects are removed from their Nodes automatically, usually within a minute, and Nodes that were offline are checked again every 10 minutes. An unused build image can also be removed by hand from the Node’s images; one that a container on the Node still uses is refused with 409 GATEWAY_INTERNAL_IMAGE. Before revoking the connection, decide which artifacts remain required for a rollback. Artifact retention is governed by the registry and the owning resource’s active, rollback, in-progress, pinned, and recent-successful history.

Success criteria

An acceptable build identifies the repository and exact commit, finishes on an approved worker, produces an immutable digest, passes the configured vulnerability policy, and exposes logs without secrets. Deployment acceptance is separate: the target resource must pull that digest, start successfully, pass health verification, and serve the expected client path.

Retain enough build and artifact history to explain what is running and to restore the previous known-good release. A mutable tag, a successful console log, or a green build badge without the digest is insufficient production evidence.

Operator details: isolation and diagnosis

Build Workers are dedicated execution boundaries because repository content and build definitions can execute code. Keep worker credentials narrow, do not co-locate unrelated sensitive workloads, and treat build output as untrusted until policy and provenance checks complete. Build Secrets should be mounted only for the build step that needs them and must not be copied into image layers.

Build steps cannot reach the Build Worker host itself, over IPv4 or IPv6, with either egress profile (internet or offline). On a host with IPv6 the worker needs ip6tables and does not start without it.

When a build is queued, distinguish lack of worker capacity from source or policy failure. When it runs and fails, identify the phase: source checkout, dependency resolution, Dockerfile or Compose build, vulnerability admission, registry publication, or final acknowledgement. Preserve the bounded log and commit before retrying. A retry should create a new auditable attempt rather than overwrite the failed record.