# Save registry credentials

Save registry credentials to pull private images into services and jobs. Open Integrations → Registries in your team account to add or manage credentials.

For ECR, Google Artifact Registry, and Azure Container Registry, select a cloud integration to authenticate. For other registries, enter a username and password or access token.

You can restrict credentials to selected projects. Under Advanced options, enable Restrict usage to specific projects. Select the projects that can use the credentials.

Supported credentials with push access can also provide a [custom build registry](https://northflank.com/docs/v1/application/build/use-custom-build-registry) for a new project. Saving credentials does not select the project's build destination.

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

## Container registries

### DockerHub (registry.hub.docker.com)

Enter your Docker Hub username and password, or use a [personal access token](https://docs.docker.com/security/access-tokens/personal-access-tokens/) with read access. If your account uses two-factor authentication, use a token.

### Cloud provider registries

Use a cloud integration to connect ECR, Google Artifact Registry, or Azure Container Registry. Select Docker Registries in the integration and grant the corresponding cloud permissions.

| Registry | Cloud integration setup |
| --- | --- |
| Elastic Container Registry | [AWS cross-account role](https://northflank.com/docs/v1/application/bring-your-own-cloud/aws-on-northflank#add-your-account-with-a-cross-account-role) or [IAM user](https://northflank.com/docs/v1/application/bring-your-own-cloud/aws-on-northflank#add-your-account-with-an-iam-user) |
| Google Artifact Registry | [GCP cross-project service account](https://northflank.com/docs/v1/application/bring-your-own-cloud/gcp-on-northflank#add-your-account-with-a-cross-project-service-account) or [service key](https://northflank.com/docs/v1/application/bring-your-own-cloud/gcp-on-northflank#add-your-account-with-a-service-key) |
| Azure Container Registry | [Azure application](https://northflank.com/docs/v1/application/bring-your-own-cloud/azure-on-northflank#add-your-azure-account) |

In the registry form, select your provider and integration. Enter the registry URL and its region, Google project ID, or Azure resource group.

To use these credentials for project builds, also select Docker Registry Push in the integration. Grant the required cloud permissions, then enable Push access (write images) in the registry form.

See [add a custom Docker registry](https://northflank.com/docs/v1/application/build/use-custom-build-registry#add-a-custom-docker-registry) for URL examples and project setup.

### GitHub Container Registry (ghcr.io)

Enter your GitHub username and a personal access token (classic) with the `read:packages` permission. Create the token under Developer settings in your GitHub account. See [GitHub's registry authentication guide](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry) for package access requirements.

### GitLab (registry.gitlab.com)

Enter your GitLab username and a [personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) with the `read_registry` permission. See [GitLab's registry authentication guide](https://docs.gitlab.com/user/packages/container_registry/authenticate_with_container_registry/) for details.

For a self-hosted GitLab instance, use its registry domain for both saved credentials and image paths.

### Custom registries

For another registry, select Custom container registry and enter its URL, username, and password or token. Use this option for a self-hosted GitLab registry with its own domain.

### Registry troubleshooting

| Problem | Action |
| --- | --- |
| Cloud integration is missing | Make sure that the integration supports your registry provider and includes Docker Registries. For a shared integration, your team must have access. |
| Push access is unavailable | Add Docker Registry Push to the cloud integration and grant its required permissions. |
| Registry is missing during project creation | Use a supported registry with push access. New projects cannot select credentials restricted to existing projects. Review restrictions with your administrator before changing access. |
| Automatic credential refresh suspended | Open the saved registry credentials and read the error. Fix the integration credentials or permissions, then select Retry credential refresh. |

## Authenticate with JSON

The registry form accepts a username and password or token. It does not accept a complete Docker `config.json` file.

If you already use Docker credentials, enter the original username and password or token in the registry form. Do not enter the Base64-encoded `auth` value as the password.

For API requests, send credentials as JSON to `POST /v1/integrations/registries`. For example:

```json
{
  "name": "example-registry",
  "provider": "custom",
  "registryUrl": "https://registry.example.com",
  "credentials": {
    "username": "example-user",
    "password": "your-password-or-token",
    "scope": {
      "pull": true,
      "push": false
    }
  }
}
```

Replace the example values with your registry credentials. For cloud registries, follow the [cloud integration instructions](#cloud-provider-registries).

## Next steps

- [Run from a container registry: Deploy an image from a container registry.](/v1/application/run/run-an-image-from-a-container-registry)
- [Set up a pipeline and release flow: Manage your deployments and release your updates in an intuitive pipeline with release flows.](/v1/application/release/pipeline/create-a-pipeline-and-release-flow)
- [Scale your services: Increase the resources available to your services, and the number of instances to deploy.](/v1/application/scale/scale-on-northflank)
- [Add databases and persistent storage: Create and use databases and other types of persistent storage in your project's applications and services.](/v1/application/databases-and-persistence/stateful-workloads-on-northflank)