Deploy
Private registry
Projects with OCI image source can use public or private images. Private images require credentials so the platform can pull the artifact during project creation or update.
Authentication options
The current documentation covers two models:
| Model | When to use |
|---|---|
| AWS ECR | When the image is in an ECR registry |
| User and token/password | When the registry accepts basic authentication or access tokens |
The authentication type is defined during project creation and is not available for editing later.
Create a project with a private image
In the console:
- choose OCI Image as source
- enter the full image URL
- mark the image as private
- choose the authentication type
- enter the requested credentials
- configure port, variables, plan, and instances
- create the project and follow the logs
If image download fails, review registry, tag, permissions, and credentials.
Best practices
- use a token with minimum pull scope
- avoid personal credentials when a service credential exists
- use immutable tags in production
- rotate tokens when someone leaves the team
- keep the same authentication strategy for future project updates
Troubleshooting
| Symptom | What to review |
|---|---|
| Failed to pull image | URL, tag, registry, and credentials |
| Image not found | namespace, repository name, and tag |
| Access denied | token scope and pull permission |
| App starts and crashes | port, image default command, and variables |
Next steps
FAQ
Can I switch a private image to public?
This change is not guaranteed after creation. Plan the source and authentication type before creating the project.
Can I use AWS ECR?
Yes. Private images can use AWS ECR authentication when ECR is the source registry.
Does the token go in code?
No. Registry credentials must be entered in the console and never versioned in the repository.