Docker Registry

This document covers the guide to integrating your docker registry with TrueFoundry to let you build and use the docker image from those registries. Docker Registries are used in two ways:

  • you can use the Docker registry to save images built during the deployment of code or repository
  • you can deploy any images from the repository to one of your connected workspaces

We support commonly used docker registries listed below:

  1. AWS ECR
  2. Google Artifact registry
  3. Azure Container registry
  4. DockerHub registry
  5. Quay registry

We also support most docker registries that use the standard username-password flows.

Add Docker Registry to TrueFoundry

To add a new docker registry, one needs to follow the following steps:

  1. Navigate to the Integrations section of your TrueFoundry dashboard, and go to the Docker Registry section.
  2. Click on the Connect Registry button at the top right corner.
  3. Now add the name of the registry you want to connect. Select the registry type.
  4. Now add the credentials for these registries. The format expected by the registry URL and permissions required for the credentials for each type of registry can be checked by clicking on the information next to the field.
Docker Hub Registry

Docker Hub Registry

AWS ECR Registry

AWS ECR Registry

Google Container Registry

Google Artifact Registry

Setting default Docker Registry for cluster

You can specify the default registry per cluster. To do this, go to Integrations > Clusters and click on Edit for the cluster you want to add default registry for.

Edit Cluster Form to add default registry

Edit Cluster Form to add default registry

In the form, choose the default registry for the cluster. When no registry is specified for deployment, the cluster default will be automatically used to store the built image.

Choose a default registry for the cluster from the form

Choose a default registry for the cluster from the form

Setting default Docker registry for organization

If you do not choose a registry for your deployment and there is no default cluster registry, the tenant default will be used. All tenants must have a default registry. If you only have one registry added, it will automatically be the tenant default and will be used for all builds.


  1. You might have the IAM role for truefoundry already created with the name - tfy-<short-region-name>-<name>-platform-role-<xxxyyyzzz>, if not create a new one. You can add the following permission to that role. You can also create a user with the permissions below, generate an access key and secret key and integrate the docker registry via the access and secret keys.
    "Sid": "ECR",
    "Effect": "Allow",
    "Action": [
    "Resource": [
    "Sid": "ECR",
    "Effect": "Allow",
    "Action": [
    "Resource": [
  1. Navigate to Integrations > Docker registry and click on Connect Registry
  2. Fill in the IAM role with the right registry URL in the form. Click here to check your Registry URL. It will be of the form

Add Google Artifact Registry

  1. Create an IAM serviceaccount named tfy-<short-region>-<name>-platform-role, if not created before. Attach the IAM role with the following permissions:
    1. Artifact Registry Administrator
    2. Service Account Token Creator
  2. Once the IAM serviceaccount is created, make sure to create a key in JSON format.
  3. Navigate to Integrations > Docker registry and click on Connect Registry. Paste the GCP service account keyfile.json and Submit.

Add Azure Container Registry

To add Azure Container registry, follow the steps below:

  1. Create an Azure container registry in your Azure resource group.

    1. Connectivity access - Public from (all networks)
  2. Collect the following information

    1. Your container registry name will be <name>
    2. The username and password for the container registry can be copied from Access keys under Settings in the left panel of the Azure portal in your container registry resource.
      1. Enable the Admin User to copy the username and the password
  3. Head over to the Docker Registry section in the Integrations tab from the left panel.

    1. Click on + Connect Registry and select Azure
    2. Add the Azure registry URL along with the username and the password

Add DockerHub registry

Add Quay registry

  1. Navigate to the organisation account. If you don't have one, please create at

  2. To create a robot account, go to the organisation settings page, look for the Robot Accounts section, and click on Create Robot Account. Give your robot account a meaningful name.

  3. Within your organisation's settings, navigate to the Teams and Membership section and create a new team or select an existing one. Add the robot account to this team and assign the Admin or Creator role to ensure it has the required access levels.

  4. Navigate to Integrations > Docker Registryand add the registry. The registry URL should be<name-of-org>, the username and the password are the credentials copied from the robot account you created

Using a secret as credential while linking Docker Registry

You can reference a secret stored in one of your secret store backends (AWS SSM Parameter Store or Google Secrets Manager) while creating a Docker Registry integration.

For example, to use a key with the name parameter-store-key stored in AWS SSM Parameter Store, you'll first need to link the Secret Store to TrueFoundry. You can read more about linking secret store here.

Once it's linked you can reference the secret in the Docker Registry form as <secret-store-fqn>::<key-in-secret-store>. It will look something like secret-store:your-org:ssm-eu-west::parameter-store-key.

What’s Next