Skip to main content
Private registry credentials apply to private image pulls during a template build. The SDK helpers below set base_image_auth, which is request-time only: the API stores the auth kind for retry decisions, not the credential value. 
builder = Template.from_image(
    "registry.example.com/team/app:1.0",
    username="robot",
    password="token",
)
You can also attach credentials after selecting an explicit image: 
builder = (
    Template()
    .from_image("registry.example.com/team/app:1.0")
    .set_base_image_auth(username="robot", password="token")
)

​
GCP Artifact Registry

builder = Template.from_gcp_registry(
    "us-docker.pkg.dev/project/repo/app:latest",
    service_account_json="./service-account.json",
)

​
AWS ECR

builder = Template.from_aws_registry(
    "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:latest",
    access_key_id="AKIA...",
    secret_access_key="...",
    region="us-east-1",
)
Do not hard-code credentials in source files. Load them from a secret manager or environment variables in CI.

​
BuildKit Dockerfiles

For BuildKit Dockerfile builds that pull from more than one private registry, the HTTP API also accepts registry_auth, a list of { registry, auth } entries. Each registry must match a Dockerfile FROM host. These credentials are written to a temporary Docker config on the build worker and are removed with the build staging directory. Retries of private-registry builds require fresh base_image_auth or registry_auth in the retry request; old request-time values are not replayed. Builds with internet_access=False cannot pull from private registries unless the required content is already available from an accessible BuildKit cache or local build context. Keep build internet access enabled for private registry pulls that must contact the registry.