For Febrary 2025, official wiki doesn’t have any information about GitLab registry support, LLMs don’t know any way to make it work as well, but… it’s possible and it works.
If you’re reading this, you probably already know why we use the registry. You can skip the long part and scroll down to the instructions.
What is docker registry?
It is a storage with our ready docker images.
We build once and use prepared images anytime. We don’t have to waste time and resources for building our image each time on each new machine for each deploy.
Registry is like… a freezer with infinite pizza. Cook once — take out as many times as you want. Same pizza. Every time.
You don’t wait, you don’t worry — just grab and go.
Build every time costs you at least two things:
Time - because every deploy is a cooking session.
Consistency - because every cooking session is a little different.
Same recipe, but different hands or different day sometimes can give you different result. And that’s a problem.
Why we need registry?
As I already mentioned, registry helps us to store built docker images of your apps without rebuilding build of them for each deploy from sources.
The one of main advantages is consistency. Immutable artifact. (build once, run anywhere, remember?
You always have exactly the same artifact, which means you can be sure that what you tested is exactly what you deployed. Everything else follows from this:
- Speed. Skip build step on deploy. Just pull and run.
- Low server load. Your build runs on GitLab Runner. The build process can’t affect your app server at all.
- Simple rollback. Older versions are always there, just pull a previous tag.
- Security. Small bonus. Source code never touches the production server.
In the end, this is the industry standard. The big guys do it this way for a reason.
P.S. It’s worth noting that an image might be built for the wrong platform, but this is usually caught and fixed during the initial setup — or solved entirely by using multi-platform builds. Also, for true immutability, it’s better to pin versions by digest rather than by tag, since tags can technically be overwritten.
How to add Gitlab registry to Dokploy?
To configure a Gitlab Container Registry, you need to fill the form (Add a external registry modal) with the following details:
- Insert the Registry Name eg. Gitlab-registry
- Go to https://gitlab.com/-/user_settings/personal_access_tokens and click on Add new token.
- Insert Token name eg. dokploy
- Set Expiration date
- Select follow scope: read_registry
- Click to Generate token
- Copy the access token, comeback to Dokploy and paste it in Password field
- Registry URL: set registry.gitlab.com
- Username: set gitlab group as username, eg. greenKit-group Attentions: You must use group, not login. If you login greenKit you must set greenKit-group
- Image Prefix: Left empty
- Click on Create to save the registry
Be attention: Modal window have Test registry button, but for GitLab registry it always return “Registry Tested Successfully”. With invalid data too.
Actual for v0.26.7 at least.
Top comments (2)
Really helpful write-up — especially because this is exactly the kind of “it should be documented, but isn’t” integration that people waste hours on. Your “freezer with infinite pizza” analogy lands well, and I like that you didn’t stop at “it works” but also explained the why (immutability, speed, rollback, and keeping source off prod).
Nice work — this will save a bunch of people time, and it’s a great example of documenting the sharp edges the official docs skip. Keep it up :)
Thanks! :)