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, 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. Gateway 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 accepts one build at a time, uses isolated BuildKit and containerd state, applies fixed resource limits, denies insecure build entitlements, and clears cache between jobs.

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.

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.

Failure handling

If a build cannot start, check source authorization, worker availability, entitlement, and integration state. 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.

Cleanup and rollback

Removing a source connection prevents future source-driven work but does not delete an already deployed runtime or its artifact automatically. 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.

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.