From 135e71017e4f2e934c15748e7fd178fb02790ff4 Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Tue, 1 Oct 2024 17:43:40 +0200 Subject: [PATCH] docs(platform/gitlab): add headings, small rewrite (#31547) --- lib/modules/platform/gitlab/readme.md | 43 +++++++++++++++++++++++---- 1 file changed, 37 insertions(+), 6 deletions(-) diff --git a/lib/modules/platform/gitlab/readme.md b/lib/modules/platform/gitlab/readme.md index 073bde6ffedb7f..cff27430d110e4 100644 --- a/lib/modules/platform/gitlab/readme.md +++ b/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)