# Use custom build registry

A custom build registry stores your project's build images in your cloud account. Northflank supports Amazon Elastic Container Registry (ECR), Google Artifact Registry, and Azure Container Registry.

Select the registry when you create a project. You can use this feature without a BYOC cluster.

To deploy existing images from an external registry, use [registry credentials](https://northflank.com/docs/v1/application/run/save-registry-credentials). Saving credentials alone does not change where Northflank stores your builds.

## Prerequisites

Before you configure a custom build registry, you need:

- An ECR registry, Google Artifact Registry repository, or Azure Container Registry in your cloud account.

- A [cloud integration](https://northflank.com/docs/v1/application/bring-your-own-cloud/use-other-cloud-providers-with-northflank) with Docker Registries and Docker Registry Push selected, and the corresponding cloud permissions.

- Saved registry credentials with Push access (write images) enabled and access permitted for the new project.

You can select a build registry only when you create a project. You cannot change this selection on an existing project.

If the registry controls are unavailable for your account, contact Northflank support about feature availability.

## How it works

When your project uses a custom build registry:

1. Northflank builds your code with your configured build method.

2. Northflank pushes the resulting image to the project's selected registry.

3. Deployments that use the build pull the image from that registry.

Keep the registry and its credentials available for future builds and deployments. The project registry selection does not change the source of external images that you deploy.

## Add a custom Docker registry

If you need a cloud integration, follow the [provider setup instructions](https://northflank.com/docs/v1/application/run/save-registry-credentials#cloud-provider-registries) first.

> [!note]
>
> [Click here](https://app.northflank.com/s/account/integrations/registry-credentials/new) to add a custom Docker registry.

1. Open Integrations → Registries in your team account.

2. If this is your first registry, select Add registry integration. Otherwise, select Add registry.

3. Enter a name and select Elastic Container Registry, Google Artifact Registry, or Azure Container Registry.

4. Select a cloud integration with registry pull and push permissions.

5. Enter the registry URL and the additional values for your provider, as shown below.

6. Enable Push access (write images).

7. Select Add registry.

| Provider | Registry URL example | Additional field |
| --- | --- | --- |
| ECR | `123456789012.dkr.ecr.eu-west-1.amazonaws.com` | Region: `eu-west-1` |
| ECR in AWS European Sovereign Cloud | `123456789012.dkr.ecr.eusc-de-east-1.amazonaws.eu` | Region: `eusc-de-east-1` |
| Google Artifact Registry | `europe-west3-docker.pkg.dev/example-project/builds` | Project ID: `example-project` |
| Azure Container Registry | `exampleregistry.azurecr.io` | Resource Group: `example-rg` |

Use your own registry values. The Google Artifact Registry URL includes both the Google project ID and the repository name, `builds` in this example.

For ECR, the region must match the registry URL. A sovereign registry requires an [AWS European Sovereign Cloud integration](https://northflank.com/docs/v1/application/bring-your-own-cloud/aws-on-northflank#aws-european-sovereign-cloud).

If the integration or registry is missing from a selector, see [registry troubleshooting](https://northflank.com/docs/v1/application/run/save-registry-credentials#registry-troubleshooting).

## Use in a project

> [!warning] Choose the registry at project creation
>
> Select the registry when you create the project. You cannot change this selection on an existing project.

The PaaS mode uses Northflank's managed registry. The Self-hosted mode uses the registry linked through your selected credentials.

> [!note]
>
> [Click here](https://app.northflank.com/s/account/projects/new) to create a new project.

1. Select Create project on your team dashboard.

2. Expand Advanced options and find Docker registry settings.

3. Set Registry mode to Self-hosted.

4. Select your saved credentials under Registry.

5. Complete the project configuration and select Create project.

Your organization or team can disable the managed registry. In that case, you must select a supported registry with push access before you create a project. A team cannot override an organization restriction.

To view an existing project's registry, open the project's Settings page. Find the Docker registry settings section. These controls are read-only.

## Next steps

- [Build from a Git repository: Start building from your linked Git repositories in minutes.](/v1/application/build/build-code-from-a-git-repository)
- [Inject build arguments: Pass secrets and configuration settings to your builds.](/v1/application/build/inject-build-arguments)
- [Run an image continuously: Deploy a built image as a continuously-running service.](/v1/application/run/run-an-image-continuously)
- [Run an image once or on a schedule: Run an image manually or on a cron schedule.](/v1/application/run/run-an-image-once-or-on-a-schedule)