Documentation

Container Registry Configuration

Configure custom container registries for all your deployments across GitHub, GitLab, Azure DevOps, and Bitbucket

Overview

NebuaCloud supports flexible container registry configuration for all your deployments. You can choose between:

Provider Defaults - Automatic, provider-specific registries (GHCR, ACR, GitLab Registry)
Custom Registry - Use Docker Hub, AWS ECR, Google GCR, Azure ACR, or any OCI-compliant registry for ALL git providers

Provider Default Registries

When no custom registry is configured, NebuaCloud uses provider-specific defaults:

GitHub → GitHub Container Registry (GHCR)

Registry: ghcr.io
Authentication: OAuth token (requires write:packages scope)
Image format: ghcr.io/username/repo-service:tag
Setup: Ensure your GitHub OAuth connection has package write permissions

Azure DevOps → Azure Container Registry (ACR)

Registry: <organization>.azurecr.io (auto-detected from organization name)
Authentication: OAuth token
Image format: <organization>.azurecr.io/repo-service:tag

One-time Setup Required:

# Create ACR (name must match your Azure DevOps organization)
az acr create --resource-group myResourceGroup \
  --name <organization-name> \
  --sku Basic

# Grant yourself push access
az role assignment create \
  --assignee <your-email@example.com> \
  --role AcrPush \
  --scope /subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/<organization-name>

GitLab → GitLab Container Registry

Registry: registry.gitlab.com
Authentication: OAuth token
Image format: registry.gitlab.com/namespace/project/repo-service:tag
Setup: OAuth connection provides automatic access

Bitbucket

No default registry - You must configure a custom registry
Bitbucket doesn't provide a native container registry

Custom Registry Configuration

Accessing Registry Settings

Navigate to Organization Overview page
Click the "Container Registry" tab
Select your registry provider and enter credentials
Click Save Settings

Once configured, ALL deployments from that organization will use your custom registry, regardless of the git provider.

Supported Registry Providers

Docker Hub

Best for: Personal projects, small teams, multi-provider deployments

Provider: Docker Hub
Host: docker.io (auto-filled)
Username: <your-dockerhub-username>
Password: <access-token>

Setup Instructions:

Go to Docker Hub Security Settings
Click "New Access Token"
Name: NebuaCloud, Permissions: Read, Write, Delete
Copy the token and paste in the password field

Pricing:

Free: 1 private repository, unlimited public
Pro: $5/month - unlimited private repositories

Image format: docker.io/username/repo-service:tag

AWS Elastic Container Registry (ECR)

Best for: AWS-hosted applications, enterprise deployments

Provider: AWS ECR
Host: <account-id>.dkr.ecr.<region>.amazonaws.com
Username: AWS
Password: <token from aws ecr get-login-password>

Setup Instructions:

# Create ECR repository
aws ecr create-repository --repository-name nebuacloud-apps

# Get authentication token (valid for 12 hours)
aws ecr get-login-password --region us-east-1

Important Notes:

ECR tokens expire after 12 hours
For long-term use, consider using IAM roles or refresh tokens regularly
Ensure your IAM user has ecr:PutImage and ecr:GetAuthorizationToken permissions

Pricing: $0.10/GB/month stored

Image format: <account-id>.dkr.ecr.<region>.amazonaws.com/repo-service:tag

Google Container Registry (GCR)

Best for: GCP-hosted applications

Provider: Google GCR
Host: gcr.io (or us.gcr.io, eu.gcr.io, asia.gcr.io)
Username: _json_key
Password: <entire service account JSON key>

Setup Instructions:

Go to GCP Service Accounts
Create a service account with "Storage Admin" role
Create and download a JSON key
Paste the entire JSON content as the password

Pricing: $0.026/GB/month stored

Image format: gcr.io/project-id/repo-service:tag

Azure Container Registry (ACR)

Best for: Azure-hosted applications, custom ACR configurations

Provider: Azure ACR
Host: <registry-name>.azurecr.io
Username: <admin-username or service-principal-id>
Password: <admin-password or service-principal-secret>

Setup with Admin Credentials:

# Enable admin user
az acr update --name myregistry --admin-enabled true

# Get credentials
az acr credential show --name myregistry

Setup with Service Principal (Recommended):

# Create service principal with AcrPush role
az ad sp create-for-rbac \
  --name nebuacloud-acr-push \
  --role AcrPush \
  --scopes /subscriptions/<subscription-id>/resourceGroups/myResourceGroup/providers/Microsoft.ContainerRegistry/registries/myregistry

# Output provides:
# - appId: Use as username
# - password: Use as password

Pricing:

Basic: $5/month
Standard: $20/month
Premium: $50/month

