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
- Go to your project
- Click Settings in the project sidebar
- Select the Docker Registry tab
- Click Add Registry
- 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
- Registry URL: The registry hostname (e.g.,
- Click Save
The credential is stored immediately and the pull secret appears in your project within seconds. The Status column tracks progress:
| Status | Meaning |
|---|---|
| Installing | Stored, being carried to the project |
| In use | Active and available to workloads |
| Not installed | Could not be installed (still retried automatically) |
| Removing | Deletion 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).
| Registry | URL Format |
|---|---|
| Docker Hub | docker.io |
| GitHub | ghcr.io |
| GitLab | registry.gitlab.com |
| AWS ECR | <account>.dkr.ecr.<region>.amazonaws.com |
| GCR | gcr.io or <region>-docker.pkg.dev |
| ACR | <registry>.azurecr.io |
| Self-hosted | registry.example.com |
Registry Configuration
Docker Hub
URL: docker.io
Username: your-docker-username
Password: your-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)
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
- Check project registries for matching URL
- Fall back to default credentials (if configured)
- Attempt anonymous pull (public images)
Multiple Registries
You can add multiple registries to a project:
Registry Matching
SailOps matches registries by URL prefix:
| Image | Matched Registry |
|---|---|
nginx:latest | Docker Hub |
ghcr.io/org/app:v1 | GitHub |
registry.internal.company.com/app:v1 | Private |
Managing Registries
Viewing Registries
- Go to Settings in the project sidebar
- Select the Docker Registry tab
- See all configured registries and their connection status
Testing Connection
There are two ways to test credentials:
Test while adding or editing
- Open the Add Registry or Edit modal
- Fill in the registry URL, username and password
- 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. - Click Test Connection
Test a saved credential
- Click Test on the credential row
- Optionally enter an image reference to check
- 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:packagesandread_registryrespectively) - 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)
Testing with an image works on any registry. Without an image, only GitHub and GitLab tokens can have their permissions checked beyond basic authentication.
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
- Click Edit on the registry
- Update the username, password/token, or email
- Click Save
The registry a credential authenticates to cannot be changed. To switch registries, remove the credential and add a new one.
When rotating credentials, update them in SailOps before revoking old ones to avoid deployment failures.
Removing a Registry
- Click Delete on the registry
- 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.
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:
| Registry | Minimum Scope |
|---|---|
| Docker Hub | Read-only access token |
| GitHub | read:packages |
| GitLab | read_registry |
| AWS ECR | ecr: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
- Verify registry URL matches image
- Check credentials are valid
- Test connection in settings
Error: unauthorized: authentication required
- Update registry password/token
- Ensure token has required scopes
- Check token hasn't expired
Error: manifest unknown
- Verify image tag exists
- Check image architecture (amd64 required)
- Ensure image is pushed to registry
ECR Token Expired
For AWS ECR:
- Verify IAM credentials are valid
- Check IAM permissions include ECR access
- SailOps auto-refreshes tokens
Rate Limiting
Docker Hub has rate limits:
- Anonymous: 100 pulls/6 hours
- Authenticated: 200 pulls/6 hours
- Paid: Unlimited
Solutions:
- Add Docker Hub credentials
- Mirror images to private registry
- Upgrade Docker Hub plan