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 configured per service. Each container service can have its own credentials for pulling private images.
1

Select a Service

Click on a container service that uses a private image.
2

Add Credentials

In the Config tab, find the Image section and click “Add registry credentials”. Fill in:
  • Registry URL - The registry hostname
  • Username - Your username or access key
  • Password/Token - Your password or access token
3

Deploy

Deploy. Suga authenticates automatically using the stored credentials.

​
Registry Configuration

RegistryURLUsernamePassword
Docker Hubdocker.ioYour usernameAccess token
GHCRghcr.ioGitHub usernamePersonal access token (read:packages)
GCRgcr.io_json_keyService account JSON key
ECR{account}.dkr.ecr.{region}.amazonaws.comAWSaws ecr get-login-password output
ACR{name}.azurecr.ioRegistry nameAdmin password or SP password
Self-hostedYour registry hostnameYour usernameYour password
ECR tokens expire after 12 hours. For long-running deployments, use BYOC with IAM roles or implement credential rotation.

​
Image Name Format

Always include the full registry in the image name: 
ghcr.io/username/my-app:latest
gcr.io/project-id/my-app:v1.0.0
123456789012.dkr.ecr.us-west-2.amazonaws.com/my-app:latest
yourregistry.azurecr.io/my-app:latest
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:
ghcr.io/username/image:tag  ✓
username/image:tag          ✗ (assumes Docker Hub)
ECR tokens expire after 12 hours. Options:
  • Use BYOC with IAM roles (no token needed)
  • Implement credential rotation
  • Regenerate token and update credentials
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.