> For the complete documentation index, see [llms.txt](https://docs.hivel.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hivel.ai/integrations/version-control/gitlab/gitlab-cloud-fine-grained-token.md).

# GitLab Cloud - Fine-Grained Token

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**.

<img src="/files/EjEFbmKRBuAPHmnzaJHG" alt="" height="391" width="277">

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

   <img src="/files/nUc2nqxeoZrvVtNiby5D" alt="" height="531" width="693">

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

<img src="/files/HXhPcbWJUBCa5epULB8y" alt="" height="403" width="652">

### **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:

<div data-with-frame="true"><img src="/files/umv18uYHXBw3u0bn2w8a" alt="" height="235" width="452"></div>

3. 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.

   <img src="/files/z56K4hxobHPNhdMySz1c" alt="" height="374" width="625">
3. Check **Project** in the list that appears.

<img src="/files/Rn9FwwwnQawddxleY6JA" alt="" height="273" width="558">

4. 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**.

<div data-with-frame="true"><img src="/files/TgsTDi98lu41lVUOMnAy" alt=""></div>

<img src="/files/9ZYVnnkaG7t5CeGIT3QK" alt="" height="429" width="711">

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&#x20;

**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!