From ab247bbb62583065ee8b053d2f28f358a5ce1c6d Mon Sep 17 00:00:00 2001
From: Nico Rausch <rausch.nico@gmail.com>
Date: Mon, 5 Jan 2026 13:53:54 +0100
Subject: [PATCH] Clarify Container Registry Docs

Update the Container Registry Documentation to explicitly state 2.x as registry version or include an optional JWKS file to use v3.
---
 docs/container_registry.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/docs/container_registry.md b/docs/container_registry.md
index f0f99189b..aab3e0827 100644
--- a/docs/container_registry.md
+++ b/docs/container_registry.md
@@ -65,11 +65,18 @@ creation. This information is not used at all.
 
 #### Update docker-compose.yml
 
+> [!important]
+> Docker Registry v3 is currently not compatible with the JWT tokens signed by GitLab.
+> The example below uses `registry:2` to avoid issues in validating the token.
+> 
+> Alternatively, you can generate a JWKS file and specify it as `REGISTRY_AUTH_TOKEN_JWKS`
+> to run `registry:latest`. Further information can be found [here](https://github.com/cesanta/docker_auth/issues/386).
+
 First add the configuration for the registry container to your `docker-compose.yml`.
 
 ```yaml
     registry:
-        image: registry
+        image: registry:2
         restart: always
         expose:
             - "5000"
@@ -251,7 +258,7 @@ storage:
  ...
  registry:
     restart: always
-    image: registry:2.4.1
+    image: registry:2.8.3
     volumes:
      - ./certs:/certs
     environment:
@@ -365,7 +372,7 @@ docker run --name registry -d \
 --env 'REGISTRY_AUTH_TOKEN_ISSUER=gitlab-issuer' \
 --env 'REGISTRY_AUTH_TOKEN_ROOTCERTBUNDLE=/certs/registry-auth.crt' \
 --env 'REGISTRY_STORAGE_DELETE_ENABLED=true' \
-registry:2.4.1
+registry:2.8.3
 ```
 
 - **Step 6**: Start the image