GitLab Cloud - Fine-Grained Token

How do I sign-up with GitLab Cloud?

To integrate GitLab with Hivel using a fine-grained Personal Access Token, follow the steps below. This guide is the granular-permission alternative to the broad-scope Personal Access Token process, grants Hivel individual read permissions per resource instead of one of the broad scopes.

Data Access by Hivel

• Hivel accesses the past 30-90 days of commits and pull requests from active repositories during the initial sync.

Authorization Mechanism

• Hivel integrates with GitLab using a fine-grained Personal Access Token.

• You retain full control, access can be revoked at any time by revoking the token in GitLab under Preferences → Access Tokens.

Requirements

• Log in with an admin account that has access to the groups/projects you want to integrate. The token only needs read-only permissions - no write access is required.

Best Practice

1. Opt for a service account rather than an individual-linked account.

Steps to generate a Fine-Grained Personal Access Token on GitLab

Step 1: Prepare a Service Account

1. Log into the GitLab service account:

   • Use a dedicated service account that has access to the required repositories for Hivel integration.

   • Avoid using personal GitLab accounts to ensure only the intended repositories are accessed.

Step 2: Open Access Tokens

1. In your GitLab account, click your avatar in the top-right corner.

2. Select Preferences.

1. On the left sidebar, select Access > Personal access tokens.

   

Step 3:Click on the Generate token dropdown and select Fine-grained token.

Step 4: Configure the Fine-Grained Personal Access Token

1. Enter a name (e.g. Hivel), description and set the longest expiry date your organization's policy allows. (GitLab requires an expiry date on personal access tokens. You can revoke the token manually when the engagement ends.)

2. Under Group and project access, choose between the following three options, based on what you've agreed to share with Hivel per your organization's data-sharing policy:

1. Grant permissions using the Resource and permission selector. It has three tabs: Group and project, User, and Global. Within a tab, the left panel lists resource categories (e.g. Projects, Repository, Groups). Each category row has a ‘›’ arrow - click it to expand the category and reveal its specific sub-permissions as checkboxes underneath. Checking one adds a row for it to the panel on the right.

None of these rows default to Read. After adding a permission, you must open its dropdown on the right-hand table and explicitly set it to Read.

Worked example - selecting Project (Group and project tab):

1. On the Group and project tab, find Projects in the left panel.

2. Click the ‘›’ arrow next to Projects to expand it.

   
3. Check Project in the list that appears.

1. A Project row is added to the panel on the right. Open its dropdown in the right panel and set the “Select permissions” to Read.

Repeat this same expand → check → set-to-Read pattern for every permission below. Where a category needs more than one sub-permission (e.g. Repository), expand it once and check all of them before moving to the next category.

Group and project tab:

• Groups → check Group

• Projects → check Project

• Project Planning → check Work Item

• Repository → check Branch, Commit, Merge Request, Repository

• System Access → check Member

User tab:

• Groups → check Group

• Projects → check Project

• System Access → check Personal Access Token

Global tab:

• System Access → check Metadata

Note: By default, no permission is selected at all. Before moving on, go back through every item in the three lists above and cross-check two things for each: (1) it's actually checked in the left panel, and (2) its row on the right is explicitly set to Read. Any permission you skip, or leave unset, is simply left out of the token entirely - the connection may still work, but whatever that permission covers will be missing or fail for Hivel.

Once every permission above has been cross-checked and set to Read, continue to the next step.

Step 5: Connect in Hivel

1. Copy the generated token immediately, as you won't be able to view it again.

2. Submit the token to Hivel.

Hivel validates the token instantly - if the token is wrong, expired, or missing any of the required permissions, Hivel shows a clear message telling you exactly what the problem is. Generate a new token with the correct permissions and reconnect.

That's it, all done!