docs(gitlab): clarify limited scope of usage of Deploy Tokens (#30787)

Co-authored-by: Rhys Arkins <rhys@arkins.net>

lib/modules/platform/gitlab/readme.md

@@ -2,21 +2,25 @@
 
 ## Authentication
 
-You can authenticate Renovate to GitLab, with a Personal Access Token, or Group Access Token.
+You can authenticate Renovate to GitLab, with a [Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), [Project Access Token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) or [Group Access Token](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html).
 
 To start, create either:
 
-- a [Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) for the bot account
-- or a [Group Access Token](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#bot-users-for-groups) for the bot account
-- or a [Deploy Token](https://docs.gitlab.com/ee/user/project/deploy_tokens/index.html) for the bot account
+- a [Personal Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#create-a-personal-access-token) for the bot account
+- or a [Project Access Token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#create-a-project-access-token) if Renovate only needs to check/update one project (usually not recommended as it requires configuring Renovate and tokens once per project)
+- or a [Group Access Token](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#create-a-group-access-token-using-ui) to the group Renovate will be working on
 
-The bot account must have at least the Developer role in order to [create issues and merge requests](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions).
-If you are using automerge, the bot account must have the appropriate ["Allowed to merge" permission on the protected branch](https://docs.gitlab.com/ee/user/project/protected_branches.html#require-everyone-to-submit-merge-requests-for-a-protected-branch) of your projects.
-If merging is restricted to Maintainers, the bot account must have the Maintainer role.
+The bot account or token must have at least the Developer role in order to [create issues and merge requests](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions).
+If you are using automerge, the bot account or token must have the appropriate ["Allowed to merge" permission on the protected branch](https://docs.gitlab.com/ee/user/project/protected_branches.html#require-everyone-to-submit-merge-requests-for-a-protected-branch) of your projects.
+If merging is restricted to Maintainers, the bot account or token must have the Maintainer role.
 
-If you are using a group access token, to keep using the same GitLab-generated bot user you must [rotate/refresh the Group Access Token](https://docs.gitlab.com/ee/api/group_access_tokens.html#rotate-a-group-access-token) _before_ the token's expiry date.
+If you are using a project access token or a group access token, GitLab creates an [internal](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html#bot-users-for-projects) [bot](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html#bot-users-for-groups) user for you.
+This bot user is the one that will be used to create merge requests and issues.
+Use the name and email of this bot user to configure Renovate when [verifing users using push rules](#verifying-users-using-push-rules).
+For group access tokens, an expiration date is required, unlike project access tokens where it is optional.
+To keep using the same GitLab-generated bot account you must [rotate/refresh the Group Access Token](https://docs.gitlab.com/ee/api/group_access_tokens.html#rotate-a-group-access-token) _before_ the token's expiry date.
 
-We refer to personal access tokens and group access tokens as _access tokens_ in the instructions that follow.
+We refer to personal access tokens, project access tokens and group access tokens as _access tokens_ in the instructions that follow.
 
 For real runs, give the access token these scopes:
 
@@ -44,6 +48,8 @@ If you're using a private [GitLab container registry](https://docs.gitlab.com/ee
 - Make sure the user that owns the access token is a member of the corresponding GitLab projects/groups with the right permissions.
 - Make sure the access token has the `read_registry` scope.
 
+You may also use a dedicated [Deploy Token](https://docs.gitlab.com/ee/user/project/deploy_tokens/) instead of using `RENOVATE_TOKEN` as the password in the above host rule example.
+
 You may want to set `FORCE_COLOR: 3` or `TERM: ansi` to the job, in order to get colored output.
 [GitLab Runner runs the container’s shell in non-interactive mode, so the shell’s `TERM` environment variable is set to `dumb`.](https://docs.gitlab.com/ee/ci/yaml/script.html#job-log-output-is-not-formatted-as-expected-or-contains-unexpected-characters)
 
@@ -63,5 +69,9 @@ By setting the server version yourself, you save a API call that fetches the ser
 
 ## Multiple merge request assignees
 
-Due to licensing restrictions [multiple assignees](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html) are only available in GitLab Premium self-managed, GitLab Premium SaaS, and higher tiers.
+[Multiple assignees](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html) are only available on GitLab Premium and Ultimate tiers.
 Because of a safeguard in [GitLab's API](https://github.com/renovatebot/renovate/pull/14212#issuecomment-1040189712) if multiple assignees are set, but not available to the project, only the first assignee will be applied.
+
+## Verifying users using push rules
+
+When verifying users using [push rules](https://docs.gitlab.com/ee/user/project/repository/push_rules.html#verify-users), you must use the name and email of the bot user for `gitAuthor`.