diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index a2c9fff..55abbd1 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -90,12 +90,22 @@ build_image:
         echo "Waiting for Docker daemon..."
         sleep 1
       done
-    # Prefer GitLab's built-in registry variables, but allow explicit fallbacks
-    # so the pipeline can publish to any OCI-compatible registry.
-    - export REGISTRY_HOST="${CI_REGISTRY:-${REGISTRY_HOST:-}}"
-    - export REGISTRY_USER="${CI_REGISTRY_USER:-${REGISTRY_USER:-}}"
-    - export REGISTRY_PASSWORD="${CI_REGISTRY_PASSWORD:-${REGISTRY_PASSWORD:-}}"
-    - export IMAGE_REPOSITORY="${CI_REGISTRY_IMAGE:-${REGISTRY_IMAGE:-}}"
+    # Use one registry mode at a time:
+    # 1) explicit REGISTRY_* vars for external/custom registries
+    # 2) GitLab's built-in CI_REGISTRY_* vars for the integrated registry
+    - |
+      if [ -n "${REGISTRY_HOST:-}${REGISTRY_USER:-}${REGISTRY_PASSWORD:-}${REGISTRY_IMAGE:-}" ]; then
+        test -n "${REGISTRY_HOST:-}" || { echo "REGISTRY_HOST is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        test -n "${REGISTRY_USER:-}" || { echo "REGISTRY_USER is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        test -n "${REGISTRY_PASSWORD:-}" || { echo "REGISTRY_PASSWORD is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        test -n "${REGISTRY_IMAGE:-}" || { echo "REGISTRY_IMAGE is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        export IMAGE_REPOSITORY="$REGISTRY_IMAGE"
+      else
+        export REGISTRY_HOST="${CI_REGISTRY:-}"
+        export REGISTRY_USER="${CI_REGISTRY_USER:-}"
+        export REGISTRY_PASSWORD="${CI_REGISTRY_PASSWORD:-}"
+        export IMAGE_REPOSITORY="${CI_REGISTRY_IMAGE:-}"
+      fi
     - test -n "$REGISTRY_HOST" || { echo "Registry host is not set. Configure CI_REGISTRY or REGISTRY_HOST."; exit 1; }
     - test -n "$REGISTRY_USER" || { echo "Registry user is not set. Configure CI_REGISTRY_USER or REGISTRY_USER."; exit 1; }
     - test -n "$REGISTRY_PASSWORD" || { echo "Registry password is not set. Configure CI_REGISTRY_PASSWORD or REGISTRY_PASSWORD."; exit 1; }
@@ -133,10 +143,19 @@ deploy_to_vps:
   needs:
     - build_image
   before_script:
-    - export REGISTRY_HOST="${CI_REGISTRY:-${REGISTRY_HOST:-}}"
-    - export REGISTRY_USER="${CI_REGISTRY_USER:-${REGISTRY_USER:-}}"
-    - export REGISTRY_PASSWORD="${CI_REGISTRY_PASSWORD:-${REGISTRY_PASSWORD:-}}"
-    - export IMAGE_REPOSITORY="${CI_REGISTRY_IMAGE:-${REGISTRY_IMAGE:-}}"
+    - |
+      if [ -n "${REGISTRY_HOST:-}${REGISTRY_USER:-}${REGISTRY_PASSWORD:-}${REGISTRY_IMAGE:-}" ]; then
+        test -n "${REGISTRY_HOST:-}" || { echo "REGISTRY_HOST is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        test -n "${REGISTRY_USER:-}" || { echo "REGISTRY_USER is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        test -n "${REGISTRY_PASSWORD:-}" || { echo "REGISTRY_PASSWORD is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        test -n "${REGISTRY_IMAGE:-}" || { echo "REGISTRY_IMAGE is not set. Configure all REGISTRY_* variables together."; exit 1; }
+        export IMAGE_REPOSITORY="$REGISTRY_IMAGE"
+      else
+        export REGISTRY_HOST="${CI_REGISTRY:-}"
+        export REGISTRY_USER="${CI_REGISTRY_USER:-}"
+        export REGISTRY_PASSWORD="${CI_REGISTRY_PASSWORD:-}"
+        export IMAGE_REPOSITORY="${CI_REGISTRY_IMAGE:-}"
+      fi
     - test -n "$REGISTRY_HOST" || { echo "Registry host is not set. Configure CI_REGISTRY or REGISTRY_HOST."; exit 1; }
     - test -n "$REGISTRY_USER" || { echo "Registry user is not set. Configure CI_REGISTRY_USER or REGISTRY_USER."; exit 1; }
     - test -n "$REGISTRY_PASSWORD" || { echo "Registry password is not set. Configure CI_REGISTRY_PASSWORD or REGISTRY_PASSWORD."; exit 1; }
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
index 3c5cf5a..e8c352d 100644
--- a/docs/DOCKER.md
+++ b/docs/DOCKER.md
@@ -189,6 +189,8 @@ If you want GitLab CI to build once and deploy by pulling a prebuilt image on th
 - Explicit registry variables:
   Set `REGISTRY_HOST`, `REGISTRY_USER`, `REGISTRY_PASSWORD`, and `REGISTRY_IMAGE` yourself. This works for GitLab Registry, Docker Hub, GHCR, or another OCI registry.
 
+If `REGISTRY_*` variables are set, the CI pipeline now uses them as a complete override and requires all four values. If they are unset, the pipeline falls back to GitLab's `CI_REGISTRY_*` variables.
+
 Example explicit values for a local registry exposed through Traefik:
 
 ```text