Skip to main content

How to use a private container registry

See also

Divio allows you to use container images from private registries by securely storing access credentials and authenticating during the build process.

Follow these steps to integrate a private registry into your Divio project.

Step 1: Add container registry credentials​

  1. In the Divio Control Panel, go to
    Organisation > Container Registries from the left-hand menu.
  2. Click Add Credentials.
  3. Fill in the following:
    • Server – for example: registry.gitlab.com or ghcr.io
    • Username – your registry username
    • Password – or a personal access token (PAT)
  4. Click Add to save the credentials.

Step 2: Reference the private image in your Dockerfile​

Update your Dockerfile to reference the private image:

FROM registry.gitlab.com/your-namespace/your-image:your-tag

Once pushed, Divio will use your saved credentials to authenticate and pull the image during the build process.

Example​

If you push container images to GitLab’s private registry, you can reference them in your Dockerfile like this:

FROM registry.gitlab.com/my-own/private-repository:2.1.3

Divio will authenticate with the registry using the credentials you added in the Control Panel and pull the image securely during the build process.

note
  • Credentials can be deleted and re-added at any time in the Control Panel.
  • Multiple registry credentials can be added if your application uses more than one private registry.

Troubleshooting​

Build fails with “access denied” or “image not found”​

  • Double-check the image path in your Dockerfile. Make sure it includes the full registry domain, repository, and tag.
  • Verify that your credentials are correctly added under Organisation > Container Registries in the Control Panel.
  • If using a personal access token (PAT), confirm it has read/pull access to the image.

Private image referenced, but build still fails​

  • Make sure the image exists and has been pushed to the registry.
  • Confirm that the image path in the FROM instruction is correct and accessible.
  • Try deleting and re-adding the credentials in the Control Panel to rule out input errors.