docs: fix discrepancies and add missing documentation for GitLab provider (#6430)

Co-authored-by: Gergely Bräutigam <gergely.brautigam@sap.com>
Signed-off-by: Alexander Chernov <alexander@chernov.it>

docs/provider/gitlab-variables.md

@@ -2,6 +2,8 @@
 
 External Secrets Operator integrates with GitLab to sync [GitLab Project Variables API](https://docs.gitlab.com/ee/api/project_level_variables.html) and/or [GitLab Group Variables API](https://docs.gitlab.com/ee/api/group_level_variables.html) to secrets held on the Kubernetes cluster.
 
+> **Note**: The GitLab provider is read-only. PushSecret is not supported.
+
 ### Configuring GitLab
 The GitLab API requires an access token, project ID and/or groupIDs.
 
@@ -12,6 +14,7 @@ To create a new access token, go to your user settings and select 'access tokens
 Click 'Create personal access token', and your token will be generated and displayed on screen. Copy or save this token since you can't access it again.
 ![token-created](../pictures/screenshot_gitlab_token_created.png)
 
+> **Note**: Project access tokens and group access tokens are also accepted in place of a personal access token.
 
 ### Access Token secret
 
@@ -26,6 +29,12 @@ Be sure the `gitlab` provider is listed in the `Kind=SecretStore` and the Projec
 
 In order to sync group variables `inheritFromGroups` must be true or `groupIDs` have to be defined.
 
+> **Note**: `inheritFromGroups` and `groupIDs` are mutually exclusive. Setting both fields at the same time causes a validation error. Use `groupIDs` to sync from a fixed list of groups, or `inheritFromGroups: true` to automatically discover all parent groups of the project.
+
+The values in `groupIDs` must be the numeric group ID, not the group path or slug. You can find the numeric ID on the group's General Settings page.
+
+When `inheritFromGroups: true` is set, parent groups are discovered at secret-fetch time via the GitLab Projects API and sorted by full path length, shortest first. This gives the project's direct parent the highest priority among groups. Project variables always take precedence over group variables regardless of this order.
+
 In case you have defined multiple environments in Gitlab, the secret store should be constrained to a specific `environment_scope`.
 
 #### Environment Scope Fallback Behavior
@@ -38,7 +47,7 @@ The GitLab provider implements an intelligent fallback mechanism for environment
 
 **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.
+> **Implementation Note**: This fallback behavior is implemented in the `getVariables` function in `providers/v1/gitlab/provider.go`, where the provider automatically retries with `EnvironmentScope: "*"` when the initial lookup with the specific environment scope returns a 404 Not Found response. The same fallback applies to group variable lookups in `getGroupVariables`.
 
 ```yaml
 {% include 'gitlab-secret-store.yaml' %}
@@ -48,6 +57,54 @@ The GitLab provider implements an intelligent fallback mechanism for environment
 Your project ID can be found on your project's page.
 ![projectID](../pictures/screenshot_gitlab_projectID.png)
 
+#### Custom TLS certificates
+
+If your GitLab instance uses a self-signed or private CA certificate, configure the provider to trust it using one of two options.
+
+**Option 1 -- inline PEM via `caBundle`**: base64-encode your CA certificate and set it directly in the store spec.
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: SecretStore
+metadata:
+  name: gitlab-secret-store
+spec:
+  provider:
+    gitlab:
+      url: https://gitlab.example.com
+      auth:
+        SecretRef:
+          accessToken:
+            name: gitlab-secret
+            key: token
+      projectID: "12345"
+      caBundle: LS0tLS1CRUdJTi...  # base64-encoded PEM certificate
+```
+
+**Option 2 -- reference a Secret or ConfigMap via `caProvider`**: store the PEM certificate in a Kubernetes resource and point the store at it. This avoids embedding the certificate in the store spec and works well with cert-manager or manually provisioned CA bundles.
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: SecretStore
+metadata:
+  name: gitlab-secret-store
+spec:
+  provider:
+    gitlab:
+      url: https://gitlab.example.com
+      auth:
+        SecretRef:
+          accessToken:
+            name: gitlab-secret
+            key: token
+      projectID: "12345"
+      caProvider:
+        type: Secret       # or ConfigMap
+        name: gitlab-ca    # name of the Secret or ConfigMap
+        key: ca.crt        # key inside the resource that holds the PEM certificate
+        # namespace: ...   # required only for ClusterSecretStore
+```
+
 ### Creating external secret
 
 To sync a GitLab variable to a secret on the Kubernetes cluster, a `Kind=ExternalSecret` is needed.
@@ -56,14 +113,73 @@ To sync a GitLab variable to a secret on the Kubernetes cluster, a `Kind=Externa
 {% include 'gitlab-external-secret.yaml' %}
 ```
 
+#### Key normalisation
+
+When using `data:` to look up a single variable by name, hyphens in `remoteRef.key` are silently replaced with underscores before the GitLab API call. For example, `key: my-secret` will look up the GitLab variable named `my_secret`. This normalisation does not apply to `dataFrom`.
+
+#### Extracting a JSON sub-key with `remoteRef.property`
+
+If a GitLab variable holds a JSON string, you can extract a single nested value using `remoteRef.property`. The value is resolved using [GJSON path syntax](https://github.com/tidwall/gjson#path-syntax), so dot-separated paths and array indexing are both supported.
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: ExternalSecret
+metadata:
+  name: gitlab-json-property-example
+spec:
+  refreshInterval: 1h0m0s
+  secretStoreRef:
+    kind: SecretStore
+    name: gitlab-secret-store
+  target:
+    name: gitlab-secret-to-create
+    creationPolicy: Owner
+  data:
+    - secretKey: db-password
+      remoteRef:
+        key: MY_JSON_CONFIG          # GitLab variable whose value is a JSON string
+        property: database.password   # GJSON path into that JSON value
+```
+
 #### Using DataFrom
 
-DataFrom can be used to get a variable as a JSON string and attempt to parse it.
+DataFrom can be used to get a variable as a JSON string and attempt to parse it, or to match multiple variables by name.
+
+**Extracting all keys from a JSON variable** (`dataFrom.extract`):
 
 ```yaml
 {% include 'gitlab-external-secret-json.yaml' %}
 ```
 
+**Matching multiple variables by name regex** (`dataFrom.find`):
+
+```yaml
+apiVersion: external-secrets.io/v1
+kind: ExternalSecret
+metadata:
+  name: gitlab-find-example
+spec:
+  refreshInterval: 1h0m0s
+  secretStoreRef:
+    kind: SecretStore
+    name: gitlab-secret-store
+  target:
+    name: gitlab-secret-to-create
+    creationPolicy: Owner
+  dataFrom:
+    - find:
+        name:
+          regexp: "^PROD_.*"            # required: regexp matched against variable names
+        tags:
+          environment_scope: production  # optional: also filter by environment scope
+```
+
+The following restrictions apply when using `find`:
+
+- `find.name` is mandatory. The provider requires a name regexp to select which variables to sync.
+- `find.tags` only supports the `environment_scope` key. Any other tag key causes an error. Setting `find.tags.environment_scope` while the SecretStore already has an `environment` configured also causes an error, as the two would conflict.
+- `find.path` is not implemented in the GitLab provider and returns an error if set.
+
 ### Getting the Kubernetes secret
 The operator will fetch the project variable and inject it as a `Kind=Secret`.
 ```

docs/snippets/gitlab-secret-store.yaml

@@ -13,6 +13,10 @@ spec:
             name: gitlab-secret
             key: token
       projectID: "**project ID goes here**"
-      groupIDs: ["**groupID(s) go here**"]
-      inheritFromGroups: "**automatically looks for variables in parent groups**"
+      # To sync variables from specific groups, provide their numeric IDs
+      # (visible on the group's General Settings page).
+      # groupIDs and inheritFromGroups are mutually exclusive: set only one.
+      groupIDs: ["12345", "67890"]
+      # Alternatively, automatically inherit variables from all parent groups:
+      # inheritFromGroups: true
       environment: "**environment scope goes here**"