Skip to main content
This guide explains how to use Docker images from private registries on Suga.

​
Supported Registries

  • Docker Hub - Private repositories
  • GitHub Container Registry (GHCR) - ghcr.io
  • Google Container Registry (GCR) - gcr.io and Artifact Registry
  • Amazon ECR - Elastic Container Registry
  • Azure Container Registry (ACR)
  • Self-hosted - Harbor, GitLab, Nexus, etc.

​
Adding Registry Credentials

Registry credentials are stored per environment, keyed by registry hostname. Enter them once for a registry and every service in that environment pulling from the same host can use them. Environments do not share credentials, so staging and production each need their own.
1

Open the Container Dialog

Open the Add palette and choose Service from Container, or select an existing service and open its Config tab.
2

Enter the Image URI

Enter the full image reference, including the registry host, for example ghcr.io/username/my-app:v1.2.3. Suga reads the registry host from this, so there is no separate registry field.
3

Add Credentials

Expand Registry credentials and fill in:
  • Username - Your username or access key
  • Password - Your password or access token
4

Apply

Click Apply. Suga authenticates automatically using the stored credentials.

​
Registry Configuration

ECR tokens expire after 12 hours. Suga only supports username and password credentials, so there is no way to have it fetch a fresh ECR token for you. Update the password before it expires, or push your images to a registry with long-lived tokens, such as GHCR.

​
Image Name Format

Always include the full registry in the image name:
Omitting the registry prefix (e.g., username/my-app) assumes Docker Hub.

​
Image Pull Behavior

Suga always pulls the latest version of an image on each deployment. This ensures you get the most recent version even when using the same tag.
Using :latest in production is not recommended. Use specific version tags (e.g., v1.2.3) for reproducible deployments.

​
Troubleshooting

Check:
  • Registry URL format is correct
  • Credentials haven’t expired
  • Image name and tag exist
  • Token has read permissions
Test locally: docker login registry-url && docker pull image:tag
Use full image name including registry:
ECR tokens expire after 12 hours. Regenerate the token with aws ecr get-login-password and update the password on the container. If you redeploy often, copy your images to a registry with long-lived tokens instead.
Docker Hub limits: 100 pulls/6h (anonymous), 200 pulls/6h (authenticated)Solutions:
  • Add Docker Hub credentials (increases to 200)
  • Use GHCR, GCR, or other registry
  • Upgrade to Docker Hub Pro

​
Security Best Practices

Grant only read permissions:
  • Docker Hub: Read-only access token
  • GitHub: read:packages scope
  • GCR: “Storage Object Viewer” role
  • ECR: AmazonEC2ContainerRegistryReadOnly
  • ACR: AcrPull role
Rotate every 90 days, after team member departure, or after suspected compromise.
Use myapp:v1.2.3 instead of myapp:latest for reproducible deployments.