Short answer: - Prefect Cloud doesn’t pull images. Your worker does. - Private registries work on every Prefect Cloud tier, including the free one. No special plan required. - Exception: Prefect Serverless runs on Prefect’s image; you can’t use your own/private image there. Use your own workers (Docker/Kubernetes/ECS) to pull private images. How to set it up (Prefect 3.x): General idea - Point your deployment at a work pool (Docker, Kubernetes, or ECS). - Put your private image reference on the job config (either in the work pool’s base job template or as deployment job variables). - Configure the worker environment with credentials to the registry. Prefect Cloud never needs your registry creds; only the worker host/container does. Docker worker 1) Log the worker host into your registry (do this wherever the Docker worker runs): - Docker Hub:

echo "$DOCKER_PAT" | docker login --username "$DOCKER_USER" --password-stdin

- GHCR:

echo "$GHCR_TOKEN" | docker login <http://ghcr.io|ghcr.io> -u "$GITHUB_USER" --password-stdin

- ECR:

aws ecr get-login-password --region <region> \
| docker login --username AWS --password-stdin <acct>.dkr.ecr.<region>.<http://amazonaws.com|amazonaws.com>

2) Put your image on the work pool’s base job template (or as deployment job variables):

{
  "job_configuration": {
    "image": "<http://ghcr.io/acme/prefect-flows:2025-08-01|ghcr.io/acme/prefect-flows:2025-08-01>",
    "env": {},
    "volumes": [],
    "image_pull_policy": "ALWAYS",
    "auto_remove": true
  }
}

3) Create/use a Docker work pool and start a Docker worker against it. As long as the host has

docker login

to the registry, pulls will succeed. - Docs: Docker worker guide Kubernetes worker 1) Create an image pull secret in your cluster/namespace:

kubectl create secret docker-registry regcred \
  --docker-server=<registry.example.com> \
  --docker-username=<user> \
  --docker-password=<token-or-password> \
  --docker-email=<email>

2) Reference it in the work pool’s base job template so the Prefect job can pull:

apiVersion: batch/v1
kind: Job
spec:
  template:
    spec:
      imagePullSecrets:
        - name: regcred
      containers:
        - name: flow
          image: <http://ghcr.io/acme/prefect-flows:2025-08-01|ghcr.io/acme/prefect-flows:2025-08-01>
          env: []
      restartPolicy: Never

3) Run a Kubernetes worker in that cluster/namespace. The job’s pod will use the secret to pull. - Docs: Kubernetes worker guide ECS worker (Prefect + AWS) - ECR: give the ECS task execution role permissions to pull (ecr:GetAuthorizationToken, ecr:BatchCheckLayerAvailability, ecr:GetDownloadUrlForLayer, ecr:BatchGetImage). Use your ECR image in the job config. - Non‑ECR registries: set repository credentials on the task definition via AWS Secrets Manager (ECS field:

repositoryCredentials.credentialsParameter

). Put your image in the job config; ECS will use the secret to pull. - Make sure your Prefect ECS worker’s base job template maps those task settings (execution role, task role, image, etc.). - AWS docs: ECR on ECS, Private registry auth on ECS A note on GHCR scopes - Your token needs

read:packages

to pull. Pricing - Using private images is not feature-gated. Any Prefect Cloud plan supports it because the pull happens in your infra, not in Cloud. - Pricing page: Prefect Cloud pricing If you tell me which worker type (Docker/K8s/ECS) and which registry (Docker Hub, GHCR, ECR, ACR, GCR), I’ll give you the exact template and commands you need. I can even pretend to be excited about it.