docs(renovate-bot): Document Renovate's access tokens in detail.

d945ad90 · Florian Forster · ec188cc5 · d945ad90
Unverified Commit d945ad90 authored 3 months ago by Florian Forster
--- a/renovate-bot.md
+++ b/renovate-bot.md
@@ -25,14 +25,101 @@ to only be accessible on the default protected branch.
 For legacy project configurations, the following manual setup is required:
  
 1. Create a [Project Access Token](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html) with `api` and `write_repository` scope
-2. Make it available in your CI environment via the `RENOVATE_GITLAB_TOKEN` environment variable through the CI/CD Variables settings. Make sure the variable is **Protected** and **Masked**.
-
-   Note: you can use Group Access Tokens and Group CI/CD variables, instead of Project-level ones should you choose.
+2. Create a GitLab token to use by Renovate. There are multiple options, see [Access Token](#access-token) for details.
 3. Lookup the GitHub Personal Access token from [1Password Production Vault](https://gitlab.1password.com/vaults/7xbs54owvjux3cypztlhyetej4/allitems/53z2zuf7urh7hoy3nqeqsei27e) and save it into the CI environment variable `RENOVATE_GITHUB_TOKEN`. Make sure the variable is **Protected** and **Masked**.
 4. Create a CI Pipeline Schedule called `Renovatebot` with a daily schedule, eg `0 1 * * *`. Ensure that the CI Pipeline schedule includes a variable, `RENOVATE_SCHEDULED` with a value of `1`.
  
   Note: Renovate Bot will only run on `gitlab.com`. For projects that are mirrored to other GitLab instances, the task will not run.
  
+### Access Token
+
+There are four ways to configure the access token used by Renovate. There are in descending order of priority:
+
+1. The `vault` input when including `renovate-bot.yml`.
+   This input is used verbatim and needs to include the secret's field as well as the vault mount.
+
+   For example:
+
+   ```yaml
+     - project: 'gitlab-com/gl-infra/common-ci-tasks'
+       ref: v2.41.1  # renovate:managed
+       file: renovate-bot.yml
+       inputs:
+         vault: "gitlab-com/gitlab-com/gl-infra/renovate/renovate-ci/renovate/gitlab-com/token@ci"
+   ```
+2. The `VAULT_RENOVATE_GITLAB_TOKEN_PATH` variable.
+   This variable holds only the vault path; the secret field is `token` and the Vault mount is `ci`.
+   This is the recommended way to override the default behavior if required.
+
+   <details>
+   <summary>For example, to use a Group Access Token (the main reason to override the default behavior), you'd add something like the following to the [infra-mgmt repository](https://gitlab.com/gitlab-com/gl-infra/infra-mgmt/):</summary>
+
+   ```hcl
+   module "group_infra_platform_runway_renovate_bot" {
+     source  = "ops.gitlab.net/gitlab-com/group/gitlab//modules/access-token"
+     version = "1.2.0"
+
+     group_id = module.group_infra_platform_runway.id
+     name     = "Runway Renovate Robot"
+
+     scopes       = ["api", "read_registry", "write_repository"]
+     access_level = "maintainer"
+
+     expires_after_days = 90
+     rotate_after_days  = 60
+
+     vault_kv_secret = {
+       store      = true
+       name       = "renovate-bot"
+       auth_path  = local.vault_auth_path
+       group_path = module.group_infra_platform_runway.full_path
+     }
+   }
+
+   resource "gitlab_group_variable" "infra-platform-runway-renovate-gitlab-token" {
+     group             = module.group_infra_platform_runway.id
+     key               = "VAULT_RENOVATE_GITLAB_TOKEN_PATH"
+     description       = "Path to the group access token used by Renovate in all Runway projects."
+     value             = module.group_infra_platform_runway_renovate_bot.vault_secret_path
+     protected         = false # Used in MRs opened by Renovate
+     masked            = false
+     raw               = true
+     environment_scope = "*"
+   }
+   ```
+   </details>
+3. The `RENOVATE_GITLAB_TOKEN` variable holds the access token directly.
+   This option exists primarily for backwards compatibility and its use is discouraged.
+   When using this option, ensure that tokens get automatically rotated at least every 90 days.
+   We recommend to use the [project access token](https://ops.gitlab.net/gitlab-com/gl-infra/terraform-modules/gitlab/project/-/tree/main/modules/access-token) or [group access token](https://ops.gitlab.net/gitlab-com/gl-infra/terraform-modules/gitlab/group/-/tree/main/modules/access-token) module to manage access tokens in the [infra-mgmt repository](https://gitlab.com/gitlab-com/gl-infra/infra-mgmt/).
+   Make sure the variable is **Protected** and **Masked**.
+4. **Default:** The token is read from the `access_tokens/${VAULT_SECRETS_PATH}/renovate-bot` Vault path, using the field `token` and the Vault mount `ci`.
+   We recommend that you use the [GitLab project Terraform module](https://ops.gitlab.net/gitlab-com/gl-infra/terraform-modules/gitlab/project), which configures the project correctly.
+
+   <details>
+   <summary>The following (partial) config will set up everything that you need:</summary>
+
+   ```hcl
+   module "project_provisioner" {
+     source  = "ops.gitlab.net/gitlab-com/project/gitlab"
+     version = "5.11.0"
+
+     # Create access tokens for common-ci-task
+     common_ci_tasks = {
+       enabled = true
+     }
+
+     # Store access tokens in Vault
+     vault = {
+       enabled   = true
+       auth_path = local.vault_auth_path
+     }
+   }
+   ```
+   </details>
+
+Note: you can use Group Access Tokens and Group CI/CD variables, instead of Project-level ones if required.
+
 ## Configuration
  
 1. Ensure that a `validate` and `renovate_bot` stages exists in your `.gitlab-ci.yml` configuration