> 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-server-integration/gitlab-server-fine-grained-token.md). # GitLab Server - Fine-grained token **Data Access by Hivel** * Hivel accesses the past 60-90 days of commits and pull requests from active repositories during the initial sync. **Authorization Mechanism** * Hivel employs GitLab Server's **personal access token** for authentication. * Users maintain full control and can withdraw access by revoking the Personal Access Token. **Effortlessly Connect Your GitLab Server with Hivel** This easy-to-follow guide will lead you through each step, ensuring a smooth and efficient integration process to unlock efficiency insights across your org. ### **Step 1: Gather Your GitLab Server Details** First things first, let's get some essential information from your GitLab Server: * **GitLab Server URL**: This is your gateway to accessing your GitLab Server. Look for an address in the format of `https://{your-git-domain}.com/`. Don't forget to replace `{your-git-domain}` with your actual domain. * **GitLab Server Version**: Compatibility is key, and knowing your GitLab Server version is crucial. Here's how to find it: * Head over to your GitLab Server interface. * Click on the 'Help' section. It’s usually at the end of your GitLab URL, like this: `/help`. * You'll see your version info displayed, typically in the format of "GitLab Community Edition {x.x.x} / GitLab Enterprise Edition {x.x.x}". ### **Step 2: Whitelist Necessary IP Addresses** For a secure and uninterrupted connection, make sure to whitelist the following IP addresses: * **Mandatory IPs**: * 107.23.139.76 * 3.219.89.23 * **Recommended but Optional IPs**: * 45.119.114.218 * 183.82.116.218 ### **Step 3: 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 4: 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 5: Click on the Generate token dropdown and select Fine-grained token.**

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

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.

3. Check **Project** in the list that appears.

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

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 7: Connect in Hivel** 1. **Copy the generated token** immediately, as you won't be able to view it again. 2. **Submit:**\ a. GitLab token\ b. Email\ c. base URL

Obtaining base URL:

Open your GitLab dashboard or any project page and copy only the base URL from your browser’s address bar, excluding the project name and anything that follows it (e.g., https://company.com). For detailed instructions, How to Find Your GitLab Server URL?

\ d. username 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! *** **Continue setting up your integrations** Now that GitLab Server is connected, connect the rest of your on-prem tools to complete your setup - [Back to Integrations](https://docs.hivel.ai/integrations#on-prem-server-integrations).