> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vidocsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GitLab
> Connect GitLab to Vidoc with a bot user access token and turn on merge request reviews.
Vidoc connects to GitLab through a bot user. You give Vidoc an access token of the bot user. GitLab calls a pull request (PR) a merge request (MR). These pages use "pull request" and "PR" for all platforms.
On GitLab, Vidoc can:
* Review each PR and write a summary comment and inline comments.
* Resolve its own comment threads when a later scan shows that the issue is fixed.
* Read commands and questions that mention the bot user in PR comments.
* Record feedback from replies and 👍/👎 reactions on its comments.
* Show a commit status, when status reporting is on.
For a comparison with other platforms, refer to [Supported platforms](/supported-platforms).
## Requirements
* Vidoc Cloud connects to GitLab.com. To use a self-managed GitLab instance, contact Vidoc.
* A GitLab user for Vidoc (the bot user). The user account must be active.
* An access token of the bot user with the `api` scope.
* The bot user has the **Maintainer** role (or higher) on each project to scan. Vidoc creates project webhooks with this token. The **Developer** role is not sufficient.
* You have the **Admin** role in Vidoc.
Your operators configure the platform connection for the installation (see the installation guide that Vidoc provides). The installation connects to one GitLab instance: GitLab.com or your self-managed GitLab.
The bot user requirements are the same as on Vidoc Cloud:
* The bot user account is active.
* The access token has the `api` scope.
* The bot user has the **Maintainer** role (or higher) on each project to scan.
### Select the token type
You can use one of these token types:
| Token type | Notes |
| ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Personal access token of a dedicated user (recommended) | Create a GitLab user for Vidoc, for example `vidoc`. Invite it to your projects. Create a personal access token with the `api` scope. Developers mention this username to talk to Vidoc. |
| Service account token | Available in Premium and Ultimate, and in Free from GitLab 18.11. Use a personal access token of the service account with the `api` scope. Check the [GitLab service account requirements](https://docs.gitlab.com/user/profile/service_accounts/) for your version and tier. |
| Group access token | This works, but GitLab generates the bot username, for example `group_123_bot_…`. This name is difficult to mention in comments. |
The username of the bot user is the handle that developers mention in PR comments. Select a short name that is easy to type.
## Connect GitLab
You must have the **Admin** role in Vidoc.
In the web app, open the account menu and select **Integrations**. On the **GitLab** card, click **Connect**. You can also start from the **Repositories** page. If GitLab is already connected, click the card, then click **Add connection**.
On Vidoc Cloud, the onboarding flow shows the same steps when you create your organization.
In **Connect GitLab bot account** (step 1 of 2), paste the token in **Bot access token**. Click **Continue**. Vidoc checks the token with GitLab.
In **Select Projects** (step 2 of 2), select the projects to import. Click **Connect selected**.
### Import more projects later
1. Open **Integrations > GitLab**.
2. Open the actions menu of the GitLab account and select **Import repositories**.
The list shows the projects where the bot user is a member. To add a project to the list, add the bot user to the project in GitLab with the **Maintainer** role first.
## Turn on PR reviews for projects
Open **Repositories** in the web app. Turn on the **PR reviews** toggle for each project to scan. You must have the **Developer** role or higher.
When you turn on **PR reviews**:
* Vidoc creates a project webhook in GitLab. The webhook sends push, merge request, and comment events to Vidoc. You do not create it by hand.
* Vidoc indexes the default branch of the project. On the Enterprise plan and on self-hosted installations, Vidoc then runs a first full scan of the default branch. Refer to [Scan types](/how-it-works#scan-types).
* Vidoc then reviews each new PR and each update to a PR.
On Vidoc Cloud, indexing and PR reviews start only when your organization has an active plan.
The **PR comments** toggle is in the actions menu of each repository. When it is off, Vidoc still scans PRs, but it does not write to GitLab. For all repository controls, refer to [Repositories](/web-app/repositories).
## GitLab specifics
| Topic | Behavior on GitLab |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scan triggers | A scan starts when a PR opens, when you push new commits, and when you change the title, description, or labels. Each new scan stops the running scan. |
| Bot handle | The username of the bot user. The summary comment shows the handle to use. |
| Commands | `@ scan`, `rescan`, `restart`, and `help`. The commenter needs the **Developer** role or higher on the project and must not be blocked. A Vidoc account is not necessary. Refer to [Commands](/pull-requests/commands). |
| Questions and "remember" requests | Same permission as commands: the **Developer** role or higher on the project. A Vidoc account is not necessary. |
| Replies on findings | A reply with a clear verdict creates a learning. A false-positive reply also ignores the issue. The GitLab user must be linked to a Vidoc user. Refer to [Feedback](/pull-requests/feedback). |
| Reactions | Vidoc collects 👍 and 👎 on its inline comments. |
| Commit status | When status reporting is on, Vidoc shows a commit status on the head commit. GitLab has no **Run Vidoc** button. Use a command to scan again. |
| Comment formatting | Vidoc comments use alert blocks such as `> [!CAUTION]`. GitLab 17.10 and later show them as colored alerts. Earlier versions show a normal quote. Collapsed sections work. |
## Update credentials
Replace the token before it expires, or after you rotate it in GitLab:
1. Open **Integrations > GitLab**.
2. Open the actions menu of the GitLab account and select **Bot account**.
3. Paste the new token in **Rotate bot access token**.
4. Click **Save bot token**.
If you use a token of a different GitLab user, the bot handle changes. Tell your developers the new handle.
## Troubleshooting
| Symptom | Cause | Fix |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Project import or **PR reviews** fails with 403 | The bot user has a role lower than **Maintainer** on the project, or the token does not have the `api` scope. | Give the bot user the **Maintainer** role on the project or group. Make sure that the token has the `api` scope. Try again. |
| The integration shows `GitLab rejected the stored credential (401 Unauthorized)` | The bot token is revoked or expired. | Add a new token. Refer to [Update credentials](#update-credentials). |
| The GitLab webhook test returns 401 `Invalid webhook token` | The webhook belongs to an old connection, or its secret does not match. | In Vidoc, turn **PR reviews** off and on for the project. In GitLab, delete old Vidoc webhooks. |
| A project is not in the import list | The bot user is not a member of the project. | Add the bot user to the project with the **Maintainer** role. |
| A PR has no Vidoc comment | **PR reviews** or **PR comments** is off for the project, or the scan still runs. | On the **Repositories** page, make sure that **PR reviews** and **PR comments** are on. Wait some minutes, then refer to [When a scan fails](/pull-requests/overview#when-a-scan-fails). |
| The summary comment shows "Currently scanning commit ..." for more than 30 minutes | The scan failed. | Write `@ rescan` as a new PR comment. |
| Vidoc does not answer a command or question | You do not have the **Developer** role or higher on the project, or you mentioned the wrong handle. | Use the handle from the summary comment. Ask a project maintainer for the **Developer** role. |
| Alert blocks show as normal quotes | Your GitLab version is earlier than 17.10. | Read the first bold word of the quote, for example **Fix before merge**. |
| No **Integrations** item in the account menu | You do not have the **Admin** role. | Ask an admin of your organization. |