docs(platform/gitlab): add headings, small rewrite (#31547)

lib/modules/platform/gitlab/readme.md

@@ -2,47 +2,76 @@
 
 ## Authentication
 
-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).
+You can authenticate Renovate to GitLab, with _one_ of these methods:
+
+- [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)
+- [Group Access Token](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html)
+
+### Three ways to authenticate, choose one
 
 To start, create either:
 
 - 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 [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 and update _one_ project. We do not recommend Project Access Tokens, as you need to configure Renovate, and the token, for _each_ 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 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.
+#### Bot or token must have at least developer role
+
+The bot account, or token, must have at least the Developer role.
+The developer role allows Renovate to [create issues and merge requests](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions).
+
+#### If you want Renovate to automerge, give appropriate 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 only maintainers are allowed to merge, give Maintainer role
+
 If merging is restricted to Maintainers, the bot account or token must have the Maintainer role.
 
-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.
+#### Setting up Project Access Tokens or Group Access Tokens
+
+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, project access tokens and group access tokens as _access tokens_ in the instructions that follow.
 
+#### Permissions for access tokens on real runs
+
 For real runs, give the access token these scopes:
 
 - `api`
 - `write_repository`
 - `read_registry` (only if Renovate needs to access the [GitLab Container registry](https://docs.gitlab.com/ee/user/packages/container_registry/))
 
+#### Permissions for access tokens on dry runs
+
 For dry runs, give the access token these scopes:
 
 - `read_api`
 - `read_repository`
 - `read_registry` (only if Renovate needs to access the [GitLab Container registry](https://docs.gitlab.com/ee/user/packages/container_registry/))
 
+#### Letting Renovate use your access token
+
 Let Renovate use your access token by doing _one_ of the following:
 
 - Set your access token as a `token` in your `config.js` file
 - Set your access token as an environment variable `RENOVATE_TOKEN`
 - Set your access token when you run Renovate in the CLI with `--token=`
 
+#### Set `platform=gitlab` in your Renovate config file
+
 Remember to set `platform=gitlab` somewhere in your Renovate config file.
 
-If you're using a private [GitLab container registry](https://docs.gitlab.com/ee/user/packages/container_registry/), you must:
+#### Setting up Renovate for a Private Gitlab container registry
+
+If you use a private [GitLab container registry](https://docs.gitlab.com/ee/user/packages/container_registry/), you must:
 
 - Set the `RENOVATE_HOST_RULES` CI variable to `[{"matchHost": "${CI_REGISTRY}","username": "${GITLAB_USER_NAME}","password": "${RENOVATE_TOKEN}", "hostType": "docker"}]`.
 
@@ -53,6 +82,8 @@ If you're using a private [GitLab container registry](https://docs.gitlab.com/ee
 
 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.
 
+#### Get colored output
+
 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)