Image format: <registry-name>.azurecr.io/repo-service:tag

GitHub Container Registry (GHCR)

Best for: Public open-source projects, GitHub-centric workflows

Provider: GitHub GHCR
Host: ghcr.io (auto-filled)
Username: <github-username>
Password: <personal-access-token>

Setup Instructions:

Go to GitHub Personal Access Tokens
Create a new token
Select scopes: write:packages, read:packages
Copy the token

Pricing:

Free: 500MB storage
Beyond free tier: $0.25/GB/month

Image format: ghcr.io/username/repo-service:tag

GitLab Container Registry

Best for: GitLab-centric workflows, CI/CD integration

Provider: GitLab
Host: registry.gitlab.com (auto-filled)
Username: <gitlab-username or oauth2>
Password: <personal-access-token>

Setup Instructions:

Go to GitLab Access Tokens
Create a token with write_registry scope
Use your GitLab username or oauth2 as the username
Copy the token as password

Pricing: Included with GitLab plan

Image format: registry.gitlab.com/namespace/project/repo-service:tag

Custom / Self-Hosted Registry

Best for: Harbor, Artifactory, Nexus, or any OCI-compliant registry

Provider: Custom
Host: registry.example.com
Username: <username>
Password: <password or token>

Use this option for:

Harbor
JFrog Artifactory
Sonatype Nexus
Private Docker Registry
Any OCI-compliant registry

Decision Guide

✅ Use Provider Defaults When:

Deploying from a single git provider only
You want minimal setup and configuration
OAuth tokens have required registry permissions
You don't mind images spread across multiple registries

✅ Use Custom Registry When:

Deploying from multiple git providers
You want all container images in one central location
Using Bitbucket (required - no default registry)
You need advanced features (vulnerability scanning, geo-replication)
Corporate policy mandates a specific registry provider
You want consistent image lifecycle management

Common Use Cases

Personal Developer / Small Team

Recommendation: Use provider defaults or Docker Hub

Why:

Free tier sufficient for most needs
Easy setup with OAuth
No infrastructure to manage

Example Configuration:

GitHub repos → GHCR (automatic)
Docker Hub for Bitbucket repos

Startup / Multi-Cloud

Recommendation: Docker Hub or cloud-agnostic registry

Why:

All images in one place
Easy to switch cloud providers
Cost-effective

Example Configuration:

