feat(catalog): add gitlab user ID in user entity

Signed-off-by: Jessica He <jhe@redhat.com>

docs/auth/github/provider.md

@@ -80,6 +80,7 @@ This provider includes several resolvers out of the box that you can use:
 - `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found, it will throw a `NotFoundError`.
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`.
 - `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`.
+- `userIdMatchingUserEntityAnnotation`: Matches the GitHub user ID with the User entity that has a matching `github.com/user-id`. If no match is found, it will throw a `NotFoundError`.
 
 :::note Note
 

docs/auth/gitlab/provider.md

@@ -72,6 +72,7 @@ This provider includes several resolvers out of the box that you can use:
 - `emailMatchingUserEntityProfileEmail`: Matches the email address from the auth provider with the User entity that has a matching `spec.profile.email`. If no match is found, it will throw a `NotFoundError`.
 - `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`.
 - `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found, it will throw a `NotFoundError`.
+- `userIdMatchingUserEntityAnnotation`: Matches the GitLab user ID with the User entity that has a matching `gitlab.com/user-id` annotation (or `{integration-host}/user-id` for self-hosted GitLab instances). If no match is found, it will throw a `NotFoundError`.
 
 :::note Note
 

docs/features/software-catalog/well-known-annotations.md

@@ -251,6 +251,46 @@ browser when viewing that user.
 This annotation can be used on a [User entity](descriptor-format.md#kind-user)
 to note that it originated from that user on GitHub.
 
+### github.com/user-id
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    github.com/user-id: '123456'
+```
+
+The value of this annotation is the numeric user ID that identifies a user on
+[GitHub](https://github.com) (either the public one, or a private GitHub
+Enterprise installation) that is related to this entity. Unlike the username,
+which can be changed by the user, the user ID is immutable.
+
+This annotation can be used on a [User entity](descriptor-format.md#kind-user)
+to note that it originated from that user on GitHub. It enables the
+`userIdMatchingUserEntityAnnotation` sign-in resolver to match users by their
+GitHub user ID during authentication.
+
+### gitlab.com/user-id
+
+```yaml
+# Example:
+metadata:
+  annotations:
+    gitlab.com/user-id: '123456'
+```
+
+The value of this annotation is the numeric user ID that identifies a user on
+[GitLab](https://gitlab.com) (either the public one, or a private GitLab
+installation) that is related to this entity. For self-hosted GitLab instances,
+the annotation key will be `{integration-host}/user-id` where
+`{integration-host}` is the hostname of your GitLab instance. Unlike the
+username, which can be changed, the user ID is immutable.
+
+This annotation can be used on a [User entity](descriptor-format.md#kind-user)
+to note that it originated from that user on GitLab. It enables the
+`userIdMatchingUserEntityAnnotation` sign-in resolver to match users by their
+GitLab user ID during authentication.
+
 ### gocd.org/pipelines
 
 ```yaml