Administration

Guide

Connect GitLab

Connect a GitLab.com group to Volobox with a service account, let each person link their own GitLab account, and register the group's projects.

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.

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

SymptomFix
Verification says the token is invalid or inactiveCreate a new token for the service account and update the connection.
Verification says the token does not belong to a service accountCreate the personal access token under the group's service account.
Verification says scopes are insufficientCreate a replacement service token with both api and write_repository.
Verification says Maintainer is requiredAdd the service account directly to the connected top-level group with the Maintainer role.
Personal GitLab sign-in is unavailableSave both the OAuth Application ID and Client secret, with the exact redirect URI Volobox shows.
A person's panel shows Reconnect GitLabTheir authorization expired or its refresh was rejected. They reconnect under Personal Settings, Integrations.
A repository shows Webhook needs attentionRead 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 renamedEdit the connection, enter the new path and save. Volobox keeps the connection only while GitLab's numeric group ID still matches.

Next steps