# Connect GitLab

At the end of this guide a GitLab.com group is connected to Volobox through a service account, people can link their own GitLab accounts so their pushes carry their identity, and the group's projects are registered for Volobox projects to link. An administrator who may open integration settings and holds **Manage integrations** can do it, together with someone who can manage the GitLab group.

## Before you begin

- A GitLab.com top-level group whose projects Volobox should manage. Connect each unrelated top-level group separately.
- Permission in GitLab to create a service account, add it to the group, create its personal access token, and create an OAuth application in the group.
- A Volobox account with the integrations permission under **Organization settings** and **Manage integrations**. Registering repositories also needs **Manage all code repositories**.

> **Note:** This connection is for GitLab.com groups.

## Prepare the GitLab group

1. In the GitLab group, create a service account.
2. Add the service account to the top-level group with the **Maintainer** role. Subgroups and projects inherit that access.
3. Create a personal access token for the service account with the `api` and `write_repository` scopes. Save the token before leaving GitLab.
4. In the same GitLab group, create a confidential OAuth application with the `api`, `read_user` and `write_repository` scopes.
5. For its redirect URI, copy the **Redirect URI** shown under **Personal OAuth** in Volobox's connect dialog (see the next section) exactly. It ends in `/gitlab/callback` and has no query string.
6. Save the OAuth **Application ID** and **Client secret**.

> **Warning:** The token must be a personal access token created under the group's service account. A personal access token of your own, a group access token or a project access token is not accepted.

## Connect the group

1. Open **Admin** on the left activity rail, then **Settings**, and select the **Integrations** tab of **Organization Settings**.
2. Under **GitLab connections**, select **Connect group**.
3. Enter the full **Group path**, such as `company` or `company/platform`.
4. Enter the service account token.
5. Open **Personal OAuth** and enter both the **Application ID** and the **Client secret**.
6. Select **Connect group**. Volobox checks the token, its scopes, the group, the service account, its Maintainer access and project discovery before it saves the connection.

> **Note:** You can leave **Personal OAuth** blank during the first setup, but people cannot connect their own GitLab accounts until both values are saved.

![Organization Settings, Integrations tab, GitLab connections: the meridian-works/studio group connected through a service account, with its token scopes, personal OAuth set up, the time it was last verified, and Verify, Edit and Remove actions.](https://volobox.io/docs/images/gitlab-integration.light.webp)

*GitLab connections on the Integrations tab: a connected group with its service account, token scopes and verification status, and Verify and Edit.*

## Register repositories

1. In **Organization Settings**, open **Code**, then **Repositories**.
2. Select **Register repository** and choose **GitLab**.
3. Choose the connected group and a project. Projects in nested subgroups are included; archived projects cannot be selected.
4. Confirm the name, default branch and sandbox template, then select **Save**. Volobox creates the project's webhook in GitLab.
5. To link the repository to a Volobox project, open the project's **Settings**, then **Repositories**, and select **Link repository**. There you set up GitLab issue tracking and manual sync.

## Connect your own GitLab account

When the group has **Personal OAuth** set up, each person who works in coding sessions connects GitLab once. Git pushes and `glab` then use that person's GitLab identity; without a personal connection set up, coding uses the group's service account.

1. Open your avatar menu, select **Settings**, then the **Integrations** tab of **Personal Settings**.
2. Connect your GitLab account and approve the authorization on GitLab.

## Later: rotate credentials

1. Create the replacement token or OAuth client secret in GitLab first.
2. Select **Edit** on the connection. Leave an unchanged secret blank, enter only the replacement values, and select **Save**.
3. Select **Verify**.
4. After the OAuth application's credentials change, people reconnect their personal GitLab accounts.

## Check that it works

1. On the connection, select **Verify**. Volobox runs the same live checks as when you connected.
2. On a registered repository, open **Repository actions** and select **Test connection**. It confirms that Volobox can read the default branch.

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| Verification says the token is invalid or inactive | Create a new token for the service account and update the connection. |
| Verification says the token does not belong to a service account | Create the personal access token under the group's service account. |
| Verification says scopes are insufficient | Create a replacement service token with both `api` and `write_repository`. |
| Verification says Maintainer is required | Add the service account directly to the connected top-level group with the **Maintainer** role. |
| Personal GitLab sign-in is unavailable | Save both the OAuth **Application ID** and **Client secret**, with the exact redirect URI Volobox shows. |
| A person's panel shows **Reconnect GitLab** | Their authorization expired or its refresh was rejected. They reconnect under **Personal Settings**, **Integrations**. |
| A repository shows **Webhook needs attention** | Read the reason beside the badge and check that the service token is valid, then edit and save the repository to retry at once. |
| The group was renamed | Edit the connection, enter the new path and save. Volobox keeps the connection only while GitLab's numeric group ID still matches. |

## Next steps

- [From a task to a pull request](/docs/task-to-pull-request)
- [Write a preview manifest](/docs/write-preview-manifest)
- [Coding sessions](/docs/coding)
- [Integrations](/docs/integrations)
