How to Use Private Docker Registries with Elestio CI/CD

If you've been running CI/CD pipelines on Elestio with public images, life was already pretty smooth. But the moment you needed to pull from a private registry — your company's internal images, a gated container, anything behind authentication — you hit a wall. That wall is now gone.

Elestio CI/CD now supports private registry credentials for GitHub Container Registry (ghcr.io), GitLab Container Registry (both cloud and self-hosted), and Docker.io. You configure your credentials once, and every pipeline run authenticates automatically.

Why This Matters

Most production workloads don't run on public images. You've got custom-built containers, proprietary dependencies, images you'd rather not publish to the world. Until now, deploying those through Elestio CI/CD meant workarounds — pre-pulling images, baking credentials into scripts, or just giving up and using a different deployment path.

None of that is necessary anymore. You add your registry secret, point your pipeline at the private image, and it just works.

What's Supported

Here's the full breakdown of private registries you can now authenticate with:

That last one is worth highlighting — if you're running your own GitLab instance, Elestio supports it. Just point to your registry domain and authenticate. No restrictions on where your GitLab lives.

How to Set It Up

Setting up a private registry takes about 30 seconds. Here's the process:

1. Open Registry Configuration

In your Elestio CI/CD pipeline settings, navigate to the Registry Secrets section and click Create Registry Configuration Secret.

2. Pick Your Registry

You'll see three tabs: Docker.io, GitHub, and GitLab. Select the one that matches your registry provider.

3. Fill In Your Credentials

Each registry requires four fields:

• Nickname — A label for this credential set (e.g., "production-ghcr" or "internal-gitlab")
• Username — Your registry username
• Password or token — Your authentication token (a personal access token for GitHub, a deploy token for GitLab, or your Docker.io password)
• Repository — The private registry domain (e.g., ghcr.io/your-org or registry.gitlab.com/your-group)

4. Verify and Save

Hit Verify to confirm Elestio can reach your registry with the provided credentials. If verification passes, you're done — your pipelines will automatically use these credentials when pulling images from that registry.

Registry-Specific Tips

GitHub Container Registry (ghcr.io)

You'll need a Personal Access Token (PAT) with read:packages scope. Classic tokens work fine — generate one from your GitHub account under Settings > Developer Settings > Personal Access Tokens. Fine-grained tokens also work, as long as they grant read access to your packages.

For the repository field, use ghcr.io/your-username or ghcr.io/your-org.

GitLab Container Registry

For GitLab Cloud (gitlab.com), a deploy token with both read_registry and read_api scopes is required. The read_registry scope handles image pulls, while read_api is needed for Elestio to verify your credentials and list available images. Create one in your project's Settings > Repository > Deploy Tokens.

For self-hosted GitLab, the process is identical — just use your instance's registry domain instead of registry.gitlab.com. Elestio doesn't lock you into any specific GitLab host. The same read_registry + read_api scopes apply.

Docker.io

If you're pulling private images from Docker Hub, use your Docker Hub username and either your account password or an access token. You can create access tokens from your Docker Hub account under Account Settings > Security. Tokens are recommended over passwords — they're revocable and can be scoped to read-only.

Troubleshooting

Verification fails with "unauthorized" Double-check your token has the right scopes. GitHub needs read:packages, GitLab needs both read_registry and read_api. An expired token will also cause this.

Image pull fails during pipeline run Make sure the repository field matches exactly how you reference the image in your pipeline config. If your image is at ghcr.io/acme/api-server:latest, your repository should be ghcr.io/acme.

Self-hosted GitLab registry not reachable Verify your GitLab instance's container registry is enabled and accessible over HTTPS. Elestio needs to reach it from outside your network — if it's behind a VPN or firewall, you'll need to allow access.

Built Because You Asked

This feature was one of our most requested additions — customers have been asking for private registry support since the early days of Elestio CI/CD. We started with Docker.io, GitHub, and GitLab because that's where the vast majority of private images live, but we're listening. If you need support for additional registries, let us know.

If you're not using Elestio CI/CD yet, it's included with every service deployment on Elestio. You get automated builds, zero-downtime deploys, and now — private registry support out of the box. Deploy any of our 400+ open-source services and your CI/CD pipeline is ready to go.

Thanks for reading. See you in the next one 👋