docs(gitlab-variables): document environment scope fallback (#5300)

* docs(gitlab-variables): document environment scope fallback

Added details about environment scope fallback behavior for GitLab provider.

Signed-off-by: Sinyx <sinyx.contact@gmail.com>
Signed-off-by: s1nyx <sinyx.contact@gmail.com>

* docs(gitlab-variables): add implementation note for environment scope fallback behavior

Signed-off-by: s1nyx <sinyx.contact@gmail.com>

---------

Signed-off-by: Sinyx <sinyx.contact@gmail.com>
Signed-off-by: s1nyx <sinyx.contact@gmail.com>
Co-authored-by: Gergely Brautigam <skarlso777@gmail.com>

docs/provider/gitlab-variables.md

@@ -28,6 +28,18 @@ In order to sync group variables `inheritFromGroups` must be true or `groupIDs`
 
 In case you have defined multiple environments in Gitlab, the secret store should be constrained to a specific `environment_scope`.
 
+#### Environment Scope Fallback Behavior
+
+The GitLab provider implements an intelligent fallback mechanism for environment scopes:
+
+1. **Primary lookup**: When you configure a specific `environment` in your SecretStore (example: `environment: "production"`), the provider first tries to find variables with that exact environment scope.
+2. **Automatic fallback**: If no variable is found with the specific environment scope, the provider automatically falls back to variables with "All environments" scope (`*` wildcard).
+3. **Priority order**: Variables with specific environment scopes take precedence over wildcard variables when both exist.
+
+**Example**: If your SecretStore has `environment: "production"` but your GitLab variable is set to "All environments", the variable will still be successfully retrieved through the fallback mechanism.
+
+> **Implementation Note**: This fallback behavior is implemented in the [`getVariables` function](https://github.com/external-secrets/external-secrets/blob/636ce0578dda4a623a681066def8998a68b051a6/pkg/provider/gitlab/provider.go#L134-L151) where the provider automatically retries with `EnvironmentScope: "*"` when the initial lookup with the specific environment scope returns a 404 Not Found response.
+
 ```yaml
 {% include 'gitlab-secret-store.yaml' %}
 ```