Tokens?

CLA Bot heavily relies on tokens, why is that?

In order to not rely on extra services, the bot is started from within CI/CD pipelines. While each pipeline automatically inherits a CI_JOB_TOKEN, neither its scope nor its role is enough to fulfil all requirements for CLA Bot.

Another reason for the number of tokens is that CLA Bot has to interact with more than one repository in different ways, so a single CI_JOB_TOKEN would not be enough anyway. We try to limit permissions for any one of these tokens to not require "universal access".

As a side effect, your projects sees additional Members for each token. Depending on the use case, a nice name and avatar make CLA Bot look nice.

Security

The tokens that are required for CLA Bot to run have to be provided as CI/CD Variables. Ideally, you would want to "mask" their values to prevent obtaining their contents all too easily. Please be aware that this does not prevent malicious actors that may have injected code into your CI/CD pipelines from gaining access to their content. You will find those variables with 'home' under Settings / CI/CD / Variables.

For this reason, we advise you to keep 'home' separate from 'playground' with limited permissions and an as short as possible members list. 'Playground' will be public and accepting contributions, 'home' will not. So it will separate access tokens from public access.

Types of tokens

CLA Bot requires Project Access Tokens and Pipeline Trigger Tokens. If you want to use the bot's installer, you also need a Personal Access Token to interact with your GitLab instance.

The Personal Access Token

This is only required to run install-bot.
Scope: api
The token is used to connect to your GitLab instance, search/alter/create projects, set up variables/tokens/webhooks, the lot. You find it with your User settings / Access tokens.

The Project Access Tokens

These tokens can be found with the respective projects under Settings / Access tokens.

To access 'playground', you will need the CLA_BOT_API_TOKEN_<id of playground> with:
Scope: api
Role: Developer
This token is used to read project information, check for merge requests, read comments, update comments, and start/resolve discussion threads.

To access 'home', you will need the CLA_BOT_API_TOKEN with:
Scope: read_api
Role: Developer
The token is used to check for already running CI/CD 'Bot' pipelines to avoid overlapping changes to 'playground'. In case multiple bots have been triggered due to different events, they will wait their turn and run one after the other.

Finally, a token CLA_BOT_STORAGE_TOKEN to access 'store' with:
Scope: read_repository, write_repository
Role: Developer / Maintainer
This is used to clone the signature store and commit any changes to it. The actual role depends on whether the branch that holds the information is protected (Maintainer) or not (Developer).

The Pipeline Trigger Token

This is used to trigger the CI/CD pipeline inside 'home'. It does not expire and cannot be used for anything but triggering the CI/CD pipeline. It can be found with 'home' under Settings / CI/CD / Pipeline trigger tokens.

Token lifetime and rotation

GitLab does limit the lifetime of Personal Access Tokens. You can easily "rotate" tokens from the settings of your project. Simply navigate to Settings / Access tokens. One of the listed actions is rotating the tokens value. What this is does is: it keeps scope, role, and name/description of the token, but assigns a new content while updating the lifetime.

Unfortunately this is not quite enough. You will have to update the content of the matching CI/CD variable as well. Find those under Settings / CI/CD / Variables. Until an up-to-date value can be read from there, CLA Bot will not be able to run properly.

Avatars

If you initially "installed" CLA Bot with its installer, you will have been asked whether you want to set up an avatar for the token. Having done that, each interaction (comments, commits) will be associated with the bot's face. To set this up manually, please take a look at the snippets.