Using private image registries with Gitpod Self-Hosted

⚠️ Gitpod Self-hosted has been replaced with Gitpod Dedicated, a self-hosted, single-tenant managed service that runs in your private cloud account but is managed by us.
Try out Gitpod Dedicated.

This guide outlines the considerations to take when using images for workspaces that originate from private image registries that are not stored in the image registry already configured in the KOTS Installation UI. This is useful when, for example, you want to pull private base images from one registry and then store the built images in another.

Please refer to the Docker image documentation for more information about workspace images.

Note: there are two ways of setting an image for a workspace: via the installation-wide default workspaceImage and the .gitpod.yml file. The .gitpod.yml file will take precedence if both are set.


To access private registries, Gitpod needs to have the corresponding access credentials. These can be supplied in the KOTS installation UI:

registry credentials UI


Gitpod also has an allow list for private base image registries. Any private image registry that is used throughout an installation needs to be on this allowlist.

Important: Any registry for which credentials are supplied is automatically added to this allowlist!

Registries can be added to the allowlist via the config patch in the following format:

language icon language: 
        - <>
        - <>

Was this helpful?