Skip to main content

Docker Registry

Pull container images from private registries for your deployments.

Overview​

SailOps supports connecting to private Docker registries, allowing you to deploy containers from:

  • Docker Hub (private repositories)
  • GitHub Container Registry (ghcr.io)
  • GitLab Container Registry
  • AWS ECR
  • Google Container Registry (GCR)
  • Azure Container Registry (ACR)
  • Self-hosted registries

Adding a Registry​

Steps​

  1. Go to your project
  2. Click Settings in the project sidebar
  3. Select the Docker Registry tab
  4. Click Add Registry
  5. Fill in the details:
    • Registry URL: The registry hostname (e.g., docker.io, ghcr.io). It cannot be changed afterwards.
    • Username: Authentication username
    • Password/Token: Authentication secret
    • Email: Optional email for registry authentication
  6. Click Save

The credential is stored immediately and the pull secret appears in your project within seconds. The Status column tracks progress:

StatusMeaning
InstallingStored, being carried to the project
In useActive and available to workloads
Not installedCould not be installed (still retried automatically)
RemovingDeletion in progress

Registry URL Format​

Enter the registry as a hostname or HTTPS URL. SailOps normalizes common variants automatically (e.g. index.docker.io and registry-1.docker.io both resolve to docker.io).

RegistryURL Format
Docker Hubdocker.io
GitHubghcr.io
GitLabregistry.gitlab.com
AWS ECR<account>.dkr.ecr.<region>.amazonaws.com
GCRgcr.io or <region>-docker.pkg.dev
ACR<registry>.azurecr.io
Self-hostedregistry.example.com

Registry Configuration​

Docker Hub​

URL: docker.io
Username: your-docker-username
Password: your-access-token
Access Token

Use a Docker Hub Access Token instead of your password. Create one at hub.docker.com/settings/security.

GitHub Container Registry​

URL: ghcr.io
Username: your-github-username
Password: <your-github-pat>

Create a Personal Access Token with read:packages scope.

GitLab Container Registry​

URL: registry.gitlab.com
Username: your-gitlab-username
Password: <your-gitlab-pat>

Create a Project Access Token with read_registry scope.

AWS ECR​

URL: 123456789.dkr.ecr.eu-west-1.amazonaws.com
Username: AWS
Password: (ECR auth token)
ECR Authentication

AWS ECR tokens expire after 12 hours. SailOps automatically refreshes them when using IAM credentials.

For ECR, you can also use:

  • IAM Access Key + Secret Key
  • IAM Role (for SailOps managed clusters)

Google Container Registry​

URL: gcr.io
Username: _json_key
Password: (service account JSON)

Create a service account with Storage Object Viewer role.

Azure Container Registry​

URL: myregistry.azurecr.io
Username: service-principal-id
Password: service-principal-secret

Create a service principal with AcrPull role.

Using Private Images​

In Container Configuration​

When creating a container, reference your private image:

Image: ghcr.io/myorg/myapp:latest

SailOps automatically uses the matching registry credentials.

Image Pull Priority​

  1. Check project registries for matching URL
  2. Fall back to default credentials (if configured)
  3. Attempt anonymous pull (public images)

Multiple Registries​

You can add multiple registries to a project:

Registry Matching​

SailOps matches registries by URL prefix:

ImageMatched Registry
nginx:latestDocker Hub
ghcr.io/org/app:v1GitHub
registry.internal.company.com/app:v1Private

Managing Registries​

Viewing Registries​

  1. Go to Settings in the project sidebar
  2. Select the Docker Registry tab
  3. See all configured registries and their connection status

Testing Connection​

There are two ways to test credentials:

Test while adding or editing​

  1. Open the Add Registry or Edit modal
  2. Fill in the registry URL, username and password
  3. Optionally enter an Image to test (e.g. ghcr.io/team/app:1.0). The image must be on the same registry as the credential. When given, SailOps asks the registry for that image's manifest to prove the credential can pull it.
  4. Click Test Connection

Test a saved credential​

  1. Click Test on the credential row
  2. Optionally enter an image reference to check
  3. Click Run test

The saved password is used directly — you do not need to enter it again.

Test results​

Both tests report:

  • Provider detection (Docker Hub, GitHub, GitLab, or generic)
  • Authentication status against the registry endpoint
  • Scope verification for GitHub and GitLab tokens (checks for read:packages and read_registry respectively)
  • Missing scopes if the token lacks required read permissions

When an image is given, two additional outcomes are possible:

  • Image not found — the credentials work but the registry has no such tag or digest
  • Image forbidden — the credentials work but cannot pull this image (it does not exist, or the account was not granted access)
Image test

Testing with an image works on any registry. Without an image, only GitHub and GitLab tokens can have their permissions checked beyond basic authentication.

Scope Check

For GitHub and GitLab registries, SailOps verifies that your token has the scopes needed to pull images. If scopes are missing, the test result lists them so you can update the token.

Updating Credentials​

  1. Click Edit on the registry
  2. Update the username, password/token, or email
  3. Click Save

The registry a credential authenticates to cannot be changed. To switch registries, remove the credential and add a new one.

Credential Rotation

When rotating credentials, update them in SailOps before revoking old ones to avoid deployment failures.

Removing a Registry​

  1. Click Delete on the registry
  2. Confirm removal

The credential enters the Removing status while the pull secret is cleaned up from the project. Once complete, the credential disappears from the list and the registry becomes available for a new credential.

Active Containers

Ensure no running containers use images from this registry before removing. A running workload keeps the image it already pulled, but cannot pull again after the credential is gone.

Security Best Practices​

1. Use Access Tokens​

Never use account passwords:

✓ Docker Hub Access Tokens
✓ GitHub Personal Access Tokens
✓ GitLab Project Access Tokens

✗ Account passwords

2. Minimal Permissions​

Grant only required permissions:

RegistryMinimum Scope
Docker HubRead-only access token
GitHubread:packages
GitLabread_registry
AWS ECRecr:GetAuthorizationToken, ecr:BatchGetImage

3. Separate Credentials per Environment​

Production Project → Production registry credentials
Staging Project → Staging registry credentials

4. Regular Rotation​

Rotate credentials periodically:

  • Every 90 days for standard use
  • Immediately after team member departure
  • After any security incident

Troubleshooting​

Image Pull Errors​

Error: ImagePullBackOff

  1. Verify registry URL matches image
  2. Check credentials are valid
  3. Test connection in settings

Error: unauthorized: authentication required

  1. Update registry password/token
  2. Ensure token has required scopes
  3. Check token hasn't expired

Error: manifest unknown

  1. Verify image tag exists
  2. Check image architecture (amd64 required)
  3. Ensure image is pushed to registry

ECR Token Expired​

For AWS ECR:

  1. Verify IAM credentials are valid
  2. Check IAM permissions include ECR access
  3. SailOps auto-refreshes tokens

Rate Limiting​

Docker Hub has rate limits:

  • Anonymous: 100 pulls/6 hours
  • Authenticated: 200 pulls/6 hours
  • Paid: Unlimited

Solutions:

  1. Add Docker Hub credentials
  2. Mirror images to private registry
  3. Upgrade Docker Hub plan