Private Container Registry Secrets

Specifications for private Docker Container Registry Secrets

Koyeb allows you to easily deploy an app using Docker containers. Koyeb supports the deployment of containers hosted on any Private Docker Registry. This lets you build containers with your continuous delivery pipeline and host them on a secure private registry to protect your intellectual property.

In this guide, we explain how to create secrets containing Private Registries credentials.

Refer to how to deploy containers for generic instructions about app deployment from containers.

The Koyeb registry Secret format

To use a private registry, the Koyeb platform needs to be able to access the registry and you will need to create a secret with the login information for your registry. You will then reference the registry secret when you deploy your Service.

The Secret needs to contain a JSON with the right parameters for your registry:

{ "auths": { "": { "auth": "YOUR_TOKEN" } } }

The string should be replaced by your registry URL. The YOUR_TOKEN string is an authentication string which is the output of echo -n "USERNAME:TOKEN" | base64 where USERNAME and TOKEN should be replaced by your registry credentials.

Refer to the provider specific instruction section if you need help to provide the right credentials.

As a general rule, the Koyeb Secret will contain the same output as the config.json file generated by the docker login command on Linux or on Windows.

The JSON can contain either an auth field (USERNAME:TOKEN in base64) or two fields username and password (without encoding):

{ "auths": { "": { "username": "USERNAME", "password": "PASSWORD" } } }

In both cases, the Secrets will be encrypted server-side by Koyeb.

Provider specific instructions

The Koyeb implementation is compatible with any Docker compatible registry. We provided some details on how to implement it for some major Registry Providers:

Contact us if you need help or if your registry provider is not yet documented!

GitHub Container Registry

We support GitHub Container Registry and not the old GitHub Packages Docker registry. Ensure you are using an URL starting with

Build and push your container

In GitHub, create a Personal access token with the write:packages permission.

Then simply log in, build, and push your container. Do not forget to replace PERSONAL_TOKEN and GITHUB_USERNAME with your own token and GitHub username.

echo PERSONAL_TOKEN | docker login -u GITHUB_USERNAME --password-stdin docker build . --tag docker push

Create the Koyeb Secret

In GitHub, create a Personal access token with the read:packages permission.

Then, in Koyeb, create a Secret called my-registry-secret:

{ "auths": { "": { "username": "USERNAME", "password": "PERSONAL-ACCESS-TOKEN" } } }


Simply generate the auth string with echo -n "USERNAME:TOKEN" | base64

{ "auths": { "": { "auth": "GENERATED_TOKEN" } } }

GCP Container Registry

You will need to create a dedicated service account with a JSON key file.

To generate a valid auth token, simply execute the following command where keyfile.json is the file containing your newly created key:

echo -n "_json_key:$(cat keyfile.json)" | base64

Then, simply use the token in the secret JSON:

{ "auths": { "": { "auth": "GENERATED_TOKEN" } } }