Update GitLab Org Data docs

Signed-off-by: Stephen Barry <sbarry@poppulo.com>

docs/integrations/gitlab/org.md

@@ -58,8 +58,6 @@ amount of data, this can take significant time and resources.
 The token used must have the `read_api` scope, and the Users and Groups fetched
 will be those visible to the account which provisioned the token.
 
-**NOTE**: If any groups that are being ingested are empty groups and the user which provisioned the token is shared with a higher level group via [group sharing](https://docs.gitlab.com/ee/user/group/manage.html#share-a-group-with-another-group) and you don't see the expected number of `Group` entities in the catalog you may be hitting this [Gitlab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/267996).
-
 ```yaml
 catalog:
   providers:
@@ -67,11 +65,52 @@ catalog:
       yourProviderId:
         host: gitlab.com
         orgEnabled: true
-        group: org/teams # Required for gitlab.com. Optional for self managed. Must not end with slash. Accepts only groups under the provided path (which will be stripped)
+        group: org/teams # Required for gitlab.com when `orgEnabled: true`. Optional for self managed. Must not end with slash. Accepts only groups under the provided path (which will be stripped)
         groupPattern: '[\s\S]*' # Optional. Filters found groups based on provided pattern. Defaults to `[\s\S]*`, which means to not filter anything
 ```
 
+### Groups
+
 When the `group` parameter is provided, the corresponding path prefix will be
 stripped out from each matching group when computing the unique entity name.
 e.g. If `group` is `org/teams`, the name for `org/teams/avengers/gotg` will be
 `avengers-gotg`.
+
+For gitlab.com, when `orgEnabled: true`, the `group` parameter is required in
+order to limit the ingestion to a group within your organisation. `Group`
+entities will only be ingested for the configured group, or it's descendant groups,
+but not any ancestor groups higher than the configured group path. Only groups
+which contain members will be ingested.
+
+### Users
+
+For self hosted, all `User` entities are ingested from the entire instance.
+
+For gitlab.com `User` entities for users who have [direct or inherited membership](https://docs.gitlab.com/ee/user/project/members/index.html#membership-types)
+of the top-level group for the configured group path will be ingested.
+
+### Limiting `User` and `Group` entity ingestion in the provider
+
+Optionally, you can limit the entity types ingested by the provider when using
+`orgEnabled: true` with the following `rules` configuration to limit it to only
+`User` and `Group` entities.
+
+```yaml
+catalog:
+  providers:
+    gitlab:
+      yourOrgDataProviderId:
+        host: gitlab.com
+        orgEnabled: true
+        group: org/teams
+        rules:
+          - allow: [Group, User]
+```
+
+## Troubleshooting
+
+**NOTE**: If any groups that are being ingested are empty groups (i.e. do not
+contain any projects) and the user which provisioned the token is shared with a
+higher level group via [group sharing](https://docs.gitlab.com/ee/user/group/manage.html#share-a-group-with-another-group)
+and you don't see the expected number of `Group` entities in the catalog you may
+be hitting this [Gitlab issue](https://gitlab.com/gitlab-org/gitlab/-/issues/267996).