Provider: Docker Hub
All providers (GitHub, GitLab, Azure, Bitbucket) → docker.io/company/*

Enterprise on AWS

Recommendation: AWS ECR

Why:

Same region as workloads (fast pulls)
Integrated with AWS IAM
Vulnerability scanning included
VPC endpoints for private networking

Example Configuration:

Provider: AWS ECR
All providers → 123456789.dkr.ecr.us-east-1.amazonaws.com/*

Enterprise on Azure

Recommendation: Azure ACR (via custom configuration)

Why:

Geo-replication
Azure AD integration
Webhooks and Tasks support

Example Configuration:

Provider: Azure ACR
Host: company.azurecr.io
All providers → company.azurecr.io/*

Enterprise on GCP

Recommendation: Google GCR or Artifact Registry

Why:

Regional/multi-regional storage
IAM integration
Fast pulls within GCP

Troubleshooting

"unauthorized: authentication required"

For Provider Defaults:

Reconnect OAuth for the git provider
For GitHub: Ensure write:packages scope is granted
For Azure: Verify AcrPush role assignment

For Custom Registry:

Verify credentials in Organization Settings → Container Registry tab
For ECR: Refresh token (expires after 12 hours)
For GCR: Ensure service account has Storage Admin role

"denied: insufficient permissions"

Solutions:

GHCR: Ensure personal access token has write:packages scope
ACR: Ensure user has AcrPush or AcrImageSigner role
ECR: Ensure IAM user has ecr:PutImage and ecr:InitiateLayerUpload permissions
GCR: Ensure service account has Storage Admin or Storage Object Creator role

Images not appearing in registry

Check:

Registry configuration in Organization Settings
Deployment logs for push success/failure
Registry exists and is accessible
Network connectivity to registry

Cost concerns

Free Options:

Docker Hub: 1 private repository
GitLab Registry: Included with GitLab
Provider defaults: Usually included

Low-Cost Options:

AWS ECR: Pay per GB ($0.10/GB/month)
Google GCR: Pay per GB ($0.026/GB/month)
Azure ACR Basic: $5/month

Best Practices

1. Use Provider Defaults for Single-Provider Deployments

If you only deploy from GitHub, use GHCR. If only Azure, use ACR auto-detection.

2. Configure Custom Registry for Multi-Provider

For teams using GitHub + Bitbucket + Azure, configure Docker Hub or cloud registry.

3. Use Cloud-Native Registries for Production

AWS workloads → ECR
Azure workloads → ACR
GCP workloads → GCR

4. Implement Image Scanning

Most cloud registries provide vulnerability scanning. Enable it for production images.

5. Use Service Principals for Production

Avoid using personal credentials. Use service accounts or service principals with minimal required permissions.

6. Set Up Image Retention Policies

Configure automatic cleanup of old images to reduce storage costs.

7. Use Private Registries for Sensitive Code

Never push proprietary code to public registries.

Image Naming Convention

NebuaCloud automatically generates image names using this pattern:

<registry-host>/<repository>-<service-hash>:<tag>

Examples:

Docker Hub:

docker.io/myusername/flowster-webdesigner-abc123:abc123

AWS ECR:

123456789.dkr.ecr.us-east-1.amazonaws.com/myrepo-abc123:abc123

Azure ACR:

myregistry.azurecr.io/myrepo-abc123:abc123

GHCR:

ghcr.io/username/myrepo-abc123:abc123

Registry Comparison

| Registry | Free Tier | Paid | Best For | Vulnerability Scanning | |----------|-----------|------|----------|----------------------| | Docker Hub | 1 private repo | $5/mo unlimited | Personal, multi-provider | ❌ (Pro plan only) | | AWS ECR | 500MB/month | $0.10/GB/mo | AWS workloads | ✅ Free | | Google GCR | 5GB/month | $0.026/GB/mo | GCP workloads | ✅ Paid | | Azure ACR | ❌ | $5-50/mo | Azure workloads | ✅ Premium only | | GHCR | 500MB | $0.25/GB/mo | Open source | ❌ | | GitLab | ✅ Included | Included | GitLab users | ✅ Ultimate only |

Security Considerations

1. Never Commit Registry Credentials

Store credentials in NebuaCloud organization settings, not in git repositories.

2. Use Short-Lived Tokens

ECR: Tokens expire in 12 hours (good)
Others: Rotate tokens every 90 days

3. Implement Least Privilege

Only grant the minimum permissions needed (e.g., AcrPush not Owner).

4. Enable Multi-Factor Authentication

Protect your registry accounts with MFA.

5. Monitor Registry Access

Enable audit logging for registry access and pushes.

Advanced Scenarios

Scenario 1: Disaster Recovery

Configure secondary registry in different region/cloud:

Primary: AWS ECR us-east-1
Secondary: Azure ACR westeurope
Use CI/CD to mirror images

Scenario 2: Air-Gapped Environments

Use Harbor or Artifactory for offline deployments with image replication.

Scenario 3: Compliance Requirements

For regulated industries:

Use region-specific registries (EU data stays in EU)
Enable immutable tags
Implement image signing

Need Help?

Provider Defaults Not Working: Reconnect OAuth for your git provider
Custom Registry Issues: Verify credentials in Organization Settings
Bitbucket Users: You must configure a custom registry
Enterprise Support: Contact support@nebuacloud.com

Last updated: April 2026

Overview

Provider Default Registries

GitHub → GitHub Container Registry (GHCR)

Azure DevOps → Azure Container Registry (ACR)

GitLab → GitLab Container Registry

Bitbucket

Custom Registry Configuration

Accessing Registry Settings

Supported Registry Providers

Docker Hub

AWS Elastic Container Registry (ECR)

Google Container Registry (GCR)

Azure Container Registry (ACR)

GitHub Container Registry (GHCR)

GitLab Container Registry

Custom / Self-Hosted Registry

Decision Guide

✅ Use Provider Defaults When:

✅ Use Custom Registry When:

Common Use Cases

Personal Developer / Small Team

Startup / Multi-Cloud

Enterprise on AWS

Enterprise on Azure

Enterprise on GCP

Troubleshooting

"unauthorized: authentication required"

"denied: insufficient permissions"

Images not appearing in registry

Cost concerns

Best Practices

1. Use Provider Defaults for Single-Provider Deployments

2. Configure Custom Registry for Multi-Provider

3. Use Cloud-Native Registries for Production

4. Implement Image Scanning

5. Use Service Principals for Production

6. Set Up Image Retention Policies

7. Use Private Registries for Sensitive Code

Image Naming Convention

Examples:

Registry Comparison

Security Considerations

1. Never Commit Registry Credentials

2. Use Short-Lived Tokens

3. Implement Least Privilege

4. Enable Multi-Factor Authentication

5. Monitor Registry Access

Advanced Scenarios

Scenario 1: Disaster Recovery

Scenario 2: Air-Gapped Environments

Scenario 3: Compliance Requirements

Related Documentation

Need Help?